admin-valentin/agent-ecosystem
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(product-docs): add zh, es, ja, fr, de doc translations

Browse source 
Localize the VitePress docs into Simplified Chinese, Spanish, Japanese,
French and German (18 pages each), mirroring the existing en/ru structure.

- generate the 5 new locales in config.ts from a single strings table
  (nav, sidebar, search, footer, docFooter, outline, editLink) with
  locale-prefixed links
- rework DocsCardGrid from the binary isRu check to a per-locale map so
  the home cards render translated copy and prefixed links for every locale
This commit is contained in:
777genius 2026-05-31 17:50:54 +03:00
parent aa068efc68
commit 95e0f34d31
92 changed files with 11805 additions and 32 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

469
landing/product-docs/.vitepress/config.ts
View file

@ -149,6 +149,471 @@ const ruNav: DefaultTheme.NavItem[] = [
{ text: "Скачать", link: ruDownloadUrl, target: "_self", noIcon: true }
];
// Additional locales (zh, es, ja, fr, de) are generated from a single strings table
// so every locale stays structurally identical to the English/Russian sidebars and navs.
interface DocsLocaleStrings {
siteTitle: string;
siteDescription: string;
nav: { guide: string; developers: string; reference: string; troubleshooting: string; download: string };
sidebarGroups: { start: string; guide: string; operations: string; developers: string; reference: string };
sidebarItems: {
installation: string;
quickstart: string;
runtimeSetup: string;
createTeam: string;
agentWorkflow: string;
codeReview: string;
mcpIntegration: string;
teamBriefExamples: string;
gitWorktreeStrategy: string;
troubleshooting: string;
developerHub: string;
concepts: string;
providersRuntimes: string;
contributorArchitecture: string;
releaseNotes: string;
privacyLocalData: string;
faq: string;
};
ui: {
searchButton: string;
searchAria: string;
noResults: string;
selectText: string;
navigateText: string;
closeText: string;
footerMessage: string;
docFooterPrev: string;
docFooterNext: string;
outlineLabel: string;
darkModeSwitchLabel: string;
lightModeSwitchTitle: string;
darkModeSwitchTitle: string;
lastUpdatedText: string;
editLinkText: string;
};
}
interface DocsLocaleDefinition {
loc: string;
lang: string;
label: string;
strings: DocsLocaleStrings;
}
const additionalLocales: DocsLocaleDefinition[] = [
{
loc: "zh",
lang: "zh-Hans",
label: "简体中文",
strings: {
siteTitle: "Agent Teams 文档",
siteDescription: "Agent Teams 文档，这是一款用于编排 AI 智能体的本地桌面应用。",
nav: { guide: "指南", developers: "开发者", reference: "参考", troubleshooting: "故障排查", download: "下载" },
sidebarGroups: { start: "开始", guide: "指南", operations: "运维", developers: "开发者", reference: "参考" },
sidebarItems: {
installation: "安装",
quickstart: "快速开始",
runtimeSetup: "运行时设置",
createTeam: "创建团队",
agentWorkflow: "智能体工作流",
codeReview: "代码审查",
mcpIntegration: "MCP 集成",
teamBriefExamples: "团队简报示例",
gitWorktreeStrategy: "Git 与 worktree 策略",
troubleshooting: "故障排查",
developerHub: "开发者中心",
concepts: "概念",
providersRuntimes: "提供方与运行时",
contributorArchitecture: "贡献者架构",
releaseNotes: "发布说明",
privacyLocalData: "隐私与本地数据",
faq: "常见问题"
},
ui: {
searchButton: "搜索……",
searchAria: "搜索文档",
noResults: "未找到结果",
selectText: "选择",
navigateText: "导航",
closeText: "关闭",
footerMessage: "免费且开源。",
docFooterPrev: "上一页",
docFooterNext: "下一页",
outlineLabel: "本页内容",
darkModeSwitchLabel: "外观",
lightModeSwitchTitle: "切换到浅色主题",
darkModeSwitchTitle: "切换到深色主题",
lastUpdatedText: "最后更新",
editLinkText: "在 GitHub 上编辑此页"
}
}
},
{
loc: "es",
lang: "es-ES",
label: "Español",
strings: {
siteTitle: "Documentación de Agent Teams",
siteDescription:
"Documentación de Agent Teams, una aplicación de escritorio local para la orquestación de agentes de IA.",
nav: {
guide: "Guía",
developers: "Desarrolladores",
reference: "Referencia",
troubleshooting: "Solución de problemas",
download: "Descargar"
},
sidebarGroups: {
start: "Inicio",
guide: "Guía",
operations: "Operaciones",
developers: "Desarrolladores",
reference: "Referencia"
},
sidebarItems: {
installation: "Instalación",
quickstart: "Inicio rápido",
runtimeSetup: "Configuración del runtime",
createTeam: "Crear un equipo",
agentWorkflow: "Flujo de trabajo de los agentes",
codeReview: "Revisión de código",
mcpIntegration: "Integración de MCP",
teamBriefExamples: "Ejemplos de briefing de equipo",
gitWorktreeStrategy: "Estrategia de Git y worktree",
troubleshooting: "Solución de problemas",
developerHub: "Centro para desarrolladores",
concepts: "Conceptos",
providersRuntimes: "Proveedores y runtimes",
contributorArchitecture: "Arquitectura para colaboradores",
releaseNotes: "Notas de la versión",
privacyLocalData: "Privacidad y datos locales",
faq: "Preguntas frecuentes"
},
ui: {
searchButton: "Buscar...",
searchAria: "Buscar en la documentación",
noResults: "No se encontraron resultados",
selectText: "para seleccionar",
navigateText: "para navegar",
closeText: "para cerrar",
footerMessage: "Gratis y de código abierto.",
docFooterPrev: "Anterior",
docFooterNext: "Siguiente",
outlineLabel: "En esta página",
darkModeSwitchLabel: "Apariencia",
lightModeSwitchTitle: "Cambiar al tema claro",
darkModeSwitchTitle: "Cambiar al tema oscuro",
lastUpdatedText: "Última actualización",
editLinkText: "Editar esta página en GitHub"
}
}
},
{
loc: "ja",
lang: "ja-JP",
label: "日本語",
strings: {
siteTitle: "Agent Teams ドキュメント",
siteDescription:
"AI エージェントのオーケストレーションを行うローカル デスクトップアプリ Agent Teams のドキュメントです。",
nav: {
guide: "ガイド",
developers: "開発者向け",
reference: "リファレンス",
troubleshooting: "トラブルシューティング",
download: "ダウンロード"
},
sidebarGroups: {
start: "はじめに",
guide: "ガイド",
operations: "運用",
developers: "開発者向け",
reference: "リファレンス"
},
sidebarItems: {
installation: "インストール",
quickstart: "クイックスタート",
runtimeSetup: "ランタイムの設定",
createTeam: "チームの作成",
agentWorkflow: "エージェントのワークフロー",
codeReview: "コードレビュー",
mcpIntegration: "MCP 連携",
teamBriefExamples: "チームブリーフの例",
gitWorktreeStrategy: "Git と worktree の戦略",
troubleshooting: "トラブルシューティング",
developerHub: "開発者ハブ",
concepts: "コンセプト",
providersRuntimes: "プロバイダーとランタイム",
contributorArchitecture: "コントリビューター向けアーキテクチャ",
releaseNotes: "リリースノート",
privacyLocalData: "プライバシーとローカルデータ",
faq: "FAQ"
},
ui: {
searchButton: "検索...",
searchAria: "ドキュメントを検索",
noResults: "結果が見つかりませんでした",
selectText: "選択",
navigateText: "移動",
closeText: "閉じる",
footerMessage: "無料でオープンソースです。",
docFooterPrev: "前へ",
docFooterNext: "次へ",
outlineLabel: "このページの内容",
darkModeSwitchLabel: "外観",
lightModeSwitchTitle: "ライトテーマに切り替える",
darkModeSwitchTitle: "ダークテーマに切り替える",
lastUpdatedText: "最終更新",
editLinkText: "GitHub でこのページを編集"
}
}
},
{
loc: "fr",
lang: "fr-FR",
label: "Français",
strings: {
siteTitle: "Documentation Agent Teams",
siteDescription:
"Documentation d'Agent Teams, une application de bureau locale pour l'orchestration d'agents IA.",
nav: {
guide: "Guide",
developers: "Développeurs",
reference: "Référence",
troubleshooting: "Dépannage",
download: "Télécharger"
},
sidebarGroups: {
start: "Démarrer",
guide: "Guide",
operations: "Opérations",
developers: "Développeurs",
reference: "Référence"
},
sidebarItems: {
installation: "Installation",
quickstart: "Démarrage rapide",
runtimeSetup: "Configuration du runtime",
createTeam: "Créer une équipe",
agentWorkflow: "Flux de travail des agents",
codeReview: "Revue de code",
mcpIntegration: "Intégration MCP",
teamBriefExamples: "Exemples de briefs d'équipe",
gitWorktreeStrategy: "Stratégie Git et worktree",
troubleshooting: "Dépannage",
developerHub: "Hub développeur",
concepts: "Concepts",
providersRuntimes: "Fournisseurs et runtimes",
contributorArchitecture: "Architecture pour les contributeurs",
releaseNotes: "Notes de version",
privacyLocalData: "Confidentialité et données locales",
faq: "FAQ"
},
ui: {
searchButton: "Rechercher...",
searchAria: "Rechercher dans la documentation",
noResults: "Aucun résultat trouvé",
selectText: "pour sélectionner",
navigateText: "pour naviguer",
closeText: "pour fermer",
footerMessage: "Gratuit et open source.",
docFooterPrev: "Précédent",
docFooterNext: "Suivant",
outlineLabel: "Sur cette page",
darkModeSwitchLabel: "Apparence",
lightModeSwitchTitle: "Passer au thème clair",
darkModeSwitchTitle: "Passer au thème sombre",
lastUpdatedText: "Dernière mise à jour",
editLinkText: "Modifier cette page sur GitHub"
}
}
},
{
loc: "de",
lang: "de-DE",
label: "Deutsch",
strings: {
siteTitle: "Agent Teams Dokumentation",
siteDescription:
"Dokumentation für Agent Teams, eine lokale Desktop-App zur Orchestrierung von KI-Agenten.",
nav: {
guide: "Anleitung",
developers: "Entwickler",
reference: "Referenz",
troubleshooting: "Fehlerbehebung",
download: "Download"
},
sidebarGroups: {
start: "Start",
guide: "Anleitung",
operations: "Betrieb",
developers: "Entwickler",
reference: "Referenz"
},
sidebarItems: {
installation: "Installation",
quickstart: "Schnellstart",
runtimeSetup: "Runtime-Einrichtung",
createTeam: "Team erstellen",
agentWorkflow: "Agent-Workflow",
codeReview: "Code-Review",
mcpIntegration: "MCP-Integration",
teamBriefExamples: "Team-Briefing-Beispiele",
gitWorktreeStrategy: "Git- und Worktree-Strategie",
troubleshooting: "Fehlerbehebung",
developerHub: "Entwickler-Hub",
concepts: "Konzepte",
providersRuntimes: "Anbieter und Runtimes",
contributorArchitecture: "Architektur für Mitwirkende",
releaseNotes: "Versionshinweise",
privacyLocalData: "Datenschutz und lokale Daten",
faq: "FAQ"
},
ui: {
searchButton: "Suchen...",
searchAria: "Dokumentation durchsuchen",
noResults: "Keine Ergebnisse gefunden",
selectText: "zum Auswählen",
navigateText: "zum Navigieren",
closeText: "zum Schließen",
footerMessage: "Kostenlos und quelloffen.",
docFooterPrev: "Zurück",
docFooterNext: "Weiter",
outlineLabel: "Auf dieser Seite",
darkModeSwitchLabel: "Darstellung",
lightModeSwitchTitle: "Zum hellen Design wechseln",
darkModeSwitchTitle: "Zum dunklen Design wechseln",
lastUpdatedText: "Zuletzt aktualisiert",
editLinkText: "Diese Seite auf GitHub bearbeiten"
}
}
}
];
const buildLocaleGuide = (loc: string, s: DocsLocaleStrings): DefaultTheme.SidebarItem[] => [
{
text: s.sidebarGroups.start,
items: [
{ text: s.sidebarItems.installation, link: `/${loc}/guide/installation` },
{ text: s.sidebarItems.quickstart, link: `/${loc}/guide/quickstart` },
{ text: s.sidebarItems.runtimeSetup, link: `/${loc}/guide/runtime-setup` }
]
},
{
text: s.sidebarGroups.guide,
items: [
{ text: s.sidebarItems.createTeam, link: `/${loc}/guide/create-team` },
{ text: s.sidebarItems.agentWorkflow, link: `/${loc}/guide/agent-workflow` },
{ text: s.sidebarItems.codeReview, link: `/${loc}/guide/code-review` },
{ text: s.sidebarItems.mcpIntegration, link: `/${loc}/guide/mcp-integration` },
{ text: s.sidebarItems.teamBriefExamples, link: `/${loc}/guide/team-brief-examples` }
]
},
{
text: s.sidebarGroups.operations,
items: [
{ text: s.sidebarItems.gitWorktreeStrategy, link: `/${loc}/guide/git-worktree-strategy` },
{ text: s.sidebarItems.troubleshooting, link: `/${loc}/guide/troubleshooting` }
]
},
{
text: s.sidebarGroups.developers,
items: [{ text: s.sidebarItems.developerHub, link: `/${loc}/developers/` }]
},
{
text: s.sidebarGroups.reference,
items: [
{ text: s.sidebarItems.concepts, link: `/${loc}/reference/concepts` },
{ text: s.sidebarItems.providersRuntimes, link: `/${loc}/reference/providers-runtimes` },
{ text: s.sidebarItems.contributorArchitecture, link: `/${loc}/reference/contributor-architecture` },
{ text: s.sidebarItems.releaseNotes, link: `/${loc}/reference/release-notes` },
{ text: s.sidebarItems.privacyLocalData, link: `/${loc}/reference/privacy-local-data` },
{ text: s.sidebarItems.faq, link: `/${loc}/reference/faq` }
]
}
];
const buildLocaleNav = (loc: string, s: DocsLocaleStrings): DefaultTheme.NavItem[] => [
{
text: s.nav.guide,
link: `/${loc}/guide/quickstart`,
activeMatch: `^/${loc}/guide/(?!troubleshooting(?:/|$))`
},
{ text: s.nav.developers, link: `/${loc}/developers/`, activeMatch: `^/${loc}/developers/` },
{ text: s.nav.reference, link: `/${loc}/reference/concepts`, activeMatch: `^/${loc}/reference/` },
{
text: s.nav.troubleshooting,
link: `/${loc}/guide/troubleshooting`,
activeMatch: `^/${loc}/guide/troubleshooting(?:/|$)`
},
{ text: s.nav.download, link: `${publicBaseUrl}${loc}/download/`, target: "_self", noIcon: true }
];
const buildLocaleConfig = ({ loc, lang, label, strings: s }: DocsLocaleDefinition) => ({
label,
lang,
title: s.siteTitle,
description: s.siteDescription,
themeConfig: {
nav: buildLocaleNav(loc, s),
outline: {
level: [2, 3] as [number, number],
label: s.ui.outlineLabel
},
darkModeSwitchLabel: s.ui.darkModeSwitchLabel,
lightModeSwitchTitle: s.ui.lightModeSwitchTitle,
darkModeSwitchTitle: s.ui.darkModeSwitchTitle,
search: {
provider: "local" as const,
options: {
translations: {
button: {
buttonText: s.ui.searchButton,
buttonAriaLabel: s.ui.searchAria
},
modal: {
noResultsText: s.ui.noResults,
footer: {
selectText: s.ui.selectText,
navigateText: s.ui.navigateText,
closeText: s.ui.closeText
}
}
}
}
},
lastUpdated: {
text: s.ui.lastUpdatedText,
formatOptions: {
dateStyle: "medium" as const,
timeStyle: "short" as const,
forceLocale: true
}
},
editLink: {
pattern: `https://github.com/${REPO}/edit/main/landing/product-docs/:path`,
text: s.ui.editLinkText
},
docFooter: {
prev: s.ui.docFooterPrev,
next: s.ui.docFooterNext
},
footer: {
message: s.ui.footerMessage,
copyright: "Copyright © 777genius"
}
}
});
const additionalLocaleSidebars = Object.fromEntries(
additionalLocales.map((def) => [`/${def.loc}/`, buildLocaleGuide(def.loc, def.strings)])
);
const additionalLocaleConfigs = Object.fromEntries(
additionalLocales.map((def) => [def.loc, buildLocaleConfig(def)])
);
export default defineConfig({
lang: "en-US",
title: SITE_TITLE,
@ -261,6 +726,7 @@ export default defineConfig({
nav: rootNav,
sidebar: {
"/ru/": ruGuide,
...additionalLocaleSidebars,
"/": rootGuide
},
socialLinks: [{ icon: "github", link: `https://github.com/${REPO}` }],
@ -339,6 +805,7 @@ export default defineConfig({
copyright: "Copyright © 777genius"
}
}
}
},
...additionalLocaleConfigs
}
});

173
landing/product-docs/.vitepress/theme/DocsCardGrid.vue
View file

@ -6,41 +6,152 @@ const props = withDefaults(defineProps<{ type?: "start" | "reference" }>(), {
type: "start"
});
type CardText = { title: string; desc: string };
// Locales that have their own translated card copy. Anything else falls back to English (root).
const KNOWN_LOCALES = ["ru", "zh", "es", "ja", "fr", "de"] as const;
// Links and icons are shared across locales; only the path prefix changes per locale.
const START_LINKS = ["/guide/quickstart", "/guide/installation", "/guide/create-team", "/guide/code-review"];
const START_ICONS = ["01", "02", "03", "04"];
const REFERENCE_LINKS = [
"/reference/concepts",
"/reference/providers-runtimes",
"/reference/contributor-architecture",
"/reference/privacy-local-data",
"/reference/faq"
];
const REFERENCE_ICONS = ["◈", "⌁", "▦", "⌘", "?"];
const CARD_TEXT: Record<string, { start: CardText[]; reference: CardText[] }> = {
"": {
start: [
{ title: "Quickstart", desc: "Install the app and create your first team." },
{ title: "Installation", desc: "Platforms, releases, and running from source." },
{ title: "Create a team", desc: "Roles, lead prompt, and task boundaries." },
{ title: "Code review", desc: "Review task changes with hunk-level decisions." }
],
reference: [
{ title: "Concepts", desc: "Teams, tasks, roles, and autonomy levels." },
{ title: "Runtimes", desc: "Claude, Codex, OpenCode, and multimodel mode." },
{ title: "Architecture", desc: "Feature layout, guardrails, and runtime/provider boundaries." },
{ title: "Local data", desc: "What stays on disk and what providers receive." },
{ title: "FAQ", desc: "Short answers to common questions." }
]
},
ru: {
start: [
{ title: "Быстрый старт", desc: "Поставить приложение и создать первую команду." },
{ title: "Установка", desc: "Платформы, релизы и запуск из исходников." },
{ title: "Создание команды", desc: "Роли, lead prompt и границы работы." },
{ title: "Код-ревью", desc: "Проверка изменений по задачам и hunk-level decisions." }
],
reference: [
{ title: "Концепции", desc: "Команды, задачи, роли и уровни автономности." },
{ title: "Рантаймы", desc: "Claude, Codex, OpenCode и multimodel-режим." },
{ title: "Архитектура", desc: "Feature layout, guardrails и границы runtime/provider." },
{ title: "Локальные данные", desc: "Что хранится на машине и что уходит провайдерам." },
{ title: "FAQ", desc: "Короткие ответы на частые вопросы." }
]
},
zh: {
start: [
{ title: "快速开始", desc: "安装应用并创建你的第一个团队。" },
{ title: "安装", desc: "平台、发布版本以及从源码运行。" },
{ title: "创建团队", desc: "角色、lead prompt 与任务边界。" },
{ title: "代码审查", desc: "以代码块（hunk）级别的决策审查任务变更。" }
],
reference: [
{ title: "概念", desc: "团队、任务、角色与自主级别。" },
{ title: "运行时", desc: "Claude、Codex、OpenCode 与多模型模式。" },
{ title: "架构", desc: "功能布局、护栏以及运行时/提供方边界。" },
{ title: "本地数据", desc: "哪些数据留在磁盘上，哪些会发送给提供方。" },
{ title: "常见问题", desc: "对常见问题的简短解答。" }
]
},
es: {
start: [
{ title: "Inicio rápido", desc: "Instala la aplicación y crea tu primer equipo." },
{ title: "Instalación", desc: "Plataformas, versiones y ejecución desde el código fuente." },
{ title: "Crear un equipo", desc: "Roles, prompt del lead y límites de las tareas." },
{ title: "Revisión de código", desc: "Revisa los cambios de las tareas con decisiones a nivel de hunk." }
],
reference: [
{ title: "Conceptos", desc: "Equipos, tareas, roles y niveles de autonomía." },
{ title: "Runtimes", desc: "Claude, Codex, OpenCode y modo multimodelo." },
{ title: "Arquitectura", desc: "Estructura de las funciones, guardrails y límites entre runtime y proveedor." },
{ title: "Datos locales", desc: "Qué permanece en el disco y qué reciben los proveedores." },
{ title: "Preguntas frecuentes", desc: "Respuestas breves a preguntas habituales." }
]
},
ja: {
start: [
{ title: "クイックスタート", desc: "アプリをインストールして、最初のチームを作成します。" },
{ title: "インストール", desc: "対応プラットフォーム、リリース、ソースからの実行について。" },
{ title: "チームの作成", desc: "ロール、リードプロンプト、タスクの範囲について。" },
{ title: "コードレビュー", desc: "ハンク単位の判断でタスクの変更をレビューします。" }
],
reference: [
{ title: "コンセプト", desc: "チーム、タスク、ロール、自律性のレベルについて。" },
{ title: "ランタイム", desc: "Claude、Codex、OpenCode、およびマルチモデルモードについて。" },
{ title: "アーキテクチャ", desc: "機能の構成、ガードレール、ランタイム/プロバイダーの境界について。" },
{ title: "ローカルデータ", desc: "ディスクに保持されるものと、プロバイダーに送信されるものについて。" },
{ title: "FAQ", desc: "よくある質問への簡潔な回答。" }
]
},
fr: {
start: [
{ title: "Démarrage rapide", desc: "Installez l'application et créez votre première équipe." },
{ title: "Installation", desc: "Plateformes, versions et exécution depuis les sources." },
{ title: "Créer une équipe", desc: "Rôles, prompt du lead et périmètre des tâches." },
{ title: "Revue de code", desc: "Examinez les modifications de tâches avec des décisions au niveau du hunk." }
],
reference: [
{ title: "Concepts", desc: "Équipes, tâches, rôles et niveaux d'autonomie." },
{ title: "Runtimes", desc: "Claude, Codex, OpenCode et mode multimodèle." },
{ title: "Architecture", desc: "Organisation des fonctionnalités, garde-fous et frontières runtime/fournisseur." },
{ title: "Données locales", desc: "Ce qui reste sur le disque et ce que reçoivent les fournisseurs." },
{ title: "FAQ", desc: "Réponses brèves aux questions fréquentes." }
]
},
de: {
start: [
{ title: "Schnellstart", desc: "Installieren Sie die App und erstellen Sie Ihr erstes Team." },
{ title: "Installation", desc: "Plattformen, Releases und Ausführen aus dem Quellcode." },
{ title: "Team erstellen", desc: "Rollen, Lead-Prompt und Aufgabengrenzen." },
{ title: "Code-Review", desc: "Aufgabenänderungen mit Entscheidungen auf Hunk-Ebene überprüfen." }
],
reference: [
{ title: "Konzepte", desc: "Teams, Aufgaben, Rollen und Autonomiestufen." },
{ title: "Runtimes", desc: "Claude, Codex, OpenCode und Multimodell-Modus." },
{ title: "Architektur", desc: "Feature-Aufbau, Guardrails und Grenzen zwischen Runtime und Anbieter." },
{ title: "Lokale Daten", desc: "Was auf dem Datenträger bleibt und was die Anbieter erhalten." },
{ title: "FAQ", desc: "Kurze Antworten auf häufige Fragen." }
]
}
};
const { page } = useData();
const isRu = computed(() => page.value.relativePath.startsWith("ru/"));
const locale = computed(() => {
const segment = page.value.relativePath.split("/")[0];
return (KNOWN_LOCALES as readonly string[]).includes(segment) ? segment : "";
});
const cards = computed(() => {
if (isRu.value) {
return props.type === "reference"
? [
{ icon: "◈", title: "Концепции", desc: "Команды, задачи, роли и уровни автономности.", link: "/ru/reference/concepts" },
{ icon: "⌁", title: "Рантаймы", desc: "Claude, Codex, OpenCode и multimodel-режим.", link: "/ru/reference/providers-runtimes" },
{ icon: "▦", title: "Архитектура", desc: "Feature layout, guardrails и границы runtime/provider.", link: "/ru/reference/contributor-architecture" },
{ icon: "⌘", title: "Локальные данные", desc: "Что хранится на машине и что уходит провайдерам.", link: "/ru/reference/privacy-local-data" },
{ icon: "?", title: "FAQ", desc: "Короткие ответы на частые вопросы.", link: "/ru/reference/faq" }
]
: [
{ icon: "01", title: "Быстрый старт", desc: "Поставить приложение и создать первую команду.", link: "/ru/guide/quickstart" },
{ icon: "02", title: "Установка", desc: "Платформы, релизы и запуск из исходников.", link: "/ru/guide/installation" },
{ icon: "03", title: "Создание команды", desc: "Роли, lead prompt и границы работы.", link: "/ru/guide/create-team" },
{ icon: "04", title: "Код-ревью", desc: "Проверка изменений по задачам и hunk-level decisions.", link: "/ru/guide/code-review" }
];
}
const text = CARD_TEXT[locale.value] ?? CARD_TEXT[""];
const isReference = props.type === "reference";
const entries = isReference ? text.reference : text.start;
const links = isReference ? REFERENCE_LINKS : START_LINKS;
const icons = isReference ? REFERENCE_ICONS : START_ICONS;
const prefix = locale.value ? `/${locale.value}` : "";
return props.type === "reference"
? [
{ icon: "◈", title: "Concepts", desc: "Teams, tasks, roles, and autonomy levels.", link: "/reference/concepts" },
{ icon: "⌁", title: "Runtimes", desc: "Claude, Codex, OpenCode, and multimodel mode.", link: "/reference/providers-runtimes" },
{ icon: "▦", title: "Architecture", desc: "Feature layout, guardrails, and runtime/provider boundaries.", link: "/reference/contributor-architecture" },
{ icon: "⌘", title: "Local data", desc: "What stays on disk and what providers receive.", link: "/reference/privacy-local-data" },
{ icon: "?", title: "FAQ", desc: "Short answers to common questions.", link: "/reference/faq" }
]
: [
{ icon: "01", title: "Quickstart", desc: "Install the app and create your first team.", link: "/guide/quickstart" },
{ icon: "02", title: "Installation", desc: "Platforms, releases, and running from source.", link: "/guide/installation" },
{ icon: "03", title: "Create a team", desc: "Roles, lead prompt, and task boundaries.", link: "/guide/create-team" },
{ icon: "04", title: "Code review", desc: "Review task changes with hunk-level decisions.", link: "/guide/code-review" }
];
return entries.map((entry, index) => ({
icon: icons[index],
title: entry.title,
desc: entry.desc,
link: `${prefix}${links[index]}`
}));
});
</script>

69
landing/product-docs/de/developers/index.md Normal file
View file

@ -0,0 +1,69 @@
---
title: Entwickler-Hub – Agent Teams Dokumentation
description: Einstiegspunkt für Mitwirkende und Entwickler zur Architektur, zu den Guardrails, zum Debugging und zu den MCP-Erweiterungswegen von Agent Teams.
lang: de-DE
---
# Entwickler-Hub
Nutzen Sie diese Seite, wenn Sie Agent Teams selbst ändern, einen Team-Launch debuggen oder eine Runtime mit MCP-Tools erweitern möchten. Die folgenden Links verweisen auf die maßgeblichen Repo-Dokumente, damit die Implementierungsregeln an einer Stelle gebündelt bleiben.
## Hier starten
| Bedarf | Gehe zu |
| --- | --- |
| Repo-Überblick, Skripte und Quellcode-Einrichtung | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) |
| Agent-Navigation und Architektur-Index | [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) |
| Arbeitskonventionen für Agenten und Mitwirkende | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) |
| Strikte Implementierungs-Guardrails | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) |
| Aufbau mittlerer und großer Features | [Feature-Architektur-Standard](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) |
| Debugging von Launch, Bootstrap und Teammate-Messaging | [Runbook für das Debugging von Agent-Teams](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) |
| Beitragsprozess | [Leitfaden für Beiträge](https://github.com/777genius/agent-teams-ai/blob/main/.github/CONTRIBUTING.md) |
| Versionshinweise / Changelog | [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) — [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) |
## Lokaler Entwicklungsweg
Führen Sie die Electron-Desktop-App für die normale Entwicklung aus:
```bash
pnpm install
pnpm dev
```
Der Browser-/Web-Weg ist kein Ersatz für die Desktop-Runtime. Der Desktop-Modus ist der unterstützte lokale Weg, da er IPC, Terminals, Anbieter-Authentifizierung, die Verwaltung des Team-Lebenszyklus, Launch-Diagnosen und die von echten Teams genutzten Runtime-Bridges umfasst.
## Architektur-Checkpoints
Bevor Sie ein Feature ändern, bestimmen Sie seine Grenze:
| Bereich | Erwarteter Speicherort |
| --- | --- |
| Mittleres oder großes Produkt-Feature | `src/features/<feature-name>/` |
| Orchestrierung im Electron-Hauptprozess | `src/main/` |
| Preload-sichere API-Oberfläche | `src/preload/` |
| Renderer-UI und App-Zustand | `src/renderer/` |
| Geteilte Typen und reine Hilfsfunktionen | `src/shared/` |
| MCP-Server des Agent-Teams-Boards | `mcp-server/` |
| Board-Datencontroller | `agent-teams-controller/` |
Verwenden Sie `src/features/recent-projects` als Referenz-Slice für die Feature-Organisation. Halten Sie prozessübergreifende Verträge explizit und vermeiden Sie tiefe Imports über Feature-Grenzen hinweg.
## Debugging-Weg
Bei hängenden Launches, OpenCode-Zuständen `registered` / Bootstrap nicht bestätigt, fehlenden Teammate-Antworten oder verdächtigen Task-Logs:
1. Beginnen Sie mit dem [Debugging-Runbook](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md).
2. Untersuchen Sie das neueste Artefakt-Paket unter `~/.claude/teams/<team>/launch-failure-artifacts/latest.json`.
3. Öffnen Sie die Artefakt-`manifest.json` und prüfen Sie `classification`, Bootstrap-Breadcrumbs, Launch-Diagnosen, die Spawn-Status der Mitglieder und die redigierten Log-Auszüge.
4. Räumen Sie nur das Team, den Run, das Pane oder den Prozess auf, das bzw. den Sie als zum Smoke-Test oder zum fehlgeschlagenen Launch gehörig identifizieren können.
## MCP-Entwicklungsweg
Agent Teams nutzt einen integrierten MCP-Server namens `agent-teams` für Board-Operationen. Benutzer- und Projekt-MCP-Server können externe Fähigkeiten für Runtimes hinzufügen. Siehe [MCP-Integration](/de/guide/mcp-integration) für Einrichtungsbeispiele, die Struktur von `.mcp.json` und Hinweise zur Tool-Registrierung.
## Verwandte Dokumente
- [Architektur für Mitwirkende](/de/reference/contributor-architecture)
- [Runtime-Einrichtung](/de/guide/runtime-setup)
- [MCP-Integration](/de/guide/mcp-integration)
- [Fehlerbehebung](/de/guide/troubleshooting)

121
landing/product-docs/de/guide/agent-workflow.md Normal file
View file

@ -0,0 +1,121 @@
---
title: Agent-Workflow – Agent Teams Dokumentation
description: Verstehen Sie den Aufgabenlebenszyklus, das Kanban-Board, Nachrichten, Aufgabenprotokolle, Parallelarbeit, Live-Prozesse und teamübergreifende Kommunikation.
lang: de-DE
---
# Agent-Workflow
Agent Teams macht die Arbeit der Agenten als Aufgabenstatus, Nachrichten, Protokolle und überprüfbare Codeänderungen sichtbar.
## Modi
| Modus | Beschreibung |
| --- | --- |
| Solo | Ein Teammitglied mit selbst verwalteten Aufgaben |
| Team | Viele Teammitglieder, die parallel arbeiten und sich gegenseitig überprüfen |
Beide Modi teilen sich dieselben Oberflächen für Kanban, Aufgabenprotokolle und Code-Review.
## Aufgabenlebenszyklus
Agent Teams verfolgt jede Aufgabe entlang zweier unabhängiger Dimensionen: Arbeitsstatus und Review-Zustand.
| Dimension | Zustände | Beschreibung |
| --- | --- | --- |
| Arbeitsstatus | `pending`, `in_progress`, `completed` | Verfolgt, ob die Aufgabe wartet, gerade bearbeitet wird oder vom Eigentümer abgeschlossen wurde |
| Review-Zustand | `none`, `review`, `needsFix`, `approved` | Verfolgt, an welcher Stelle des Review-Ablaufs nach Abschluss sich die Aufgabe befindet |
Das Kanban-Board zeigt die kombinierte Ansicht, aber die beiden Dimensionen bewegen sich unabhängig voneinander.
### Arbeitsstatus-Ablauf
| Phase | Was passiert | Eigentümer |
| --- | --- | --- |
| Pending | Die Aufgabe ist erstellt und bereit, aber noch hat niemand mit der Arbeit begonnen | Lead oder Benutzer |
| In progress | Agenten arbeiten und aktualisieren den Aufgabenzustand über die Board-MCP-Tools | Teammitglieder |
| Completed | Der Eigentümer postet einen Ergebniskommentar und markiert die Aufgabe als erledigt | Teammitglied |
### Review-Zustand-Ablauf
| Phase | Was passiert | Eigentümer |
| --- | --- | --- |
| None | Die Aufgabe befindet sich noch nicht im Review (kann pending, in progress oder neu completed sein) | — |
| Review | Ein Review wurde angefordert; ein Reviewer prüft das Diff und das Ergebnis | Reviewer |
| Needs fix | Während des Reviews wurden Änderungen angefordert; der Eigentümer muss aktualisieren | Teammitglied (Eigentümer) |
| Approved | Der Review wurde bestanden; die Aufgabe ist finalisiert | Reviewer |
### Planung → In progress
Wenn ein Teammitglied eine Aufgabe beginnt, wechselt der Arbeitsstatus auf `in_progress`. Der Agent erstellt einen Aufgabenkommentar mit seinem Plan und arbeitet weiter. Alle nativen Tool-Aktionen (read, bash, edit, write) werden in ein Aufgabenprotokoll gestreamt.
### Completed → Review
Wenn das Teammitglied die Arbeit beendet, postet es einen Ergebniskommentar und setzt den Arbeitsstatus auf `completed`. Der Lead oder Reviewer kann dann ein Review anfordern, um den Review-Ablauf zu starten.
### Review → Approved
Wenn die Review-Oberfläche akzeptable Änderungen zeigt, genehmigen Sie das Review. Die Aufgabe wird finalisiert und mit ihrem Diff verknüpft.
::: warning Fix-first-Review
Wenn ein Teammitglied während des Reviews um Änderungen gebeten wird, sollte es einen Folgekommentar mit den Korrekturen posten, woraufhin der Lead genehmigen kann.
:::
## Kanban-Board
Das Board ist die primäre Arbeitsoberfläche. Es ermöglicht Ihnen:
- Offene, blockierte und im Review befindliche Arbeit zu überblicken
- Die Aufgabendetails zu öffnen und Laufzeitprotokolle zu inspizieren
- Änderungen zu überprüfen, ohne rohe Session-Dateien zu lesen
- Eigentümer zuzuweisen oder neu zuzuweisen
::: tip
Verwenden Sie die Schnellaktions-Schaltflächen auf den Karten, um eine Aufgabe zu starten, abzuschließen oder ein Review anzufordern, ohne das Detailfenster zu öffnen.
:::
## Nachrichten und Kommentare
| Kanal | Wann verwenden |
| --- | --- |
| Direktnachricht | Einen Agenten umleiten, eine kurze Frage stellen |
| Aufgabenkommentar | Notizen, die zu einer bestimmten Aufgabe gehören |
Kommentare bewahren den Kontext für ein späteres Review und erscheinen in der Aufgaben-Timeline.
::: tip Aufgabenkommentare bevorzugen
Wenn sich die Anmerkung auf eine bestimmte Aufgabe bezieht, fügen Sie sie als Kommentar zu dieser Aufgabe hinzu, anstatt eine Direktnachricht zu senden. So bleibt der Verlauf mit der Arbeit verknüpft.
:::
## Aufgabenprotokolle
Aufgabenspezifische Protokolle isolieren Laufzeitausgaben, Aktionen und Nachrichten für eine Zuweisung. Verwenden Sie sie, um folgende Fragen zu beantworten:
- Was hat dieser Agent ausgeführt?
- Warum hat er diese Datei geändert?
- Hat er ein anderes Teammitglied um Hilfe gebeten?
- Welche Aufgabe hat dieses Diff erzeugt?
### Validierungs-Checkliste
Wenn eine Aufgabe festzustecken scheint oder ihr Diff losgelöst wirkt, überprüfen Sie den Lebenszyklus in dieser Reihenfolge:
1. Die Aufgabe hat den erwarteten Eigentümer und ist auf `in_progress` gewechselt.
2. Der Eigentümer hat einen Aufgabenkommentar mit dem Plan oder dem ersten Fortschrittsupdate gepostet.
3. Die Aufgabenprotokolle zeigen Laufzeitaktivität innerhalb des Aufgabenfensters.
4. Dateiänderungen sind mit derselben Aufgabe, demselben Eigentümer und derselben Session verknüpft.
5. Der abschließende Aufgabenkommentar enthält den Verifizierungsbefehl und das Ergebnis.
Für tiefergehendes Debugging verwenden Sie die Befehle für persistierte Belege unter [Fehlerbehebung](/de/guide/troubleshooting#task-log-triage). Die Benutzeroberfläche ist die Arbeitsoberfläche, aber die persistierten Aufgabendateien, Postfächer und Laufzeitbelege sind die Quelle für schwerwiegende Launch- oder Attributionsfehler.
## Muster für Parallelarbeit
Teammitglieder können gleichzeitig an unabhängigen Aufgaben arbeiten. Sie können auch Abhängigkeitsverknüpfungen (`blocked-by`) erstellen, sodass eine Aufgabe wartet, bis eine andere abgeschlossen ist. Behalten Sie das Board auf blockierte Bahnen im Auge und weisen Sie Eigentümer neu zu, wenn ein Teammitglied untätig ist, während ein anderes überlastet ist.
## Live-Prozesse
Der Live-Prozess-Bereich zeigt URLs und laufende Prozesse an, wenn Agenten lokale Server oder Tools starten. Öffnen Sie URLs direkt aus der App, um die Ergebnisse zu inspizieren. Prozesse bleiben registriert, bis sie explizit gestoppt werden oder die Runtime beendet wird.
## Teamübergreifende Kommunikation
Agenten können Nachrichten an andere Teams senden, wenn die Teams verknüpft sind. Verwenden Sie dies für Übergaben, gemeinsam genutzte Bibliotheken oder Statusabfragen zwischen Squads.

119
landing/product-docs/de/guide/code-review.md Normal file
View file

@ -0,0 +1,119 @@
---
title: Code-Review – Agent Teams Dokumentation
description: Aufgabenbezogene Diffs prüfen, Hunks akzeptieren oder ablehnen, Inline-Kommentare hinterlassen und Review-Zustände von none bis approved verwalten.
lang: de-DE
---
# Code-Review
Code-Review in Agent Teams ist aufgabenzentriert. Sie prüfen, was sich für eine bestimmte Aufgabe geändert hat, anstatt einen großen unstrukturierten Diff zu durchsuchen.
## Review-Oberfläche
Für jede abgeschlossene Aufgabe, die Dateien berührt hat, ermöglicht Ihnen die Review-Oberfläche Folgendes:
- Geänderte Dateien mit Kontext vorher/nachher prüfen
- Einzelne Hunks akzeptieren oder ablehnen
- Inline-Kommentare hinterlassen
- Den Diff mit der Aufgabenbeschreibung und den Agent-Logs verknüpfen
## Entscheidungen auf Hunk-Ebene
Akzeptieren Sie kleine korrekte Änderungen und lehnen Sie isolierte Fehler ab, ohne die gesamte Aufgabe zu verwerfen. Das ist nützlich, wenn ein Agent die Aufgabe größtenteils gelöst, aber in einer Datei über das Ziel hinausgeschossen ist.
::: tip Schrittweise akzeptieren
Wenn ein Diff größtenteils korrekt ist, akzeptieren Sie zuerst die guten Hunks und fordern Sie nur für die Teile Änderungen an, die korrigiert werden müssen. So bleibt das Board in Bewegung.
:::
Nutzen Sie Entscheidungen auf Hunk-Ebene für:
| Situation | Aktion |
| --- | --- |
| Korrekte, eng begrenzte Änderung | Den Hunk akzeptieren |
| Korrekte Idee, falsche Datei oder breites Refactoring | Den Hunk ablehnen und eine engere Korrektur anfordern |
| Unklare Verhaltensänderung | Kommentieren und um Verifizierung bitten |
| Generiertes Formatierungsrauschen | Ablehnen, sofern die Formatierung nicht Teil der Aufgabe war |
## Review starten
1. Öffnen Sie eine abgeschlossene Aufgabe
2. Sehen Sie sich den Tab **Changes** an
3. Wenn der Diff angemessen aussieht, klicken Sie auf **Request Review**, um die Aufgabe in die Review-Spalte zu verschieben
Während des Reviews gilt die Aufgabe noch nicht als done, sodass andere Teammitglieder oder der Lead sie weiterhin kommentieren können.
## Review-Schleife
Eine gesunde Review-Schleife sieht so aus:
1. Der Eigentümer postet einen Ergebniskommentar mit dem geänderten Umfang und der Verifizierung
2. Der Reviewer öffnet den Aufgaben-Diff und prüft die Hunks anhand der Aufgabenbeschreibung
3. Der Reviewer akzeptiert gute Hunks, lehnt schlechte Hunks ab oder fordert Änderungen an
4. Der Eigentümer korrigiert nur den angeforderten Umfang und postet einen Folgekommentar
5. Der Reviewer genehmigt, wenn Aufgabenergebnis und Diff übereinstimmen
Beispiel für einen Kommentar mit Änderungsanforderung:
```text
Please keep the copy improvements, but revert the unrelated runtime wording in the provider table. Add the `pnpm --dir landing docs:build` result before resubmitting.
```
## Review-Zustände
| Zustand | Bedeutung |
| --- | --- |
| `none` | Aufgabe ist neu, in Bearbeitung oder abgeschlossen, aber noch nicht im Review |
| `review` | Die Aufgabe befindet sich aktiv im Review |
| `needsFix` | Es wurden Änderungen angefordert; der Eigentümer muss vor der erneuten Genehmigung aktualisieren |
| `approved` | Das Review wurde akzeptiert und die Aufgabe ist abgeschlossen |
## Agent-Review-Workflow
Teams können die Arbeit der jeweils anderen prüfen, bevor Sie die endgültige Entscheidung treffen. Das fängt offensichtliche Regressionen ab und hält das Board ehrlich, aber Sie sollten riskante Bereiche dennoch selbst überprüfen.
Ein Agent-Review ist am nützlichsten, wenn der Reviewer ein klares Bewertungsraster hat. Weisen Sie einen Reviewer beispielsweise an, nur die Verständlichkeit der Dokumentation, nur die IPC-Sicherheit oder nur die Testabdeckung zu prüfen. Breite Aufforderungen wie "alles überprüfen" führen tendenziell zu schwächerem Feedback.
### MCP-gesteuerter Review-Zustand
Änderungen des Review-Zustands (Review anfordern, Änderungen anfordern, genehmigen) sind tool-gesteuert. Das Hinterlassen eines Kommentars mit Änderungsanforderung an einer Aufgabe verschiebt die Kanban-Spalte **nicht** auf `needsFix` — ein Lead oder Agent muss das passende MCP-Tool aufrufen:
- `review_request_changes` — verschiebt die Aufgabe auf `needsFix` und benachrichtigt den Eigentümer
- `review_approve` — verschiebt die Aufgabe auf `approved` und schließt das Review ab
Kommentare allein reichen für Zustandsübergänge nicht aus. Die vollständige Liste der Review-MCP-Tools und ihrer Parameter finden Sie unter [MCP-Integration](/de/guide/mcp-integration).
## Review-Teilnehmer
Der Team-Lead ist der Standard-Reviewer. Sie können in den Kanban-Einstellungen zusätzliche Reviewer konfigurieren, wenn Sie möchten, dass Kollegen die Arbeit der jeweils anderen prüfen.
## Was manuell zu prüfen ist
Priorisieren Sie diese Bereiche beim Review:
- **Anbieter-Authentifizierung und Runtime-Erkennung** — hat der Agent die Runtime-Einrichtung so geändert, dass andere Pfade dadurch beeinträchtigt würden?
- **IPC-, Preload- und Dateisystemgrenzen** — halten Sie die Electron-Zuständigkeiten getrennt
- **Git- und Worktree-Verhalten** - überprüfen Sie Branch-Benennung, Commits und Pushes; siehe [Git- und Worktree-Strategie](/de/guide/git-worktree-strategy) für Isolationsmuster.
- **Parsing- und Aufgabenlebenszyklus-Logik** — Änderungen an Aufgabenreferenzen, Chunking oder Filterung können die Nachrichtenzustellung beeinträchtigen
- **Persistenz- und Code-Review-Abläufe** — Änderungen am Aufgabenspeicher oder Review-Zustand müssen über die IPC-Schichten hinweg konsistent bleiben
Den kanonischen Feature-Aufbau und Links zu den harten Guardrails finden Sie unter [Architektur für Mitwirkende](/de/reference/contributor-architecture).
## Verifizierung
Bevorzugen Sie gezielte Verifizierungsbefehle. Breite Formatierungs- oder Lint-Fix-Befehle sollten nicht verwendet werden, sofern die Aufgabe nicht ausdrücklich eine breite Formatierungsänderung beabsichtigt.
Gute Verifizierungskommentare enthalten den Befehl und das Ergebnis:
```text
Verified with `pnpm --dir landing docs:build`. Build passed.
```
Wenn die Verifizierung übersprungen wird, sollte der Aufgabenkommentar den Grund nennen:
```text
Docs-only wording change. Build not run because the existing dev server was busy; checked Markdown links manually.
```
::: warning Nicht projektweit automatisch formatieren
Sofern es bei der Aufgabe nicht ausdrücklich um Formatierung geht, vermeiden Sie es, `pnpm lint:fix` auf nicht zugehörige Dateien auszuführen. Das erzeugt Rauschen in der Review-Oberfläche.
:::

106
landing/product-docs/de/guide/create-team.md Normal file
View file

@ -0,0 +1,106 @@
---
title: Team erstellen – Agent Teams Dokumentation
description: Rollen definieren, Anbieter und Modelle zuweisen, ein Team-Briefing schreiben sowie Worktree-Isolation und Autonomiestufen konfigurieren.
lang: de-DE
---
# Team erstellen
Ein Team ist eine benannte Gruppe von Agenten mit Rollen, einem Lead, einem Zielprojekt und einem Koordinations-Prompt.
## Empfohlenes erstes Team
Beginnen Sie mit einem kleinen Team:
| Rolle | Zweck |
| -------- | ----------------------------------------------------------- |
| Lead | Teilt die Arbeit auf, erstellt Aufgaben, koordiniert Teammitglieder |
| Builder | Setzt abgegrenzte Aufgaben um |
| Reviewer | Überprüft die Ergebnisse, erkennt Regressionen, fordert Korrekturen an |
Dieser Zuschnitt gibt Ihnen genug Koordination, um den Produktnutzen zu sehen, ohne den ersten Start unübersichtlich zu machen.
::: tip
Sie können später weitere Mitglieder hinzufügen. Beginnen Sie klein, validieren Sie den Workflow und skalieren Sie dann hoch.
:::
## Anbieter und Modelle zuweisen
Jedes Teammitglied läuft auf einem Anbieter-Backend. Wählen Sie im Team-Editor für jedes Mitglied einen Anbieter (Claude, Codex oder OpenCode) und ein Modell. Die App zeigt nur Anbieter an, bei denen Sie sich bereits authentifiziert haben.
Das Mischen von Anbietern innerhalb eines Teams wird unterstützt — zum Beispiel ein Claude-Lead mit OpenCode-Buildern.
::: info
Gemini steht als unterstützter Anbieter-Pfad zur Verfügung. Weitere Informationen zu Authentifizierungsoptionen und zum aktuellen Anbieterstatus finden Sie unter [Anbieter und Runtimes](/de/reference/providers-runtimes).
:::
## Ein gutes Team-Briefing schreiben
Das Team-Briefing sollte Folgendes enthalten:
- das gewünschte Ergebnis
- die relevanten Dateien oder Funktionsbereiche
- Risikogrenzen, etwa "keine unbeteiligten Module refaktorieren"
- Erwartungen an das Review
- Verifizierungsbefehle, sofern Sie sie kennen
Beispiel:
```text
Build a focused improvement to the download flow. Keep changes inside the landing app unless a shared helper is clearly needed. Create tasks before implementation, review each task diff, and run landing lint/build checks.
```
## Worktree-Isolation
OpenCode-Mitglieder können die **Worktree-Isolation** nutzen, um in einem separaten Git-Worktree statt im Hauptarbeitsverzeichnis zu arbeiten. Das verhindert Dateikonflikte, wenn mehrere Agenten dasselbe Projekt bearbeiten.
::: warning
Die Worktree-Isolation setzt ein Git-verwaltetes Projekt voraus und ist derzeit auf OpenCode-Mitglieder beschränkt.
:::
Um sie zu aktivieren, schalten Sie die Option **Worktree-Isolation** beim Hinzufügen oder Bearbeiten eines OpenCode-Teammitglieds ein.
## Autonomie wählen
Agent Teams unterstützt verschiedene Kontrollstufen. Nutzen Sie mehr Autonomie für Routineänderungen und engeres Review für riskante Bereiche wie Anbieter-Authentifizierung, IPC, Persistenz, Git-Workflows und Release-Tooling.
### Aufwandsstufe
Jedes Teammitglied hat eine **Aufwand**-Einstellung, die steuert, wie viel Reasoning der Anbieter vor einer Antwort investiert. Höherer Aufwand erzeugt gründlichere Ergebnisse, kostet jedoch Zeit und Tokens.
| Stufe | Wann verwenden |
| ------- | ---------------------------------------------------------- |
| Low | Schnelle Nachschläge, kleine Formatierungsänderungen, Routine-Edits |
| Medium | Standard für die meisten Implementierungsaufgaben |
| High | Komplexe Refactorings, übergreifende Änderungen, riskante Codepfade |
Die App bietet zusätzliche Stufen (minimal, xhigh, max) für Anbieter, die diese unterstützen. Wenn ein Modell keinen konfigurierbaren Aufwand unterstützt, ist die Auswahl deaktiviert und der Standardwert des Anbieters wird verwendet.
### Fast Mode
Schalten Sie pro Mitglied den **Fast Mode** ein, um Geschwindigkeit gegenüber Tiefe zu priorisieren. Dies entspricht dem nativen Fast-/Speed-Modus des Anbieters, sofern verfügbar. Setzen Sie ihn auf **On** für Routineaufgaben, auf **Off** für sorgfältige Arbeit oder auf **Inherit**, um dem teamweiten Standard zu folgen.
### Kontext begrenzen
Aktivieren Sie **Kontext begrenzen**, um das Kontextfenster für ein Mitglied zu verkleinern. Das ist nützlich für Claude-Modelle, die erweiterten Kontext unterstützen (z. B. 1M Tokens) — das Begrenzen des Kontexts vermeidet unnötigen Token-Verbrauch und kann die Latenz für Aufgaben verbessern, die keinen großen Kontext benötigen.
## Kontext hinzufügen
Hängen Sie Dateien, Screenshots oder spezifische Notizen an, wenn sie die Aufgabe wesentlich verändern. Agenten können Aufgabenbeschreibungen, Kommentare und Anhänge als dauerhaften Kontext nutzen.
## Auf Aufgabenqualität achten
Gute Teams erstellen Aufgaben, die:
- spezifisch genug sind, um sie zu überprüfen
- klein genug sind, um sie abzuschließen
- mit sichtbaren Ergebnissen verknüpft sind
- durch einen Verifizierungspfad abgesichert sind
Wenn der Lead vage Aufgaben erstellt, senden Sie eine Direktnachricht mit der Bitte um kleinere, testbare Aufgaben.
## Nächste Schritte
- [Runtime-Einrichtung](/de/guide/runtime-setup) — Anbieter-Authentifizierung und Modelle konfigurieren
- [Code-Review](/de/guide/code-review) — Agentenänderungen akzeptieren, ablehnen oder kommentieren
- [Fehlerbehebung](/de/guide/troubleshooting) — häufige Probleme und Lösungen

102
landing/product-docs/de/guide/git-worktree-strategy.md Normal file
View file

@ -0,0 +1,102 @@
---
title: Git- und Worktree-Strategie – Agent Teams Dokumentation
description: Entscheiden Sie, wann Sie den Haupt-Worktree, Feature-Branches oder die OpenCode-Worktree-Isolierung für parallele Agentenarbeit verwenden.
lang: de-DE
---
# Git- und Worktree-Strategie
Git bietet Agent Teams den stärksten Review-Pfad: schmale Diffs, Branch-Sichtbarkeit, aufgabenbezogene Änderungen und sicherere parallele Arbeit.
## Eine Strategie wählen
| Strategie | Verwenden, wenn | Kompromiss |
| --- | --- | --- |
| Haupt-Worktree | Einzelarbeit, reine Doku-Bearbeitungen oder ein Teammitglied nach dem anderen | Einfach, aber parallele Bearbeitungen können kollidieren |
| Feature-Branch | Ein Team arbeitet an einer zusammenhängenden Änderung | Sauberes Review-Ziel, aber Teammitglieder teilen sich weiterhin Dateien |
| Worktree-Isolierung | Mehrere OpenCode-Teammitglieder bearbeiten möglicherweise dasselbe Repository parallel | Bessere Isolierung, aber Merge/Review erfordert mehr Disziplin |
Fangen Sie einfach an. Fügen Sie die Worktree-Isolierung hinzu, wenn parallele Bearbeitungen wahrscheinlich sind, nicht weil jede Aufgabe ein eigenes Checkout benötigt.
## Wann die Worktree-Isolierung aktiviert werden sollte
Aktivieren Sie sie für OpenCode-Teammitglieder, wenn:
- zwei oder mehr Teammitglieder gleichzeitig dasselbe Repository bearbeiten könnten
- eine Aufgabe Formatierer, Codegeneratoren oder umfangreiche Tests ausführen könnte
- Sie möchten, dass der Branch und das Diff jedes Teammitglieds getrennt bleiben
- der Lead-Workspace unsauber ist und keine direkten Bearbeitungen erhalten sollte
Lassen Sie sie deaktiviert, wenn:
- die Aufgabe schreibgeschützt ist
- ein Teammitglied alle Bearbeitungen verantwortet
- das Repository nicht von Git verfolgt wird
- Sie einen Runtime-Pfad benötigen, der diesen Isolierungsmodus nicht unterstützt
::: warning
Die Worktree-Isolierung gilt derzeit für OpenCode-Mitglieder und erfordert ein von Git verfolgtes Projekt.
:::
## Branch-Hygiene
Bevor Sie parallele Arbeit beginnen:
```bash
git status --short
git branch --show-current
```
Verwenden Sie nach Möglichkeit einen sauberen Branch. Wenn der Haupt-Worktree bereits Benutzeränderungen enthält, weisen Sie die Agenten an, nicht zugehörige Dateien nicht zurückzusetzen, und halten Sie den Aufgabenumfang eng.
Empfohlener Branch-Stil:
```text
agent/<team-or-task>/<short-purpose>
```
Beispiele:
```text
agent/docs/mcp-guide
agent/review/task-log-filtering
agent/ui/code-review-polish
```
## Review-Ablauf
Bei isolierten Worktrees prüfen Sie das Diff des Teammitglieds, bevor Sie Änderungen mergen oder zurück in den Haupt-Workspace übernehmen.
1. Bestätigen Sie, dass der Kommentar zum Aufgabenergebnis den geänderten Umfang und die Verifizierung benennt.
2. Prüfen Sie das Aufgaben-Diff in der Review-UI.
3. Fordern Sie Änderungen an der Aufgabe an, wenn das Diff nicht zugehörige Dateien berührt.
4. Genehmigen Sie erst, nachdem Tests oder manuelle Prüfungen dem Aufgabenrisiko entsprechen.
5. Mergen oder übernehmen Sie Änderungen bewusst.
Mergen Sie Worktree-Ausgaben nicht automatisch, nur weil die Aufgabe abgeschlossen ist. Abschluss bedeutet, dass der Agent die Arbeit für reviewbereit hält.
## Konfliktrichtlinie
Verwenden Sie diese Richtlinie für parallele Teams:
| Situation | Aktion |
| --- | --- |
| Zwei Teammitglieder bearbeiten dieselbe Datei | Pausieren Sie eine Aufgabe oder machen Sie eine Person für die Integration verantwortlich |
| Generierte Dateien wurden umfangreich geändert | Verlangen Sie einen Kommentar, der den Generator und den Befehl erklärt |
| Der Haupt-Worktree enthält nicht zugehörige Änderungen | Bewahren Sie sie auf und prüfen Sie nur die aufgabeneigenen Änderungen |
| Der Worktree-Branch divergiert | Rebasen oder mergen Sie nach dem Review manuell, nicht innerhalb einer vagen Agentenaufgabe |
## Beispiel für einen Aufgaben-Prompt
```text
Implement the settings validation fix in your assigned worktree. Keep edits inside src/features/settings and focused tests. Do not touch provider auth or task storage. Post the test command and result before completing the task.
```
Dieser Prompt funktioniert, weil er den erlaubten Bereich, die sensiblen Grenzen und den Abschlussnachweis benennt.
## Verwandte Anleitungen
- [Team erstellen](/de/guide/create-team)
- [Code-Review](/de/guide/code-review)
- [Team-Briefing-Beispiele](/de/guide/team-brief-examples)
- [Runtime-Einrichtung](/de/guide/runtime-setup)

129
landing/product-docs/de/guide/installation.md Normal file
View file

@ -0,0 +1,129 @@
---
title: Installation – Agent Teams Dokumentation
description: Laden Sie Agent Teams für macOS, Windows oder Linux herunter und installieren Sie es. Behandelt paketierte Builds, Einrichtung aus dem Quellcode, automatische Updates und Voraussetzungen.
lang: de-DE
---
# Installation
Agent Teams wird als Desktop-App für macOS, Windows und Linux ausgeliefert.
::: tip Kürzester Weg
1. Laden Sie unten den Build für Ihre Plattform herunter
2. Starten Sie die App - beginnen Sie mit dem kostenlosen Modell ohne Authentifizierung oder verbinden Sie die Anbieter-Authentifizierung über die Benutzeroberfläche
3. Starten Sie den [Schnellstart](/de/guide/quickstart), um Ihr erstes Team zu erstellen
Start der Desktop-App: Führen Sie `pnpm dev` für die Electron-App aus. Starten Sie für die normale Nutzung nicht den Browser-/Web-Entwicklungsmodus.
:::
## Builds herunterladen
Verwenden Sie die <a href="/de/download/" target="_self">Download-Seite</a> oder das neueste [GitHub-Release](https://github.com/777genius/agent-teams-ai/releases), wenn Sie die paketierte App möchten:
- macOS Apple Silicon: `.dmg`
- macOS Intel: `.dmg`
- Windows: `.exe`
- Linux: `.AppImage`, `.deb`, `.rpm` oder `.pacman`
::: warning Windows SmartScreen
Nicht signierte oder neu veröffentlichte Open-Source-Apps können SmartScreen auslösen. Wenn Sie der Release-Quelle vertrauen, wählen Sie **More info** und dann **Run anyway**.
:::
## Voraussetzungen
Die paketierte App ist auf ein Onboarding ohne Einrichtungsaufwand ausgelegt. Sie können mit dem kostenlosen Modell ohne Authentifizierung beginnen - ohne Registrierung, API-Schlüssel oder Kreditkarte. Wenn Sie weitere Modelle möchten, führt die App Sie über die Benutzeroberfläche durch die Runtime-Erkennung und die Anbieter-Authentifizierung.
Für kostenpflichtige oder kontogebundene Modelle verbinden Sie mindestens einen Anbieter:
| Anbieter | Zugriffsmethode |
| ------------------ | ------------------------------------------------- |
| Claude (Anthropic) | Anmeldung über Claude Code CLI oder API-Schlüssel |
| Codex (OpenAI) | Anmeldung über Codex CLI oder API-Schlüssel |
| Gemini (Google) | Google ADC, Gemini CLI oder API-Schlüssel |
| OpenCode | Enthaltenes kostenloses Modell ohne Authentifizierung oder API-Schlüssel für ein unterstütztes Backend (z. B. OpenRouter) |
::: info
Gemini ist als unterstützter Anbieter-Pfad verfügbar. Siehe [Anbieter und Runtimes](/de/reference/providers-runtimes) für Authentifizierungsoptionen und den aktuellen Status über alle Anbieter hinweg.
:::
Für die Entwicklung aus dem Quellcode benötigen Sie außerdem:
| Werkzeug | Version |
| ------- | ------- |
| Node.js | 24.16.0 LTS |
| pnpm | 10+ |
Unter macOS erfordern die offiziellen vorkompilierten Node.js-24-Binaries macOS 13.5+.
## Aus dem Quellcode ausführen
<InstallBlock command="git clone https://github.com/777genius/agent-teams-ai.git && cd agent-teams-ai && pnpm install && pnpm dev" label="Kopieren" copied-label="Kopiert" />
```bash
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
pnpm dev
```
`pnpm dev` startet die Electron-Desktop-App mit Hot Reload. Dies ist das standardmäßige Entwicklungsziel — starten Sie für die normale Entwicklung keinen Browser-Web-Entwicklungsserver. Dem Browser-Pfad fehlen das vollständige Desktop-IPC, das Terminal, die Anbieter-Authentifizierung und das Verhalten im Team-Lebenszyklus.
Der `main`-Branch enthält die neueste stabile Entwicklung. Wechseln Sie nur dann zu Feature-Branches, wenn Sie eine bestimmte, noch nicht veröffentlichte Änderung benötigen.
## Einrichtung überprüfen
Stellen Sie nach der Installation sicher, dass der Build fehlerfrei ist:
```bash
# Prüfen, ob die Desktop-App kompiliert und startet
pnpm typecheck
# Überprüfen, ob die VitePress-Dokumentationsseite baut
pnpm --dir landing docs:build
```
Wenn `pnpm typecheck` Typfehler meldet, prüfen Sie auf eine neuere Version der Abhängigkeiten oder auf festgepinntes TypeScript. Wenn `pnpm --dir landing docs:build` fehlschlägt, untersuchen Sie `landing/product-docs/` auf Syntaxfehler in Markdown oder Konfiguration.
Wenn Sie diese Dokumentation bearbeiten, führen Sie den Build aus, um Ihre Änderungen zu überprüfen:
```bash
pnpm --dir landing docs:build
```
## Automatische Updates
Die paketierte App prüft beim Start und periodisch während der Ausführung automatisch auf Updates. Wenn ein Update verfügbar ist, fordert die App Sie auf, es herunterzuladen und zu installieren. Sie können auch manuell über das App-Menü prüfen.
::: tip
Automatische Updates sind beim Ausführen aus dem Quellcode nicht verfügbar. Ziehen Sie die neuesten Änderungen und führen Sie `pnpm install` erneut aus, wenn sich Abhängigkeiten ändern.
:::
## Aus dem Quellcode aktualisieren
Wenn Sie aus dem Quellcode ausführen, ziehen Sie den `main`-Branch und führen Sie die Installation erneut aus, wenn sich Abhängigkeiten ändern:
```bash
git pull
pnpm install
```
Überprüfen Sie nach dem Aktualisieren den Build und die Dokumentation:
```bash
pnpm typecheck
pnpm --dir landing docs:build
```
Verwenden Sie für die normale Entwicklung immer `pnpm dev` (Electron) — nicht den Browser-Entwicklungsserver.
## Nächste Schritte
- [Schnellstart](/de/guide/quickstart) — von der Installation bis zum ersten laufenden Team
- [Runtime-Einrichtung](/de/guide/runtime-setup) — Anbieter-Authentifizierung und Modellauswahl pro Runtime
- [Team erstellen](/de/guide/create-team) — empfohlene Teamstrukturen und das Verfassen von Briefings
### Für Mitwirkende
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — Repository-Navigation und Architekturhinweise
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — Arbeitskonventionen und Projektregeln
- [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) — harte Implementierungs-Guardrails

225
landing/product-docs/de/guide/mcp-integration.md Normal file
View file

@ -0,0 +1,225 @@
---
title: MCP-Integration – Agent Teams Dokumentation
description: Konfigurieren Sie MCP in Agent Teams für Board-Operationen, Teamkoordination, externe Tool-Server und die Entwicklung eigener Tools.
lang: de-DE
---
# MCP-Integration
Agent Teams nutzt MCP in zwei praktischen Schichten:
| Schicht | Funktion | Wer es nutzt |
| --- | --- | --- |
| Integrierter Board-Server | Stellt die Tools von Agent Teams für Aufgaben, Nachrichten, Reviews, Prozesse, Runtimes und teamübergreifende Zusammenarbeit bereit | Leads und von der App gestartete Teammitglieder |
| Externe MCP-Server | Fügen optionale Tools hinzu, etwa Browser-Automatisierung, Design-Kontext, Doku-Suche oder Unternehmenssysteme | Benutzer und konfigurierte Runtimes |
Halten Sie diese Schichten getrennt. Der integrierte MCP-Server `agent-teams` ist der Weg, über den Agenten innerhalb von Agent Teams koordinieren. Externe MCP-Server sind optionale Runtime-Tools.
## Wie Agent Teams MCP einspeist
Wenn die Desktop-App Claude-basierte Teammitglieder startet, schreibt sie eine temporäre `--mcp-config`-JSON-Datei, die den integrierten Server `agent-teams` enthält:
```json
{
"mcpServers": {
"agent-teams": {
"command": "node",
"args": ["/path/to/agent-teams-mcp/index.js"],
"env": {
"AGENT_TEAMS_MCP_CLAUDE_DIR": "/Users/you/.claude"
}
}
}
}
```
In der Entwicklung kann der Befehl über `tsx` auf `mcp-server/src/index.ts` zeigen. In paketierten Builds kopiert die App den gebündelten MCP-Server an einen stabilen App-Daten-Pfad und führt ihn mit Node aus. Die generierte Datei gehört der App und wird nach bestem Bemühen wieder bereinigt.
Benutzer- und Projekt-MCP-Server bleiben getrennt. Die App liest installierte Server aus:
| Geltungsbereich | Speicherort |
| --- | --- |
| Benutzer | `~/.claude.json` unter `mcpServers` |
| Lokaler Projekteintrag in der Claude-Konfiguration | `~/.claude.json` unter `projects[projectPath].mcpServers` |
| Projekt | `<project>/.mcp.json` unter `mcpServers` |
Bevorzugen Sie den Projekt-Geltungsbereich für Tools, die zu einem einzelnen Repository gehören. Bevorzugen Sie den Benutzer-Geltungsbereich für Tools, die Sie projektübergreifend wiederverwenden.
## Beispiel für ein Projekt-`.mcp.json`
Legen Sie diese Datei im Projekt-Stammverzeichnis ab, wenn ein Team denselben projektbezogenen Server sehen soll:
```json
{
"mcpServers": {
"docs-search": {
"command": "npx",
"args": ["-y", "@acme/docs-search-mcp"],
"env": {
"DOCS_INDEX_PATH": "./docs-index"
}
},
"local-browser": {
"command": "node",
"args": ["./tools/mcp/browser-server.js"]
}
}
}
```
Halten Sie Geheimnisse aus eingecheckten `.mcp.json`-Dateien heraus. Legen Sie Zugangsdaten in Ihrer Shell, in einer benutzerbezogenen Konfiguration oder im benutzerdefinierten MCP-Installationsablauf der App ab, wenn der Wert lokal bleiben muss.
## Board-MCP-Workflow
Agenten sollten Board-MCP-Tools nutzen, wenn die Arbeit zu einer Aufgabe gehört:
1. Lesen Sie den aktuellen Aufgabenkontext.
2. Starten Sie die Aufgabe erst, wenn Sie tatsächlich mit der Arbeit beginnen.
3. Fügen Sie Aufgabenkommentare für Blocker, Pläne und Endergebnisse hinzu.
4. Markieren Sie die Aufgabe als abgeschlossen, nachdem der Ergebniskommentar gepostet wurde.
5. Senden Sie eine kurze Nachricht, wenn ein Lead oder Teammitglied das Ergebnis kennen muss.
Beispiel für einen Agentenablauf:
```text
task_get -> task_start -> edit/test -> task_add_comment -> task_complete -> message_send
```
Verwenden Sie eine Direktnachricht für die Koordination. Verwenden Sie einen Aufgabenkommentar für eine dauerhafte Aufgabenhistorie.
::: tip
Wenn der Hinweis Review, Verifizierung, geänderten Umfang oder einen Blocker betrifft, hinterlegen Sie ihn an der Aufgabe.
:::
## Integrierte Agent-Teams-Tools
Der MCP-Server registriert Tools aus `agent-teams-controller/src/mcpToolCatalog.js`. Die Registrierungsschleife befindet sich in `mcp-server/src/tools/index.ts`, und jede Gruppe hat ihre eigene Datei unter `mcp-server/src/tools/`.
Häufige Betriebstools:
| Tool | Verwendung |
| --- | --- |
| `task_get` | Liest den aktuellen Aufgabenkontext, Kommentare, Anhänge, Status und Beziehungen |
| `task_start` | Markiert eine Aufgabe als in Arbeit, wenn die Arbeit tatsächlich beginnt |
| `task_add_comment` | Fügt Blocker-Notizen, Verifizierungsnotizen, Pläne und abschließende Ergebniszusammenfassungen hinzu |
| `task_complete` | Schließt eine Aufgabe ab, nachdem der abschließende Ergebniskommentar gepostet wurde |
| `message_send` | Sendet eine sichtbare Posteingangsnachricht an einen Lead, ein Teammitglied oder einen Benutzer |
| `review_request`, `review_start`, `review_approve`, `review_request_changes` | Bewegen aufgabenbezogene Review-Workflows |
| `process_register`, `process_list`, `process_stop`, `process_unregister` | Verfolgen teammitgliedseigene Dev-Server, Watcher und andere Hintergrunddienste |
Tool-Namen können Runtimes mit MCP-Namespace-Präfixen erscheinen, zum Beispiel `mcp__agent-teams__task_get`. Der kanonische Tool-Name innerhalb des MCP-Servers bleibt `task_get`.
## Ein neues integriertes Tool registrieren
Für Arbeiten am Agent-Teams-Repository fügen Sie integrierte Board-Tools über die vorhandene FastMCP-Struktur hinzu:
1. Fügen Sie die Tool-Implementierung in die passende Datei unter `mcp-server/src/tools/` ein, oder erstellen Sie eine neue Gruppendatei, wenn die Domäne tatsächlich neu ist.
2. Fügen Sie den Tool-Namen der entsprechenden Gruppe in `agent-teams-controller/src/mcpToolCatalog.js` hinzu.
3. Binden Sie eine neue Gruppe nur dann über `mcp-server/src/tools/index.ts` ein, wenn eine neue Domänengruppe benötigt wird.
4. Validieren Sie die Eingabe mit `zod` und rufen Sie die Controller-API auf, anstatt Board-Dateien direkt zu lesen.
5. Fügen Sie gezielte Tests in `mcp-server/test/tools.test.ts` hinzu oder einen e2e-Fall, wenn der Transport eine Rolle spielt.
Minimale Struktur:
```ts
server.addTool({
name: 'task_example',
description: 'Explain what this tool does for agents.',
parameters: z.object({
teamName: z.string().min(1),
claudeDir: z.string().min(1).optional(),
taskId: z.string().min(1)
}),
execute: async ({ teamName, claudeDir, taskId }) => {
assertConfiguredTeam(teamName, claudeDir);
const controller = getController(teamName, claudeDir);
return jsonTextContent(controller.tasks.getTask(taskId));
}
});
```
Erstellen Sie kein Tool, das die Controller-Validierung umgeht, unzusammenhängende Team-Dateien verändert oder breiten Datei-/Prozesszugriff ohne eng begrenzten Aufgabenbedarf offenlegt.
## Externe MCP-Server
Verwenden Sie externe MCP-Server, wenn ein Teammitglied eine dauerhafte Tool-Verbindung benötigt und nicht nur einen einzelnen Prompt mit eingefügtem Kontext.
Gute Anwendungsfälle:
- Browser- oder Website-Test-Tools
- Design- oder Produktdaten-Tools
- interne Doku- und Suchsysteme
- Issue-Tracker- oder Support-Systeme
- Datenbankinspektions-Tools mit schreibgeschützten Zugangsdaten
Schlechte Anwendungsfälle:
- Geheimnisse, die in Prompts eingefügt werden
- einmalige Dateien, die direkt angehängt werden können
- Tools, die Produktionssysteme ohne Review verändern
- breiter lokaler Dateisystemzugriff, wenn ein engerer Projekt-Geltungsbereich ausreicht
## Geltungsbereiche
Agent Teams erkennt gemeinsam genutzte und projektorientierte MCP-Geltungsbereiche.
| Geltungsbereich | Verwenden, wenn |
| --- | --- |
| Benutzer oder Global | Derselbe Server soll projektübergreifend verfügbar sein |
| Projekt oder Lokal | Der Server gehört zu einem Repository, Arbeitsbereich oder Team-Kontext |
Bevorzugen Sie den engsten Geltungsbereich, der den Workflow weiterhin nutzbar macht. Projektbezogene Server sind beim Review leichter nachzuvollziehen, weil das Tool zum geänderten Projekt gehört.
## Einrichtungs-Checkliste
Bevor Sie eine Aufgabe zuweisen, die von einem MCP-Server abhängt:
1. Installieren oder konfigurieren Sie den Server.
2. Bestätigen Sie, dass er in der Liste der installierten MCP-Server der App im vorgesehenen Geltungsbereich erscheint.
3. Führen Sie Diagnosen aus der MCP-Registry oder der Erweiterungs-UI aus, sofern verfügbar.
4. Beginnen Sie mit einer risikoarmen, schreibgeschützten Aufgabe.
5. Erwähnen Sie die erwartete MCP-Tool-Nutzung in der Aufgabenbeschreibung oder im Team-Briefing.
Wenn ein Server die Diagnose nicht besteht, beheben Sie das zuerst. Ein besserer Aufgaben-Prompt repariert weder einen fehlenden Befehl noch einen falschen Konfigurationspfad oder abgelehnte Zugangsdaten.
## Einen eigenen Server aus der App installieren
Die Desktop-App stellt MCP-Registry-APIs über Electron-IPC bereit – für Suche, Durchsuchen, Installation, benutzerdefinierte Installation, Deinstallation, das Lesen des Installationszustands und Diagnosen. Benutzerdefinierte Installationen validieren den Servernamen, den Geltungsbereich, den Projektpfad, die Namen der Umgebungsvariablen und die HTTP-Header, bevor der Installationspfad der Runtime aufgerufen wird.
Verwenden Sie die benutzerdefinierte Installation, wenn Sie ein MCP-Paket haben, das noch nicht in der Registry ist:
| Feld | Beispiel |
| --- | --- |
| Servername | `docs-search` |
| Geltungsbereich | `project` für dieses Repository, `user` für alle Projekte |
| Typ | `stdio` für lokale Befehle, `http` oder `sse` für entfernte Server |
| Paket | `@acme/docs-search-mcp` |
| Env | `DOCS_INDEX_PATH=./docs-index` |
Führen Sie nach der Installation eine Diagnose durch und erstellen Sie eine kleine, schreibgeschützte Aufgabe, um die Tool-Oberfläche zu prüfen, bevor Sie größere Arbeit zuweisen.
## Aufgabenbeispiel
```text
Audit the docs home page with the browser MCP. Check desktop and mobile widths, capture any layout issue as a task comment, and only edit landing/product-docs files. Run `pnpm --dir landing docs:build` before completion.
```
Das funktioniert, weil es das Tool, die Oberfläche, die Schreibgrenze und den Verifizierungsschritt benennt.
## Sicherheitsregeln
- Geben Sie nicht standardmäßig jedem Teammitglied jeden MCP-Server.
- Halten Sie schreibfähige Tools aus breiten Teams heraus, sofern der Review sie nicht erfordert.
- Bevorzugen Sie schreibgeschützte Zugangsdaten für Inspektionsaufgaben.
- Stellen Sie produktionswirksame Tool-Nutzung hinter explizite Aufgabenkommentare und Review.
- Behandeln Sie MCP-Diagnosefehler als Einrichtungsfehler, nicht als Agentenfehler.
- Vermeiden Sie es, Geheimnisse in `.mcp.json` oder Prompts einzuchecken.
- Verwenden Sie absolute `projectPath`-Werte, wenn Sie projektbezogene Server über die App installieren.
- Bearbeiten Sie nicht die von der App generierten `agent-teams-mcp-*.json`-Dateien; sie sind temporäre Start-Artefakte.
## Verwandte Anleitungen
- [Runtime-Einrichtung](/de/guide/runtime-setup)
- [Team-Briefing-Beispiele](/de/guide/team-brief-examples)
- [Agent-Workflow](/de/guide/agent-workflow)
- [Entwickler](/de/developers/)

193
landing/product-docs/de/guide/quickstart.md Normal file
View file

@ -0,0 +1,193 @@
---
title: Schnellstart – Agent Teams Dokumentation
description: Kommen Sie in wenigen Minuten von einer frischen Installation zu einem laufenden KI-Agententeam. Behandelt Installation, Runtime-Auswahl, Team-Erstellung und das erste Code-Review.
lang: de-DE
---
# Schnellstart
Diese Anleitung bringt Sie in wenigen Minuten von einer frischen Installation zu einem laufenden Team.
## Kürzester Weg
```bash
# 1. Install prerequisites
node --version # need 20+
pnpm --version # need 10+
# 2. Clone and install
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
# 3. Start the desktop app (default workflow)
pnpm dev
# 4. Verify a docs-only change
pnpm --dir landing docs:build
```
Die Desktop-Electron-App (`pnpm dev`) ist das primäre Ziel — verwenden Sie für die normale Entwicklung nicht den Browser-/Web-Dev-Server. Dem Browser-Pfad fehlen Desktop-IPC, Terminal, Anbieter-Authentifizierung und das Verhalten des Team-Lebenszyklus.
## Bevor Sie beginnen
Sie benötigen:
- **Einen Computer** mit macOS, Windows oder Linux
- **(Empfohlen) Ein Git-getracktes Projekt** — Worktree-Isolierung und Diff-Review setzen Git voraus
- **(Optional) Anbieterzugang** — die Runtime-Einrichtung erkennt verfügbare Anbieter über die UI, aber einige Pfade benötigen vorhandene Authentifizierung (Anthropic, OpenAI usw.)
Falls ein Schritt unten nicht funktioniert, sehen Sie in der [Fehlerbehebungsanleitung](/de/guide/troubleshooting#team-does-not-launch) nach gängigen Lösungen.
Konsultieren Sie für Projektkonventionen und Architekturhinweise diese maßgeblichen Dateien, bevor Sie Änderungen vornehmen:
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — Repo-Navigation und Architektur-Wegweiser
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — Arbeitskonventionen und Projektregeln
- [Feature-Architekturstandard](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) — Struktur für neue Features
- [Debugging-Runbook](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) — Diagnose von Launch und Teammitgliedern
## 1. Aus dem Quellcode ausführen oder herunterladen
**Laden Sie die paketierte App** für macOS, Windows oder Linux von der <a href="/de/download/" target="_self">Download-Seite</a> herunter – keine Voraussetzungen nötig. Beginnen Sie mit dem kostenlosen Modell ohne Authentifizierung oder verbinden Sie die Anbieter-Authentifizierung über die UI, wenn Sie mehr Modelle möchten.
**Oder führen Sie aus dem Quellcode aus** für die Entwicklung:
Erfordert Node.js 24.16.0 LTS und pnpm 10+. Unter macOS erfordern die offiziellen vorkompilierten Node.js-24-Binärdateien macOS 13.5+.
```bash
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
pnpm dev
```
`pnpm dev` startet die Desktop-Electron-App mit Hot Reload. Dies ist das standardmäßige Entwicklungsziel. Starten Sie für die normale Entwicklung keinen Browser-Web-Dev-Server — dem Browser-Pfad fehlen das vollständige Desktop-IPC, das Terminal, die Anbieter-Authentifizierung und das Verhalten des Team-Lebenszyklus.
## 2. Ein Projekt öffnen oder erstellen
Starten Sie die App und wählen Sie das Projektverzeichnis aus, in dem die Agenten arbeiten sollen. Agent Teams liest lokale Projektdateien sowie den Runtime-/Session-Status, damit die UI Aufgaben, Logs, Diffs und die Aktivität der Teammitglieder anzeigen kann.
::: tip
Wählen Sie für die beste Erfahrung ein Git-getracktes Projekt. Sowohl die Worktree-Isolierung als auch das Diff-basierte Review setzen Git voraus.
:::
Bevor Sie ein Team starten, prüfen Sie, ob das Projekt eine ausreichend saubere Ausgangsbasis hat:
```bash
git status --short
```
Sie brauchen keinen perfekt sauberen Baum, aber Sie sollten wissen, welche Änderungen von Ihnen stammen, bevor die Agenten mit dem Bearbeiten beginnen. Das macht Aufgaben-Diffs und das Review auf Hunk-Ebene deutlich vertrauenswürdiger.
## 3. Einen Runtime-Pfad wählen
Der Einrichtungsablauf erkennt installierte Runtimes auf Ihrem Rechner automatisch. Eine gängige erste Einrichtung ist:
| Runtime | Gut für |
| -------- | ----------------------------------------------- |
| Claude | Claude-Code-Nutzer und vorhandenen Anthropic-Zugang |
| Codex | Codex-native Workflows und OpenAI-Zugang |
| OpenCode | Kostenloses Modell ohne Authentifizierung, Multimodell-Teams und viele Anbieter-Backends |
::: info
Gemini ist als unterstützter Anbieterpfad verfügbar. Siehe [Anbieter und Runtimes](/de/reference/providers-runtimes) für Authentifizierungsoptionen und den aktuellen Anbieterstatus.
:::
Siehe [Runtime-Einrichtung](/de/guide/runtime-setup) für eine detaillierte Konfiguration pro Anbieter.
Um eine kostenpflichtige oder kontogebundene Runtime außerhalb der App zu überprüfen, prüfen Sie die Binärdatei und testen Sie die Authentifizierung:
```bash
# Check that the runtime is installed and on PATH
command -v claude && claude --version
command -v codex && codex --version
command -v opencode && opencode --version
```
Wenn der Befehl fehlschlägt, beheben Sie zuerst die Runtime-Installation oder den `PATH`. Team-Prompts können eine fehlende Binärdatei oder eine fehlende Anbieter-Authentifizierung für Modelle, die sie benötigen, nicht umgehen.
::: tip
Wenn die Binärdatei gefunden wird, die App aber "not logged in" meldet, kann sich die Umgebung zwischen Ihrem Terminal und der App unterscheiden. Siehe das [Authentifizierungs-Diagnoselog](/de/guide/troubleshooting#auth-diagnostic-log), um sie zu vergleichen.
:::
## 4. Ihr erstes Team erstellen
Erstellen Sie ein Team mit einem Lead und einem oder mehreren Spezialisten. Halten Sie das erste Team klein: ein Lead, ein Implementierungs-Agent und ein review-orientierter Agent reichen aus, um den Workflow zu validieren.
Siehe [Team erstellen](/de/guide/create-team) für die empfohlene Struktur und Tipps.
Bevorzugen Sie für den ersten Start eine Teamform wie diese:
| Mitglied | Verantwortung | Hinweise |
| --- | --- | --- |
| Lead | Das Ziel in Aufgaben aufteilen und den Status koordinieren | Beim zuverlässigsten Anbieter belassen, den Sie haben |
| Builder | Eng abgegrenzte Aufgaben umsetzen | Klare Datei- oder Feature-Grenzen vorgeben |
| Reviewer | Abgeschlossene Arbeit überprüfen | Bitten Sie ihn, sich auf Regressionen und fehlende Tests zu konzentrieren |
Vermeiden Sie es, mit fünf oder mehr Teammitgliedern zu beginnen. Mehr Agenten erhöhen Parallelität, Logs, Anbieternutzung und Konfliktrisiko, bevor Sie wissen, dass die Einrichtung gesund ist.
## 5. Dem Lead ein konkretes Ziel geben
Formulieren Sie das Ziel so, wie Sie einen Engineering-Lead briefen würden:
```text
Improve the onboarding flow. Split the work into tasks, keep changes small, and ask for review before broad refactors.
```
Gute erste Prompts enthalten konkreten Umfang, Sicherheitsgrenzen und Verifizierung:
```text
Improve the docs quickstart. Keep edits inside landing/product-docs. Add practical examples, preserve existing VitePress syntax, and run `pnpm --dir landing docs:build` before marking tasks done.
```
Vermeiden Sie für den ersten Lauf vage Prompts wie "make the app better". Der Lead kann große Ziele aufschlüsseln, aber bessere Eingaben führen zu kleineren Aufgaben und einem saubereren Review.
::: tip
Wenn das Team startet, aber keine Aufgaben erscheinen, prüfen Sie, ob der Lead Ihren Prompt erhalten hat. Siehe [Antworten der Agenten fehlen](/de/guide/troubleshooting#agent-replies-are-missing) für die Diagnose.
:::
Der Lead erstellt Aufgaben, weist Arbeit zu und koordiniert die Teammitglieder. Sie können den Fortschritt auf dem Kanban-Board verfolgen und jederzeit mit Kommentaren oder Direktnachrichten eingreifen.
## 6. Ergebnisse überprüfen
Öffnen Sie abgeschlossene oder review-bereite Aufgaben, prüfen Sie das Diff und akzeptieren, lehnen Sie ab oder kommentieren Sie einzelne Änderungen. Verwenden Sie die Aufgaben-Logs, wenn Sie verstehen müssen, warum ein Agent eine Entscheidung getroffen hat.
Siehe [Code-Review](/de/guide/code-review) für den vollständigen Review-Workflow.
Bevor Sie die erste Aufgabe genehmigen, prüfen Sie drei Dinge:
1. Der Aufgabenkommentar erklärt, was sich geändert hat
2. Die geänderten Dateien entsprechen dem Aufgabenumfang
3. Das Verifizierungsergebnis ist im Aufgabenkommentar oder in den Logs sichtbar
## Häufige Fallstricke
| Symptom | Wahrscheinliche Ursache | Prüfen |
| --- | --- | --- |
| App erkennt eine Runtime nicht | Binärdatei nicht im `PATH`, oder App und Terminal sehen unterschiedliche Umgebungen | Führen Sie `command -v <runtime>` in einem Terminal aus und starten Sie die App dann mit derselben Terminal-Umgebung |
| Team-Launch hängt | Fehlende Anbieter-Authentifizierung für ein kostenpflichtiges/kontogebundenes Modell, falscher Modell-String oder Runtime-Binärdatei nicht gefunden | Siehe [Fehlerbehebung](/de/guide/troubleshooting#team-does-not-launch) |
| OpenCode-Lane bleibt auf `registered` hängen | Lane-Nachweis noch nicht committet, oder Modell-String-Diskrepanz | Untersuchen Sie `~/.claude/teams/<team>/.opencode-runtime/lanes/` |
| Antworten der Agenten fehlen | Problem mit Runtime-Zustellung, Wiederholung, Parsing oder Aufgabenzuordnung | Öffnen Sie die Aufgaben-Logs und prüfen Sie das Zustellungs-Ledger |
| Anbieter liefert 429er | Ratenlimit erreicht | Auf das Zurücksetzen warten oder Modell/Anbieter wechseln |
## Nächste Schritte
- [Team erstellen](/de/guide/create-team) — empfohlene Teamformen und das Schreiben von Briefings
- [Runtime-Einrichtung](/de/guide/runtime-setup) — Anbieter-Authentifizierung und Modellauswahl
- [Code-Review](/de/guide/code-review) — überprüfen, genehmigen oder Änderungen anfordern
### Für Mitwirkende
Wenn Sie Agent Teams oder diese Dokumentation ändern, beginnen Sie mit den maßgeblichen Projektdateien im Repo-Stammverzeichnis:
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — Arbeitskonventionen und Projektregeln
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — Navigationsebene für Architektur- und Implementierungshinweise
- [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) — harte Implementierungs-Guardrails
- [Feature-Architekturstandard](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) — Struktur für neue Features
- [Debugging-Runbook für Agent-Teams](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) — Diagnose von Launch, Bootstrap und Teammitgliedern
Um zu überprüfen, ob diese Dokumentationsseite korrekt baut:
```bash
pnpm --dir landing docs:build
```

179
landing/product-docs/de/guide/runtime-setup.md Normal file
View file

@ -0,0 +1,179 @@
---
title: Runtime-Einrichtung – Agent Teams Dokumentation
description: Konfigurieren Sie die Runtimes Claude Code, Codex oder OpenCode. Behandelt Authentifizierung, Anbieterzugriff, Multimodell-Modus und Prüfungen vor dem Start.
lang: de-DE
---
# Runtime-Einrichtung
Agent Teams ist eine Koordinationsebene. Die eigentliche Modellarbeit läuft über unterstützte lokale Runtimes und Anbieter.
::: tip Schnellstart - die erste Runtime auswählen
| Wenn Sie ... | Beginnen Sie mit |
| --- | --- |
| Bereits Claude Code nutzen oder Zugriff auf Anthropic haben | **Claude** - vertraute Authentifizierung, minimale Einrichtung |
| Codex oder OpenAI-basierte Workflows nutzen | **Codex** - native Integration |
| Agent Teams ohne Registrierung oder API-Schlüssel ausprobieren möchten | **OpenCode** - nutzen Sie das enthaltene kostenlose Modell ohne Authentifizierung |
| Multimodell-Routing oder breite Anbieterabdeckung möchten | **OpenCode** - am flexibelsten, eine Konfiguration für viele Backends |
| Nicht sicher sind, welche Runtime passt | **OpenCode** - deckt die meisten Anbieteroptionen ab und lässt Sie später wechseln |
Beginnen Sie mit einer Runtime und einem Teammitglied. Bestätigen Sie, dass ein Start funktioniert, bevor Sie auf Multimodell erweitern.
:::
## Voraussetzungen
Stellen Sie vor dem Start eines Teams sicher, dass:
- Die Runtime-Binärdatei installiert ist und sich in Ihrem `PATH` befindet.
- Ihr Anbieterkonto aktiven Zugriff auf das Modell hat, das Sie verwenden möchten, es sei denn, Sie beginnen mit dem enthaltenen kostenlosen OpenCode-Modell ohne Authentifizierung.
- Der Projektpfad existiert und lesbar ist.
- Die App und Ihr Terminal dieselbe Home-/Konfigurationsumgebung verwenden, wenn Sie die Authentifizierung manuell testen.
::: tip
Beginnen Sie mit einem einzelnen Teammitglied und einem Anbieter. Bestätigen Sie, dass ein Start funktioniert, bevor Sie Multimodell-Lanes hinzufügen.
:::
Schnelle Terminal-Prüfungen:
```bash
command -v claude
command -v codex
command -v opencode
```
Führen Sie den Befehl für die Runtime aus, die Sie verwenden möchten. Wenn nichts ausgegeben wird, installieren Sie die Runtime oder korrigieren Sie den `PATH`, bevor Sie ein Team starten.
## Unterstützte Pfade
| Pfad | Standard-CLI | Typische Anbieter | Verwenden, wenn |
| --- | --- | --- | --- |
| Claude | `claude` | Anthropic | Sie bereits Claude Code oder Anthropic-gestützte Workflows nutzen |
| Codex | `codex` | OpenAI | Sie eine Codex-native Runtime-Integration möchten |
| OpenCode | `opencode` | OpenRouter und viele Backends | Sie Multimodell-Routing und breite Anbieterabdeckung möchten |
Die App erkennt unterstützte Runtimes und leitet die Einrichtung nach Möglichkeit über die Oberfläche an.
Gemini ist als unterstützter Anbieterpfad mit Google ADC (`gcloud auth`), Gemini CLI OAuth und API-Schlüssel-Authentifizierung verfügbar. Konfigurieren Sie es über die Oberfläche zur Runtime-Einrichtung, wenn das Gemini-Backend erkannt wird.
## Anbieterzugriff
Agent Teams hat keine eigene kostenpflichtige Stufe. Sie können mit dem enthaltenen kostenlosen OpenCode-Modell ohne Authentifizierung beginnen - keine Registrierung, keine API-Schlüssel, keine Kreditkarte. Für zusätzliche Modelle bringen Sie den Anbieterzugriff mit, den Sie bereits haben: Abonnements, lokale Runtime-Authentifizierung oder API-Schlüssel, je nach gewähltem Pfad.
- Die Pfade **Claude** und **Codex** stützen sich auf ihre jeweiligen CLI-Authentifizierungstools.
- **OpenCode** kann zunächst das enthaltene kostenlose Modell ohne Authentifizierung ausführen. Andere OpenCode-Modelle benötigen möglicherweise anbieterspezifische API-Schlüssel in einer Konfigurationsdatei (z. B. `openrouter`, `openai`, `anthropic`).
## Authentifizierungskonfiguration
### Claude Code
Führen Sie den standardmäßigen Authentifizierungsablauf in einem Terminal aus:
```bash
claude login
```
Überprüfen Sie dann, ob die CLI erreichbar ist:
```bash
claude --version
```
Wenn die paketierte App "nicht angemeldet" meldet, während Ihr Terminal funktioniert, vergleichen Sie die von der App gesehenen `$HOME`- und `PATH`-Werte mit dem Terminal, das Sie für die Anmeldung verwendet haben. Das in der [Fehlerbehebung](/de/guide/troubleshooting#auth-diagnostic-log) beschriebene Authentifizierungs-Diagnoseprotokoll ist der beste Ausgangspunkt.
### Codex
Installieren und authentifizieren Sie sich über den CLI-Ablauf von OpenAI:
```bash
codex login
```
Überprüfen Sie dann, ob die Runtime erreichbar ist:
```bash
codex --version
```
Codex-native Starts verwenden den Codex-Kontostatus und Modellkatalogdaten, sofern verfügbar. Wenn ein Modell in der Oberfläche fehlt, aktualisieren Sie den Anbieterstatus, bevor Sie Team-Prompts bearbeiten.
### OpenCode
Um das enthaltene kostenlose Modell ohne Authentifizierung zu verwenden, wählen Sie es in der App aus und starten Sie ohne Anbieterregistrierung. Um andere OpenCode-Backends zu verwenden, erstellen oder bearbeiten Sie `~/.opencode/config.json` (oder den entsprechenden Pfad auf Ihrer Plattform) mit dem gewünschten Anbieterschlüssel:
```json
{
"providers": {
"openrouter": {
"apiKey": "sk-or-..."
}
}
}
```
Verwenden Sie den genauen Anbieternamen, den OpenCode erwartet. Wenn Sie einen benutzerdefinierten Anbieternamen festlegen, überprüfen Sie ihn anhand der Anbieter-ID, die Sie im Modell-String verwenden (zum Beispiel würde `openrouter/moonshotai/kimi-k2.6` den `openrouter`-Block verwenden).
Beispiele für Modell-Strings:
| Modell-String | Anbieterblock, der vorhanden sein muss |
| --- | --- |
| `openrouter/moonshotai/kimi-k2.6` | `openrouter` |
| `openai/gpt-5.4` | `openai` |
| `anthropic/claude-sonnet-4-6` | `anthropic` |
Wenn OpenCode startet, ein Teammitglied aber nie zustellbar wird, prüfen Sie die Lane-Belege, bevor Sie annehmen, dass das Modell den Prompt ignoriert hat. Siehe [Fehlerbehebung](/de/guide/troubleshooting#opencode-registered-but-bootstrap-unconfirmed).
### Gemini
Gemini unterstützt drei Authentifizierungsmethoden:
- **Google ADC** — führen Sie `gcloud auth application-default login` aus, um sich über Google Application Default Credentials zu authentifizieren.
- **Gemini CLI** — führen Sie `gemini login` aus, wenn die Gemini CLI installiert ist.
- **API-Schlüssel** — setzen Sie `GEMINI_API_KEY` in Ihrer Umgebung oder konfigurieren Sie ihn über die Oberfläche „Manage Providers“ der App.
Die App erkennt automatisch, welche Authentifizierungsmethode verfügbar ist, und zeigt den Gemini-Anbieter in der Oberfläche zur Runtime-Einrichtung und Teamerstellung an, wenn das Backend erreichbar ist.
## Multimodell-Modus
Der Multimodell-Modus kann Arbeit über viele Anbieter-Backends mittels OpenCode-kompatibler Konfiguration routen. Verwenden Sie ihn, wenn Sie Anbieterflexibilität benötigen oder möchten, dass Teammitglieder unterschiedliche Modell-Lanes nutzen.
::: info Modell-Lanes
Jedes Teammitglied kann ein anderes Paar aus `providerId` + `model` verwenden. Erweitern Sie in der Oberfläche zur Teambearbeitung die Mitgliedsoptionen, um die globalen Standardwerte zu überschreiben.
:::
Ein konservatives Multimodell-Setup:
| Rolle | Anbieter | Warum |
| --- | --- | --- |
| Lead | Claude oder Codex | Halten Sie die Koordination beim Anbieter, dem Sie am meisten vertrauen |
| Builder | OpenCode | Nutzen Sie breites Modell-Routing für Implementierungsarbeit |
| Reviewer | Claude, Codex oder ein zweites OpenCode-Modell | Trennen Sie das Review-Urteil von der Builder-Lane |
Vermeiden Sie es, beim ersten Start viele unbekannte Anbieter zu mischen. Bestätigen Sie eine kleine Aufgabe pro Lane, bevor Sie umfangreiche Arbeit zuweisen.
## Checkliste vor dem Start
Vor dem Start eines Teams:
1. Die ausgewählte Runtime ist installiert
2. Die Runtime-Binärdatei befindet sich im `PATH` der Umgebung
3. Die Anbieter-Authentifizierung ist für das gewählte Backend konfiguriert
4. Der Anbieter hat Zugriff auf den genauen Modell-String, den Sie angeben
5. Der Projektpfad existiert und ist lesbar
## Wann Runtime-Pfade gewechselt werden sollten
Wechseln Sie, wenn der aktuelle Pfad durch Modellverfügbarkeit, Ratenbegrenzungen, Anbieterfähigkeiten oder Anforderungen an Teamrollen blockiert ist. Behalten Sie denselben Projekt- und Team-Workflow bei, validieren Sie aber nach dem Wechsel eine kleine Aufgabe.
::: warning Behandeln Sie Einrichtungsfehler als Einrichtungsprobleme
Wenn die Authentifizierung fehlschlägt, ein Modellname abgelehnt wird oder die Runtime-Binärdatei nicht gefunden werden kann, beheben Sie zuerst die Einrichtung. Ändern Sie keine Team-Prompts oder Projektcode, um ein Problem mit der Runtime-Konfiguration zu umgehen.
:::
Verwenden Sie diese Entscheidungstabelle:
| Symptom | Bessere erste Maßnahme |
| --- | --- |
| Binärdatei nicht gefunden | Installation oder `PATH` korrigieren |
| Anmeldung funktioniert im Terminal, aber nicht in der App | Electron-Authentifizierungs-Diagnoseprotokoll und Umgebung prüfen |
| Modell abgelehnt | Genaue Modell-ID in der Anbieter-Runtime überprüfen |
| Wiederholte 429er | Parallelität senken oder Modell/Anbieter wechseln |
| OpenCode-Lane hängt | Lane-Manifest und `opencode-sessions.json` prüfen |

131
landing/product-docs/de/guide/team-brief-examples.md Normal file
View file

@ -0,0 +1,131 @@
---
title: Team-Briefing-Beispiele – Agent Teams Dokumentation
description: Praktische Team-Briefing-Vorlagen für kleine Korrekturen, Dokumentationsarbeit, Implementierungsaufgaben, Reviews und Hochrisikobereiche.
lang: de-DE
---
# Team-Briefing-Beispiele
Ein gutes Team-Briefing gibt dem Lead genug Struktur, um kleine Aufgaben zu erstellen, ohne jedes Implementierungsdetail im Voraus festzulegen.
Verwenden Sie folgendes Schema:
```text
Outcome:
Scope:
Boundaries:
Coordination:
Verification:
Review:
```
## Minimales Briefing
Für kleine, risikoarme Arbeiten verwenden.
```text
Outcome: Improve the quickstart so a new user can launch one team successfully.
Scope: Keep edits inside landing/product-docs.
Boundaries: Do not rewrite the whole docs structure.
Coordination: Create one or two tasks, keep comments on the task.
Verification: Run `pnpm --dir landing docs:build`.
Review: Summarize changed pages and any remaining gaps.
```
## Implementierungs-Briefing
Verwenden, wenn Codeänderungen einen Funktionsbereich betreffen.
```text
Outcome: Add a focused improvement to task comment filtering.
Scope: Work inside the task/comment feature files unless a shared helper is clearly needed.
Boundaries: Do not change task storage format or review state semantics.
Coordination: Split parser, UI, and tests into separate tasks if they can be reviewed independently.
Verification: Run the focused unit tests first, then the feature typecheck if touched.
Review: Call out parsing edge cases and any behavior that affects existing task comments.
```
## Dokumentations-Briefing
Für Dokumentations- und Anleitungsarbeit verwenden.
```text
Outcome: Draft practical workflow guides from the docs audit.
Scope: Add concise VitePress pages under landing/product-docs/guide.
Boundaries: Avoid moving existing navigation hubs owned by other tasks.
Coordination: Check related docs tasks before editing nav.
Verification: Run `pnpm --dir landing docs:build`.
Review: Include links added to sidebar and any pages intentionally left as drafts.
```
## Review-intensives Briefing
Für riskante Bereiche wie IPC, Anbieter-Authentifizierung, Persistenz, Git oder Logik des Aufgaben-Lebenszyklus verwenden.
```text
Outcome: Fix the launch failure without changing successful launch behavior.
Scope: Start from the newest launch-failure artifact and the affected runtime adapter.
Boundaries: Do not change provider prompts until setup and runtime evidence are inspected.
Coordination: Make one diagnostic task and one fix task if the cause is confirmed.
Verification: Run focused tests and one desktop smoke check when practical.
Review: Lead must inspect the diff before approval.
```
## Briefing für gemischte Anbieter
Verwenden, wenn Teammitglieder unterschiedliche Anbieter-/Modell-Lanes nutzen.
```text
Outcome: Implement and review a small feature using separate builder and reviewer lanes.
Scope: Builder edits the feature. Reviewer inspects only the task diff and tests.
Boundaries: Do not switch model ids mid-task unless launch fails before work begins.
Coordination: Builder posts result comment first. Reviewer posts findings as task comments.
Verification: Builder runs focused tests. Reviewer checks failure output and changed scope.
Review: Lead approves only after reviewer comments are resolved.
```
## Agent-Blöcke in Briefings
Agent-Blöcke sind versteckter, ausschließlich für Agenten bestimmter Text, der in Markierungen wie `<info_for_agent>...</info_for_agent>` eingeschlossen ist. Die App entfernt sie aus der normalen Anzeige, hält sie aber für die Agentenkoordination verfügbar. Verwenden Sie sie, wenn das Briefing den Agenten etwas mitteilen muss, das für einen menschlichen Leser nur Rauschen wäre.
Beispiel – ein Briefing, das dem Lead mitteilt, wie die Arbeit aufgeteilt werden soll, ohne die Koordinationsanweisungen dem Benutzer preiszugeben:
```text
Outcome: Add a dark mode toggle to the application settings.
Scope: Settings UI, theme context, and CSS variables.
Boundaries: Do not change existing light theme values or provider auth screens.
<info_for_agent>
Split this into three tasks: (1) theme context and CSS vars, (2) toggle component and settings wiring, (3) dark mode preview in existing docs screenshots if practical.
</info_for_agent>
```
Der Block hält das an Menschen gerichtete Briefing übersichtlich und gibt dem Lead gleichzeitig eine strukturierte Anleitung zur Aufgabenaufteilung.
## Was zu vermeiden ist
| Schwaches Briefing | Bessere Alternative |
| --- | --- |
| „Verbessere die App" | Benennen Sie den Workflow, die Dateien und die Erfolgsprüfung |
| „Behebe alle Docs" | Wählen Sie eine Anleitungsgruppe und einen Build-Befehl |
| „Nutze das beste Modell" | Benennen Sie Anbieter-/Modellauswahl oder lassen Sie die App-Standards gelten |
| „Refaktoriere nach Bedarf" | Geben Sie an, welche Module geändert werden dürfen |
| „Mach es produktionsreif" | Definieren Sie Review, Tests und Rollout-Prüfungen |
## Vor dem Start
Prüfen Sie diese Punkte, bevor Sie das Team starten:
1. Das Briefing benennt ein konkretes Ergebnis.
2. Risikogrenzen sind explizit.
3. Der Lead kann die Arbeit in überprüfbare Aufgaben aufteilen.
4. Verifizierungsbefehle sind enthalten, sofern bekannt.
5. Sensible Bereiche erfordern eine Überprüfung vor der Freigabe.
Wenn das Briefing noch zu breit ist, starten Sie zunächst einen Solo-Agenten oder ein kleines Team und bitten Sie es, einen Aufgabenplan statt einer Implementierung zu erstellen.
## Verwandte Anleitungen
- [Team erstellen](/de/guide/create-team)
- [MCP-Integration](/de/guide/mcp-integration)
- [Git- und Worktree-Strategie](/de/guide/git-worktree-strategy)

310
landing/product-docs/de/guide/troubleshooting.md Normal file
View file

@ -0,0 +1,310 @@
---
title: Fehlerbehebung – Agent Teams Dokumentation
description: Beheben Sie Probleme beim Team-Start, fehlende Agent-Antworten, Ratenbegrenzungen, CLI-Authentifizierungsprobleme und Hänger beim Lane-Bootstrap mit lokalen Diagnosen.
lang: de-DE
---
# Fehlerbehebung
Die meisten Team-Probleme fallen in eine von vier Kategorien: Runtime-Einrichtung, Start-Bestätigung, Aufgaben-Parsing und Anbieterlimits.
## Schnelle Beweissicherung
Definieren Sie bei jedem Problem im Team-Lebenszyklus zuerst diese Variablen und verwenden Sie dieselbe Shell weiter:
```bash
TEAM="<team-name>"
TEAM_DIR="$HOME/.claude/teams/$TEAM"
TASKS_DIR="$HOME/.claude/tasks/$TEAM"
```
Bestätigen Sie dann, dass die erwarteten Dateien existieren, bevor Sie den UI-Zustand interpretieren:
```bash
test -d "$TEAM_DIR" && find "$TEAM_DIR" -maxdepth 2 -type f | sort | sed -n '1,80p'
test -d "$TASKS_DIR" && find "$TASKS_DIR" -maxdepth 1 -name '*.json' | sort | sed -n '1,40p'
```
::: warning Beweise zuerst
Beheben Sie Prompts, Anbietereinstellungen oder Prozessbereinigungen nicht allein auf Basis eines hängenden Badges. Korrelieren Sie zuerst die UI mit den persistierten Dateien, Start-Artefakten und Runtime-Beweisen.
:::
## Team startet nicht
Prüfen Sie jeden Punkt der Reihe nach:
1. **Runtime verfügbar** — die ausgewählte CLI (`claude`, `codex`, `opencode`) ist installiert
2. **PATH erreichbar** — die Binärdatei ist im `PATH` der Umgebung verfügbar
3. **Modellzugriff** — der Anbieter hat Zugriff auf die angeforderte Modellzeichenfolge (besonders bei OpenCode sind exakte Anbieter-/Modellnamen wichtig)
4. **Projektpfad** — das Projektverzeichnis existiert und ist lesbar
5. **Netzwerk / VPN** — manche Anbieter verwerfen Datenverkehr, wenn ein VPN aktiv ist
::: tip
Führen Sie die Runtime-Binärdatei in einem Terminal aus, um `PATH` und Authentifizierung zu überprüfen. Beispiel: `claude --version` oder `opencode --version`.
:::
### OpenCode: registriert, aber Bootstrap unbestätigt
Wenn OpenCode `registered` anzeigt, der Bootstrap aber unbestätigt ist, untersuchen Sie zuerst die Artefakte, bevor Sie Team-Prompts ändern.
Details für Mitwirkende/zur Fehlersuche finden Sie unter [Architektur für Mitwirkende](/de/reference/contributor-architecture), die auf das maßgebliche Debugging-Runbook für Agent-Teams verweist.
Sehen Sie sich das neueste Artefakt eines fehlgeschlagenen Starts an:
```bash
LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
MANIFEST_PATH="$(jq -r '.manifestPath' "$LATEST_FAILURE")"
jq '.classification, .bootstrapTransportBreadcrumb, .memberSpawnStatuses' "$MANIFEST_PATH"
```
`latest.json` verweist auf das neueste gepackte Artefaktverzeichnis und dessen `manifest.json`. Das Manifest enthält:
- `classification` — warum der Start als Fehlschlag gewertet wurde
- `bootstrapTransportBreadcrumb` — verwendeter Zustellungspfad
- Spawn-Status der Mitglieder
- Redigierte Logs und Traces
Prüfen Sie auch das Lane-Manifest:
```bash
jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime/lanes" -maxdepth 2 -name manifest.json -print -exec jq '.activeRunId, .entries' {} \; 2>/dev/null
```
::: tip Nicht aus der UI raten
Korrelieren Sie UI-Diagnosen immer mit persistierten Dateien (`launch-state.json`, `bootstrap-journal.jsonl`) und runtime-spezifischen Beweisen.
:::
## Allgemeine Diagnose
Beginnen Sie mit den persistierten Dateien auf dem Datenträger statt allein mit der UI.
### Team-Wurzelverzeichnis
```bash
printf '%s\n' "$TEAM_DIR"
```
Wichtige Dateien und was sie Ihnen verraten:
- `launch-state.json` — Start-/Lebendigkeitszustand der Mitglieder (`.teamLaunchState`, `.summary`, `.members`)
- `bootstrap-journal.jsonl` — geordnete Bootstrap-Ereignisse von CLI/Runtime (`tail -80`)
- `bootstrap-state.json` — Zusammenfassung der Bootstrap-Phase
- `config.json` — Anbieter-, Modell- und Projektkonfiguration
- `inboxes/*.json` und `sentMessages.json` — Zustand der Nachrichtenzustellung
```bash
jq '.teamLaunchState, .summary, .members' "$TEAM_DIR/launch-state.json"
tail -80 "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
```
### OpenCode-Runtime-Beweise
Bei OpenCode-Teammitgliedern liegt der Sitzungsbeweis im Lane-Runtime-Speicher:
- `.opencode-runtime/lanes.json` — Lane-Index mit Zustand
- `.opencode-runtime/lanes/<lane>/manifest.json` — `activeRunId` und Beweiseinträge
- `.opencode-runtime/lanes/<lane>/opencode-sessions.json` — committete Sitzungsdatensätze
Erwarteter gesunder Zustand: Lane-Zustand `active`, das Manifest hat eine `activeRunId` mit mindestens einem Beweiseintrag, das Mitglied hat `bootstrapConfirmed: true`.
```bash
jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime" -maxdepth 3 -type f | sort
```
### Artefakte fehlgeschlagener Starts
Wenn ein Start als Fehlschlag markiert ist, untersuchen Sie `latest.json`:
```bash
LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
jq '.' "$LATEST_FAILURE"
jq '.' "$(jq -r '.manifestPath' "$LATEST_FAILURE")"
```
Das Manifest enthält:
- `classification` — warum der Start als Fehlschlag gewertet wurde
- `bootstrapTransportBreadcrumb` — verwendeter Zustellungspfad
- Spawn-Status der Mitglieder und redigierte Logs/Traces
## Agent-Antworten fehlen
Öffnen Sie Aufgabenprotokolle und Teammitglied-Nachrichten. Fehlende Antworten kommen häufig von:
- **Erneuter Zustellversuch der Runtime** — der Agent hat möglicherweise geantwortet, aber die Nachricht wurde nicht an die App zugestellt. Prüfen Sie das Zustellungsregister.
- **Parsing oder Filterung** — die Agent-Ausgabe enthielt nicht die erwarteten Marker oder Aufgabenreferenzen.
- **Aufgabenzuordnung** — die Arbeit fand während der Sitzung statt, wurde aber nicht mit der Aufgabe verknüpft, weil die korrekte Aufgaben-ID in der Ausgabe fehlte.
::: warning Schweigen nicht mit Ignorieren gleichsetzen
Gehen Sie nicht davon aus, dass das Modell die Nachricht ignoriert hat, bevor Logs dies bestätigen.
:::
Nutzen Sie den persistierten Nachrichtenzustand, um „nicht gesendet" von „gesendet, aber nicht gerendert" zu unterscheiden:
```bash
jq '.' "$TEAM_DIR/inboxes/user.json" 2>/dev/null
jq '.' "$TEAM_DIR/sentMessages.json" 2>/dev/null
```
Prüfen Sie `from`, `to`, `messageId`, `relayOfMessageId` und `taskRefs`. Untersuchen Sie bei OpenCode-Teammitgliedern auch die Runtime-Zustellungsbeweise, bevor Sie annehmen, dass das Modell den Prompt ignoriert hat.
## Aufgaben sind nicht mit Änderungen verknüpft
Verwenden Sie aufgabenspezifische Logs und Code-Review-Links. Wenn ein Diff losgelöst erscheint:
- Prüfen Sie, ob die Aufgaben-ID oder Aufgabenreferenz in der Agent-Ausgabe enthalten war.
- Verifizieren Sie, dass der Agent `task_add_comment` aufgerufen hat, bevor er Änderungen vorgenommen hat.
- Stellen Sie sicher, dass der Agent `task_start` aufgerufen hat, damit das Board weiß, dass die Arbeit begonnen hat.
Bei OpenCode-Teammitgliedern liegt der maßgebliche Beweis dafür, dass eine Sitzung zu einer Aufgabe gehört, in `opencode-sessions.json` und dem Eintrag im Lane-Manifest, nicht allein im UI-Nachrichtenstrom.
### Aufgabenprotokoll-Triage
Wenn ein Aufgabenprotokoll unvollständig erscheint, suchen Sie nach der Aufgaben-ID über Aufgaben-JSON, Inboxes und Bootstrap-Ereignisse hinweg:
```bash
TASK="<short-or-full-task-id>"
rg -n "$TASK" "$TASKS_DIR" "$TEAM_DIR/inboxes" "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
```
Interpretieren Sie das Ergebnis sorgfältig:
| Beweis | Was er belegt | Was er nicht belegt |
| --- | --- | --- |
| Nachricht zugestellt | Die App hat einen Prompt geschrieben oder weitergeleitet | Der Agent hat Fortschritt erzielt |
| Aufgabenkommentar | Der Agent hat board-sichtbaren Text gepostet | Der Kommentar ist bedeutsamer Fortschritt |
| Native Tool-Zeilen | Die Runtime hat in einer Sitzung gearbeitet | Die Arbeit gehört zu dieser Aufgabe, sofern die Zuordnung nicht passt |
| Eintrag im Änderungsregister | Die App hat Dateiänderungen aufgezeichnet | Die Implementierung ist korrekt |
Bei OpenCode enthält ein gesundes Aufgabenprotokoll üblicherweise native Runtime-Zeilen wie `read`, `bash`, `edit` oder `write` plus Agent-Teams-MCP-Zeilen. Wenn Sie nur `agent-teams_*`-Zeilen sehen, bestätigen Sie die Aufgabenzuordnung und Sitzungsgrenzen, bevor Sie die Log-Übereinstimmung erweitern.
## Ratenbegrenzungen
Wenn ein Anbieter eine bekannte Reset-Zeit meldet, kann Agent Teams den Lead anstoßen, nach der Abkühlphase fortzufahren. Ist die Reset-Zeit unbekannt, warten Sie oder wechseln Sie den Anbieter-/Runtime-Pfad.
| Anbieterverhalten | Empfohlene Maßnahme |
| --- | --- |
| Bekannte Reset-Zeit angezeigt | Auf Abkühlphase warten und fortfahren |
| Keine Reset-Zeit angezeigt | Anbieter oder Runtime-Pfad wechseln |
| Wiederholte 429er | Nebenläufigkeit senken oder eine andere Modell-Lane verwenden |
## CLI-Authentifizierungsprobleme
### `claude login` bleibt nicht erhalten
Wenn die CLI in einem Terminal authentifiziert ist, die App aber meldet, dass dies nicht der Fall ist, verifizieren Sie, dass die Authentifizierung im erwarteten Konfigurationspfad gespeichert ist und dass der App-Prozess dasselbe `$HOME` sieht.
### OpenCode-Anbieterschlüssel abgelehnt
- Überprüfen Sie noch einmal, ob der Anbietername in `config.json` mit dem Anbieter-Präfix in der Modellzeichenfolge übereinstimmt
- Stellen Sie sicher, dass der Schlüssel nicht abgelaufen oder im Anbieter-Dashboard widerrufen ist
### Authentifizierungs-Diagnoselog
Jeder Aufruf von `CliInstallerService.getStatus()` hängt eine Zeile an `claude-cli-auth-diag.ndjson` im Electron-Log-Ordner an (auf macOS üblicherweise `~/Library/Logs/<product-name>/`). Wenn die Datei **512 KiB** überschreitet, wird sie vor dem nächsten Schreibvorgang auf leer gekürzt.
Prüfen Sie diese Datei, wenn Sie in der gepackten App „Not logged in" oder Authentifizierungsfehler sehen.
## Lane-Bootstrap hängt
Für sekundäre OpenCode-Lanes:
- Eine fehlende `inboxes/<member>.json` ist nicht automatisch ein Fehler. OpenCode-Lanes müssen nicht zuerst per Primär-Inbox erstellt werden, bevor sie starten.
- Wenn die UI anzeigt, dass das Team noch startet, während primäre Mitglieder bereits nutzbar sind, wartet „all teammates joined" auf die sekundären Lanes.
- Wenn `Prepared communication channels for X/Y members` hängt, prüfen Sie, ob `Y` fälschlicherweise sekundäre OpenCode-Mitglieder einschließt.
### Leere Einträge im Lane-Manifest
Wenn die Bridge meldet, dass der Bootstrap erfolgreich war, aber `manifest.json` `entries: []` anzeigt, liegt das Problem beim **Commit der Beweise**, nicht am Modellverhalten. Das Mitglied darf erst als zustellbar gelten, wenn `opencode-sessions.json` und sein Manifest-Eintrag existieren.
## Häufige Mitgliedszustände
| Zustand | Bedeutung |
| --- | --- |
| `confirmed_alive` + `bootstrapConfirmed` | Gesund und bereit |
| `registered` / `runtime_pending_bootstrap` | Prozess oder Lane existiert, aber der Bootstrap-Beweis wurde noch nicht committet |
| `failed_to_start` + `runtime_process` | Prozess existiert, aber das Start-Gate ist fehlgeschlagen. Diagnose prüfen |
| `failed_to_start` + `stale_metadata` | Gespeicherte pid/Sitzung ist veraltet oder tot |
::: warning
`member_briefing` allein ist KEIN Runtime-Beweis. Bei OpenCode ist der maßgebliche Beweis committeter Runtime-Beweis wie `opencode-sessions.json` und der Manifest-Eintrag.
:::
## Runtime-Debug-Modus
Für lokales Debugging können Sie Teammitglieder dazu zwingen, in tmux-Panes zu laufen:
```bash
# Launch from a terminal
CLAUDE_TEAM_TEAMMATE_MODE=tmux pnpm dev
# Or add to custom CLI args
--teammate-mode tmux
```
Verwenden Sie dies, um interaktives CLI-Verhalten zu untersuchen. Betrachten Sie dies nicht als vollständig gleichwertig mit dem Prozess-Backend.
## Rauchtests
Verwenden Sie die Desktop-Electron-App für die normale Validierung. Der Browser-/Web-Dev-Modus enthält nicht die vollständige Desktop-Runtime, IPC, Anbieter-Authentifizierung, das Terminal oder das Verhalten des Team-Lebenszyklus.
### Nur Dokumentationsänderungen
Vom Repository-Wurzelverzeichnis aus:
```bash
pnpm --dir landing docs:build
git diff --check -- landing/product-docs
```
### Änderungen am Team-Lebenszyklus
Beginnen Sie eng begrenzt und erweitern Sie dann:
```bash
pnpm test -- test/main/services/team/TeamProvisioningService.test.ts
pnpm test -- test/main/services/team/TeamAgentLaunchMatrix.safe-e2e.test.ts
pnpm typecheck
git diff --check
```
### Live-Team-Rauchtest
Verwenden Sie ein kleines Team und ein Git-verfolgtes Wegwerfprojekt:
1. Starten Sie die Desktop-App mit `pnpm dev`.
2. Erstellen Sie einen Lead plus einen Builder.
3. Bitten Sie um eine winzige Änderung mit einem expliziten Verifizierungsbefehl.
4. Bestätigen Sie, dass die Aufgabe von `pending` -> `in_progress` -> `completed` wandert.
5. Öffnen Sie Aufgabenprotokolle und verifizieren Sie, dass Tool-Zeilen, Aufgabenkommentare und Dateiänderungen übereinstimmen.
6. Stoppen Sie beim Aufräumen nur das zum Rauchtest gehörende Team / die zugehörigen Prozesse.
::: warning Nur eng begrenztes Aufräumen
Beenden Sie beim Aufräumen eines Rauchtests nicht alle OpenCode-Hosts, nicht zusammenhängende tmux-Panes oder Benutzer-Teams.
:::
## Sicheres Aufräumen
Beim Aufräumen veralteter Prozesse:
1. Identifizieren Sie die pid und bestätigen Sie, dass sie zum aktuellen Team / zur aktuellen Lane gehört.
2. Stoppen Sie nur Prozesse, die explizit zu einem Rauchtest oder zu dem Start gehören, den Sie debuggen.
3. **Beenden Sie nicht** alle OpenCode- oder gemeinsam genutzten Host-Prozesse als Abkürzung.
## Wann Beweise zu sammeln sind
Bevor Sie um Hilfe bitten, sammeln Sie:
- Aufgaben-ID (kurz oder vollständig)
- Teamname
- Runtime-Pfad (`claude`, `codex` oder `opencode`)
- Auszug aus dem Start-Log (aus `latest.json` oder `bootstrap-journal.jsonl`)
- Anbieter-/Modellzeichenfolge
- Genaues Zeitfenster, in dem das Problem aufgetreten ist
Diese Daten reichen üblicherweise aus, um Probleme im Start- und Aufgabenlebenszyklus zu debuggen.
::: tip
Wenn das Problem weiterhin besteht, öffnen Sie die persistierten Dateien des Teams unter `~/.claude/teams/<teamName>/` und korrelieren Sie UI-Diagnosen mit dem Live-Prozesszustand, bevor Sie Code ändern.
:::

81
landing/product-docs/de/index.md Normal file
View file

@ -0,0 +1,81 @@
---
title: Agent Teams Dokumentation – KI-Agententeams aus einer lokalen Desktop-App ausführen
description: Dokumentation für Agent Teams, eine kostenlose Desktop-App zur Orchestrierung von KI-Agenten. Erstellen Sie Teams, verfolgen Sie die Arbeit auf einem Kanban-Board, überprüfen Sie Codeänderungen und koordinieren Sie Claude-, Codex-, OpenCode- und Multimodell-Workflows.
lang: de-DE
layout: home
hero:
name: Agent Teams Dokumentation
text: KI-Agententeams aus einer lokalen Desktop-App ausführen
tagline: Erstellen Sie Teams, verfolgen Sie, wie sich die Arbeit über ein Kanban-Board bewegt, überprüfen Sie Codeänderungen und koordinieren Sie Claude-, Codex-, OpenCode- und Multimodell-Workflows, ohne die lokale Kontrolle aufzugeben.
actions:
- theme: brand
text: Schnellstart
link: /de/guide/quickstart
- theme: alt
text: Installieren
link: /de/guide/installation
- theme: alt
text: Konzepte
link: /de/reference/concepts
features:
- icon: "01"
title: Team-orientierter Workflow
details: Definieren Sie Rollen, starten Sie einen Lead und lassen Sie Agenten Aufgaben aufteilen, übernehmen und koordinieren.
link: /de/guide/create-team
linkText: Team erstellen
- icon: "02"
title: Live-Kanban-Board
details: Verfolgen Sie, wie Aufgaben durch todo, in progress, review, done und approved wandern, während die Agenten arbeiten.
link: /de/guide/agent-workflow
linkText: Workflow verstehen
- icon: "03"
title: Integriertes Code-Review
details: Untersuchen Sie aufgabenbezogene Diffs, akzeptieren oder verwerfen Sie Hunks und kommentieren Sie dort, wo Agenten eine Richtung brauchen.
link: /de/guide/code-review
linkText: Änderungen überprüfen
- icon: "04"
title: Runtime-bewusste Einrichtung
details: Nutzen Sie Claude, Codex, OpenCode oder Multimodell-Anbieter über den Zugang, den Sie bereits haben.
link: /de/guide/runtime-setup
linkText: Runtimes konfigurieren
- icon: "05"
title: Local-first-Kontrolle
details: Die Desktop-App liest den lokalen Projekt- und Runtime-Zustand. Ihr Code bleibt auf Ihrem Rechner, sofern nicht ein ausgewählter Anbieter Prompt-Kontext erhält.
link: /de/reference/privacy-local-data
linkText: Datenschutzmodell
- icon: "06"
title: Debugbare Teams
details: Verfolgen Sie Aufgabenprotokolle, Runtime-Ausgaben, Teamkollegen-Nachrichten und laufende Prozesse, wenn ein Start oder eine Aufgabe hängen bleibt.
link: /de/guide/troubleshooting
linkText: Fehler beheben
---
<InstallBlock label="Kopieren" copied-label="Kopiert" />
## Hier starten
Agent Teams ist eine kostenlose Desktop-App zur Orchestrierung von KI-Agententeams. Sie senden nicht nur isolierte Prompts an einen einzelnen Agenten: Sie erstellen ein Team, weisen Rollen zu und verfolgen, wie Agenten ihre Arbeit über ein Aufgaben-Board koordinieren.
<DocsCardGrid />
## Nächste Schritte nach dem Start
Nachdem Sie Ihr erstes Team erstellt haben, erkunden Sie diese Anleitungen, um weiterzukommen:
- **Runtime-Einrichtung** - konfigurieren Sie Claude-, Codex-, OpenCode- oder Multimodell-Anbieter: [Runtimes konfigurieren](/de/guide/runtime-setup)
- **Agent-Workflow** - verstehen Sie, wie Agenten ihre Arbeit über das Aufgaben-Board koordinieren: [Workflow verstehen](/de/guide/agent-workflow)
- **Team-Briefing-Beispiele** - lernen Sie Prompt-Muster anhand realer Briefings: [Beispiele ansehen](/de/guide/team-brief-examples)
- **Code-Review** - untersuchen Sie Diffs, akzeptieren oder verwerfen Sie Änderungen: [Änderungen überprüfen](/de/guide/code-review)
- **Fehlerbehebung** - diagnostizieren Sie hängende Starts, fehlende Teamkollegen und fehlgeschlagene Aufgaben: [Fehler beheben](/de/guide/troubleshooting)
- **Git- und Worktree-Strategie** - nutzen Sie Worktree-Isolation, wenn mehrere Teamkollegen parallel dasselbe Repository bearbeiten: [Mehr über Worktrees erfahren](/de/guide/git-worktree-strategy)
- **Versionshinweise** - sehen Sie, was in jeder Version neu ist: [Releases ansehen](/de/reference/release-notes)
## Referenz
Nutzen Sie die Referenzseiten, wenn Sie exakte Terminologie, das Anbieterverhalten, die Architektur für Mitwirkende oder Datenschutzgrenzen benötigen.
<DocsCardGrid type="reference" />
## Produktvorschau
<ZoomImage src="/screenshots/1.jpg" alt="Agent Teams Kanban-Board" caption="Aufgabenstatus, Teamkollegen-Aktivität und Review-Workflow bleiben in einem Arbeitsbereich sichtbar." />

85
landing/product-docs/de/reference/concepts.md Normal file
View file

@ -0,0 +1,85 @@
---
title: Konzepte – Agent Teams Dokumentation
description: Grundlegendes Vokabular für Agent Teams — Teams, Leads, Teammitglieder, Aufgaben, Kanban, Posteingänge, Runtimes und Review.
lang: de-DE
---
# Konzepte
Diese Seite definiert die grundlegenden Begriffe, die in Agent Teams verwendet werden. Nutzen Sie sie als gemeinsames Vokabular für die App, das Aufgabenboard, Nachrichten und den Review-Ablauf.
## Team
Ein Team ist eine benannte Gruppe von Agenten, die an einen Projektpfad gebunden ist. Es hat einen Lead, optionale Teammitglieder, Runtime-/Anbietereinstellungen, Prompts, Posteingänge, Aufgaben und einen lokalen Startzustand.
## Lead {#lead}
Der Lead ist der Koordinator des Teams. Er verwandelt ein Benutzerziel in Aufgaben, weist Teammitglieder zu oder leitet sie um, verfolgt Blocker, fordert Reviews an und hält die Arbeit über das Board am Laufen.
[Teammitglied →](#teammate)
Lead-Nachrichten verwenden einen anderen Zustellungspfad als Nachrichten von Teammitgliedern: Die App leitet Lead-Posteingangseinträge in die Lead-Runtime weiter, während Teammitglieder zwischen den Zügen ihre eigenen Posteingangsdateien lesen.
## Teammitglied {#teammate}
Ein Teammitglied ist ein Agent im Team, der nicht der Lead ist. Teammitglieder übernehmen üblicherweise fokussierte Rollen wie Builder, Reviewer, Researcher oder Tester. Ein Teammitglied kann Direktnachrichten, Aufgabenzuweisungen, Aufgabenkommentare und Review-Anfragen empfangen.
[Lead ↑](#lead)
## Aufgabe
Eine Aufgabe ist die dauerhafte Arbeitseinheit. Sie hat eine ID, einen Status, einen Eigentümer, eine Beschreibung, Kommentare, Logs, Anhänge, Aufgabenverweise und überprüfbare Änderungen.
Übliche Aufgabenzustände sind `todo`, `in_progress`, `done`, `review` und `approved`. Intern speichert die Aufgabendatei den Arbeitszustand, während die Review- und Freigabeplatzierung auch den Kanban-Overlay-Zustand verwenden kann.
## Kanban
Kanban ist die Boardansicht für die Teamarbeit. Damit können Sie Aufgaben nach Zustand durchsuchen, Aufgabendetails öffnen, Logs inspizieren, Diffs überprüfen, fertige Arbeit freigeben oder Änderungen anfordern.
## Posteingang
Ein Posteingang ist eine lokale Nachrichtendatei für einen Teamteilnehmer. Agent Teams nutzt Posteingänge für Benutzernachrichten, Lead-Nachrichten, Nachrichten von Teammitgliedern, Runtime-Zustellungsmetadaten, teamübergreifende Nachrichten und einige Systembenachrichtigungen.
Nachrichten sind dauerhafte lokale Datensätze. Die Zustellung hängt dennoch davon ab, dass die ausgewählte Runtime aktiv ist und ihren nächsten Zug verarbeiten kann.
## Agent-Block
Ein Agent-Block ist verborgener, nur für Agenten bestimmter Anweisungstext, der mit `<info_for_agent>...</info_for_agent>` umschlossen ist. Die Benutzeroberfläche entfernt diese Blöcke aus der normalen, für Menschen sichtbaren Darstellung, aber Agenten und die Runtime-Zustellung können sie für Koordinationsdetails verwenden.
Der aktuelle kanonische Marker ist `info_for_agent`. Ältere Dokumente verwenden möglicherweise umschlossene Codeblöcke mit einem `info_for_agent`-Marker oder XML-artige `<agent_block>`-Tags — dies sind veraltete Muster und sollten beim Auftreten zu `info_for_agent` migriert werden. (Der ursprüngliche Tag-Name war `agent-block`; die Unterstrich-Form `<agent_block>` wird im VitePress-Quellcode verwendet, um das HTML-Parsing zu vermeiden.)
## Kontextphase
Eine Kontextphase ist ein Segment einer Sitzungs-Kontextzeitleiste. Die Verdichtung (Compaction) startet eine neue Phase, sodass die Token- und Kontextnutzung vor und nach dem Zurücksetzen analysiert werden kann.
Die Kontextverfolgung trennt Kategorien wie Projektanweisungen, erwähnte Dateien, Tool-Ausgabe, Denktext, Teamkoordination und Benutzernachrichten. Diese Zahlen sind Diagnosewerte, keine Abrechnungsbelege der Anbieter.
## Runtime
Eine Runtime ist der lokale Ausführungspfad, der einen Agentenzug ausführt. Zu den unterstützten Runtime-Pfaden gehören Claude Code, Codex und OpenCode.
Die Runtime besitzt das Verhalten der Modellausführung, Authentifizierungsdetails, die Semantik der Tool-Ausführung, Ratenbegrenzungen, die Modellverfügbarkeit und einige Transkript-/Log-Formate.
## Anbieter
Ein Anbieter ist der Modellzugriffspfad hinter einer Runtime. Aktuelle Anbieter-IDs umfassen Anthropic, Codex, Gemini und OpenCode. OpenCode kann über seine eigene Konfiguration an viele Modellanbieter weiterleiten.
Agent Teams orchestriert Aufgaben und Nachrichten, ersetzt aber nicht die Anbieter-Authentifizierung oder die Anbieterrichtlinien.
## Solo-Modus
Der Solo-Modus betreibt ein Team mit einem einzigen Mitglied. Er ist nützlich für schnelle Arbeit, geringeren Koordinationsaufwand und das Validieren eines Prompts, bevor zu einem vollständigen Team erweitert wird.
## Teamübergreifende Kommunikation
Agenten können innerhalb von Teams und teamübergreifend Nachrichten senden. Nutzen Sie dies, wenn separate Teams zusammenhängende Arbeit besitzen und sich koordinieren müssen, ohne alles in einem großen Team zusammenzufassen.
## Autonomiestufe
Die Autonomie steuert, wie viel Agenten tun dürfen, bevor sie nachfragen. Höhere Autonomie ist schneller; geringere Autonomie ist sicherer für sensible Codepfade, Persistenz, Anbieter-Authentifizierung, Git-Operationen und Releases.
## Review
Review ist der aufgabenbezogene Abnahmeablauf. Eine Aufgabe kann zu review wechseln, Kommentare oder angeforderte Änderungen erhalten und dann zu approved wechseln, wenn das Ergebnis akzeptiert wird.
Review ist an lokale Diffs und die Aufgabenhistorie gebunden und funktioniert daher am besten, wenn Aufgaben eng gefasst bleiben und Agenten die Aufgabe erwähnen, an der sie arbeiten.

55
landing/product-docs/de/reference/contributor-architecture.md Normal file
View file

@ -0,0 +1,55 @@
---
title: Architektur für Mitwirkende – Agent Teams Dokumentation
description: Leitfaden für Mitwirkende zum Feature-Aufbau, den Grenzen zwischen Runtime und Anbieter, harten Guardrails und den kanonischen Architekturdokumenten.
lang: de-DE
---
# Architektur für Mitwirkende
Diese Seite ist eine Landkarte für Mitwirkende. Sie verweist auf die kanonische Repo-Anleitung, anstatt jede Implementierungsregel erneut darzustellen.
## Kanonische Quellen
Verwenden Sie diese Dateien als Quelle der Wahrheit, wenn Sie die App ändern:
| Bedarf | Kanonische Quelle |
| --- | --- |
| Repo-Übersicht und Befehle | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) |
| Lokale Arbeitskonventionen | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) |
| Harte Guardrails | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) |
| Aufbau mittelgroßer und großer Features | [docs/FEATURE_ARCHITECTURE_STANDARD.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) |
| Debugging von Agent-Team-Starts | [docs/team-management/debugging-agent-teams.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) |
## Feature-Aufbau
Mittelgroße und große Features sollten unter `src/features/<feature-name>/` liegen und dem Feature-Architekturstandard folgen. Halten Sie die Interna eines Features hinter öffentlichen Einstiegspunkten und vermeiden Sie tiefe Importe über Feature-Grenzen hinweg.
Beginnen Sie bei neuer Arbeit mit dem vorhandenen Slice `src/features/recent-projects` als lokaler Referenzimplementierung. Kleine Fixes können nahe am bestehenden Codepfad bleiben, wenn das Erstellen eines Feature-Slice mehr Struktur als Nutzen brächte.
## Grenzen zwischen Runtime und Anbieter
Agent Teams ist für die Orchestrierung zuständig: Teams, Aufgaben, Nachrichten, Startzustand, Review-UI, Diagnostik und lokale Persistenz.
Der ausgewählte Runtime-/Anbieterpfad ist für Modellausführung, Authentifizierung, Modellverfügbarkeit, Ratenbegrenzungen, Tool-Semantik und runtime-spezifische Transkript-Nachweise zuständig. Lassen Sie Prompts oder UI-Zustand nicht für fehlende Authentifizierung, fehlende Binärdateien, abgelehnte Modell-IDs oder Anbieterausfälle kompensieren. Details zur nutzerseitigen Einrichtung finden Sie unter [Anbieter und Runtimes](/de/reference/providers-runtimes).
## Debugging von Agent-Teams
Beginnen Sie bei hängenden Starts, OpenCode-Zuständen `registered` / Bootstrap-unbestätigt, ausbleibenden Antworten von Teammitgliedern oder verdächtigen Aufgabenprotokollen mit dem dedizierten Debugging-Runbook. Untersuchen Sie das neueste Start-Fehler-Artefakt unter `~/.claude/teams/<team>/launch-failure-artifacts/latest.json` und korrelieren Sie anschließend den UI-Zustand mit den persistierten Dateien und runtime-spezifischen Nachweisen.
Vermeiden Sie umfangreiche Aufräumarbeiten während des Debuggings. Stoppen Sie nur den Prozess, die Lane, das Team oder den Smoke-Run, den Sie dem Problem zuordnen können.
## Konventionen für Mitwirkende
- Verwenden Sie `pnpm dev` für die Desktop-Electron-App während der normalen Entwicklung.
- Verwenden Sie den Browser-Dev-Modus nicht als Ersatz für Desktop-Runtime, IPC, Terminal, Anbieter-Authentifizierung oder das Verhalten des Team-Lebenszyklus.
- Halten Sie die Verantwortlichkeiten von Electron-Main, Preload, Renderer, Shared und Feature getrennt.
- Verwenden Sie `wrapAgentBlock(text)` für reine Agent-Blöcke, anstatt Marker manuell zu verketten.
- Bevorzugen Sie eine fokussierte Verifizierung. Vermeiden Sie umfangreiche `lint:fix`- oder Formatierungsänderungen, sofern die Aufgabe nicht ausdrücklich die Formatierung betrifft.
- Behandeln Sie Parsing, Aufgaben-Lebenszyklus, Anbieter-/Runtime-Erkennung, Persistenz, IPC, Git und Review-Abläufe als Hochrisikobereiche, die gezielte Tests oder einen klaren Verifizierungspfad benötigen.
## Verwandte Seiten
- [Runtime-Einrichtung](/de/guide/runtime-setup)
- [Fehlerbehebung](/de/guide/troubleshooting)
- [Code-Review](/de/guide/code-review)
- [Datenschutz und lokale Daten](/de/reference/privacy-local-data)

95
landing/product-docs/de/reference/faq.md Normal file
View file

@ -0,0 +1,95 @@
---
title: FAQ – Agent Teams Dokumentation
description: Häufig gestellte Fragen zu Agent Teams — Preise, Modellzugriff, Runtimes, Datenschutz, Review und Fehlerbehebung.
lang: de-DE
---
# FAQ
## Ist Agent Teams kostenlos?
Ja. Die App ist kostenlos und quelloffen. Der Zugriff auf Anbieter oder Runtimes kann je nach Nutzung dennoch Kosten verursachen.
## Beinhaltet Agent Teams einen Modellzugriff?
Nein. Agent Teams ist die lokale Orchestrierungs- und UI-Schicht. Der Modellzugriff stammt aus dem ausgewählten Runtime-/Anbieterpfad, etwa Claude Code, Codex oder OpenCode.
## Welche Runtimes werden unterstützt?
Die unterstützten Runtime-Pfade sind Claude Code, Codex und OpenCode. Die App erfasst außerdem Anbieter-IDs wie Anthropic, Codex, Gemini und OpenCode, sofern die Runtime sie bereitstellt.
## Muss ich zuerst Claude Code oder Codex installieren?
Nicht immer. Die App leitet die Runtime-Erkennung und -Einrichtung über die UI an. Einige Pfade erfordern dennoch eine externe Runtime-Authentifizierung.
Die Einrichtung von OpenCode ist getrennt von der Einrichtung von Claude Code und Codex. Wenn ein Start fehlschlägt, prüfen Sie den Runtime-Status und die Anbieter-Authentifizierung, bevor Sie den Team-Prompt ändern.
## Wie prüfe ich, ob eine Runtime bereit ist?
Führen Sie den Runtime-Befehl zuerst in einem Terminal aus:
```bash
claude --version
codex --version
opencode --version
```
Bestätigen Sie anschließend die Anbieter-Authentifizierung für den ausgewählten Pfad. Wenn der Befehl oder die Authentifizierungsprüfung außerhalb von Agent Teams fehlschlägt, beheben Sie die Einrichtung, bevor Sie ein Team starten.
## Lädt es meinen Code auf die Server von Agent Teams hoch?
Nein. Agent Teams ist kein Cloud-Code-Sync-Dienst. Anbietergestützte Modellaufrufe können je nach ausgewählter Runtime Prompt-Kontext erhalten.
## Wo werden Team-Dateien gespeichert?
Team-Koordinationsdaten werden lokal unter `~/.claude/teams/<team>/` (macOS/Linux) oder `%APPDATA%\Claude\teams\<team>\` (Windows) gespeichert, Aufgabendateien unter `~/.claude/tasks/<team>/` oder `%APPDATA%\Claude\tasks\<team>\` und Projekt-Sitzungsdaten unter `~/.claude/projects/<encoded-project>/`, sofern verfügbar.
## Was kann meinen Rechner verlassen?
Prompt-Kontext, ausgewählte Dateiinhalte, Tool-Ergebnisse, Befehlsausgaben, Aufgabentexte, Kommentare und Anhänge können Ihren Rechner über den Runtime-/Anbieterpfad verlassen, wenn ein Agent ein anbietergestütztes Modell verwendet. Das genaue Verhalten hängt von der Runtime und dem Anbieter ab.
## Können Agenten miteinander kommunizieren?
Ja. Agenten können Teammitgliedern Nachrichten senden, Aufgaben kommentieren, sich teamübergreifend abstimmen und Aufgabenverweise nutzen, um Konversationen mit der Arbeit verknüpft zu halten.
## Was sollte ich in den ersten Team-Prompt schreiben?
Geben Sie dem Lead ein konkretes Ergebnis, Datei- oder Feature-Grenzen, Risikolimits und Erwartungen an die Verifizierung vor. Zum Beispiel:
```text
Improve the docs quickstart. Keep edits inside landing/product-docs, add practical examples, and run `pnpm --dir landing docs:build` before marking work done.
```
## Kann ich Code überprüfen, bevor ich ihn annehme?
Ja. Der Review-Ablauf ist auf aufgabenbezogene Diffs und Entscheidungen auf Hunk-Ebene ausgelegt.
## Was ist ein Agent Block?
Ein Agent Block ist verborgener, nur für Agenten bestimmter Text, der in Markern wie `<info_for_agent>...</info_for_agent>` eingeschlossen ist. Die App entfernt ihn aus der normalen, für Benutzer sichtbaren Anzeige, hält ihn aber für die Agentenkoordination verfügbar.
## Was ist der Solo-Modus?
Der Solo-Modus ist ein Team mit einem einzigen Agenten. Er eignet sich für kleinere Aufgaben und einen geringeren Koordinationsaufwand.
## Sollte ich Worktree-Isolation verwenden?
Verwenden Sie sie, wenn mehrere OpenCode-Teammitglieder dasselbe Git-Projekt parallel bearbeiten könnten. Sie reduziert Dateikonflikte, erfordert jedoch ein Git-verwaltetes Projekt und gilt derzeit für OpenCode-Mitglieder.
## Können verschiedene Teammitglieder verschiedene Anbieter verwenden?
Ja, Anbieter-/Modelleinstellungen können pro Teammitglied übernommen werden, wenn der ausgewählte Runtime-Pfad sie unterstützt. OpenCode ist der wichtigste Pfad für ein breites Multi-Anbieter-Routing.
## Warum wird eine Aufgabe getrennt von done als review oder approved angezeigt?
Der Arbeitsstatus und der Review-Status sind verwandt, aber nicht identisch. Eine Aufgabe kann aus Sicht des Agenten done sein und anschließend in der Kanban-UI den Review- und Genehmigungsprozess durchlaufen.
## Was sollte ich tun, wenn ein Start hängen bleibt?
Öffnen Sie die Fehlerbehebung, sammeln Sie Start-Diagnosen, prüfen Sie `~/.claude/teams/<team>/` und verifizieren Sie die Runtime-/Anbieter-Authentifizierung, bevor Sie Prompts ändern.
Prüfen Sie bei OpenCode die Lane-/Session-Evidenz, bevor Sie annehmen, dass ein Teammitglied online ist, aber Nachrichten ignoriert.
## Warum unterscheiden sich Logs zwischen den Runtimes?
Claude Code, Codex und OpenCode stellen unterschiedliche Transkriptformate und Runtime-Evidenz bereit. Agent Teams normalisiert, was es kann, aber die Vollständigkeit und Zuordnung der Logs kann je nach Runtime variieren.

82
landing/product-docs/de/reference/privacy-local-data.md Normal file
View file

@ -0,0 +1,82 @@
---
title: Datenschutz und lokale Daten – Agent Teams Dokumentation
description: Was Agent Teams lokal speichert, was über anbieterbasierte Modellaufrufe Ihr Gerät verlassen kann und praktische Datenschutzhinweise.
lang: de-DE
---
# Datenschutz und lokale Daten
Agent Teams ist local-first, aber der gewählte Runtime-/Anbieterpfad spielt dennoch eine Rolle. Diese Seite beschreibt, was die Desktop-App lokal speichert und was Ihr Gerät verlassen kann, wenn Agenten anbieterbasierte Modelle aufrufen.
## Was lokal bleibt
Die Desktop-App läuft auf Ihrem Gerät und liest lokale Projekt-/Runtime-Daten, um die Benutzeroberfläche zu betreiben. Typische lokale Daten umfassen:
- Projektdateien
- Teamkonfiguration und Mitglieder-Metadaten
- Aufgaben-Metadaten, Aufgabenkommentare und Aufgabenreferenzen
- Posteingangsnachrichten
- Runtime-/Sitzungsprotokolle
- Startzustand und Bootstrap-Diagnosen
- Review-Status
- Lokale App-Einstellungen
Wichtige lokale Speicherorte umfassen:
| Plattform | Speicherort | Zweck |
| --- | --- | --- |
| macOS/Linux | `~/.claude/teams/<team>/` | Teamkonfiguration, Mitglieder-Metadaten, Posteingänge, Startzustand, Bootstrap-Nachweise, Runtime-Diagnosen, Aufzeichnungen gesendeter Nachrichten, Kanban-Status und review-bezogene Teamdateien. |
| Windows | `%APPDATA%\Claude\teams\<team>\` | Dasselbe — Teamkonfiguration, Mitglieder-Metadaten, Posteingänge, Startzustand und Diagnosen. |
| macOS/Linux | `~/.claude/tasks/<team>/` | Dauerhafte Aufgaben-JSON-Dateien für das Team-Board. |
| Windows | `%APPDATA%\Claude\tasks\<team>\` | Dasselbe — dauerhafte Aufgaben-JSON-Dateien. |
| macOS/Linux | `~/.claude/projects/<encoded-project>/` | Claude-/Codex-artige Projektsitzungsdateien, die für Sitzungsverlauf, Kontextanalyse und transkriptgestützte Benutzeroberfläche verwendet werden. |
| Windows | `%APPDATA%\Claude\projects\<encoded-project>\` | Dasselbe — Projektsitzungsdateien. |
Die genauen Dateien können je nach Runtime und App-Version variieren. Beim Debugging von Starts befinden sich die neuesten Nachweise üblicherweise im jeweiligen Ordner `~/.claude/teams/<team>/` (oder `%APPDATA%\Claude\teams\<team>\`).
## Was Ihr Gerät verlassen kann
Agent Teams selbst ist kein Cloud-Code-Sync-Dienst für Ihr Repository. Die App muss Ihr gesamtes Projekt nicht auf einen Agent-Teams-Server hochladen, um das Board, den Posteingang, Protokolle oder die Review-Benutzeroberfläche anzuzeigen.
Wenn ein Agent jedoch ein anbieterbasiertes Modell mit einer Aufgabe betraut, können Prompt-Kontext, ausgewählte Dateiinhalte, Aufgabentext, Kommentare, Tool-Ergebnisse, Befehlsausgaben und anderer von der Runtime bereitgestellter Kontext über den gewählten Runtime-/Anbieterpfad gesendet werden. Was gesendet wird, hängt von der Runtime, dem Modell, den Tool-Aufrufen, dem Prompt und der Anbieterkonfiguration ab.
Anbieter-Authentifizierung, anbieterseitige Aufbewahrung, Training, Protokollierung, regionale Verarbeitung und Abrechnung werden durch den Anbieter/die Runtime geregelt, den/die Sie wählen. Überprüfen Sie diese Richtlinien für sensible Projekte.
Häufige Beispiele:
| Aktion | Daten, die über die Runtime/den Anbieter gesendet werden können |
| --- | --- |
| Einen Agenten bitten, eine Datei zu bearbeiten | Der Aufgaben-Prompt, relevante Dateiinhalte, Tool-Ergebnisse und Befehlsausgaben |
| Einen Screenshot anhängen | Der Inhalt des Anhangs und der umgebende Aufgaben-/Kommentartext |
| Um ein Code-Review bitten | Diff-Kontext, ausgewählte Dateien, Kommentare und Verifizierungsprotokolle |
| Einen fehlschlagenden Befehl debuggen | Fehlerausgaben, Stack-Traces und referenzierte Quellcode-Ausschnitte |
## Was die App nicht garantiert
- Sie kann nicht garantieren, dass anbieterbasierte Modellaufrufe niemals privaten Code erhalten.
- Sie kann Aufbewahrungs- oder Abrechnungsrichtlinien der Anbieter nicht außer Kraft setzen.
- Sie kann einen entfernten Anbieter nicht dazu bringen, sich wie ein vollständig lokales Modell zu verhalten.
- Sie kann keine Geheimnisse schützen, die ein Agent angewiesen wird, in Prompts, Aufgabenkommentare, Dateien oder Befehle einzufügen.
- Sie kann nicht dafür sorgen, dass jede Runtime dieselben Transkript- oder Audit-Details offenlegt.
## Praktische Hinweise
- Hängen Sie keine Geheimnisse an Aufgaben, Kommentare oder Direktnachrichten an.
- Überprüfen Sie die Anbieterrichtlinien für sensible Projekte.
- Verwenden Sie eine geringere Autonomie für riskante Repositorys.
- Halten Sie den Aufgabenumfang eng, wenn Sie mit privatem Code arbeiten.
- Bevorzugen Sie lokale Nachweise und Protokolle beim Debugging.
- Prüfen Sie generierte Prompts, Aufgabenbeschreibungen und angehängte Dateien, bevor Sie Agenten mit vertraulichem Material betrauen.
- Verwenden Sie Anbieter-/Modellpfade, die Ihren Datenschutzanforderungen entsprechen.
Bevor Sie Agent Teams auf einem sensiblen Repository verwenden:
1. Entfernen Sie Geheimnisse aus dem Arbeitsverzeichnis und den Aufgabenanhängen
2. Wählen Sie den Runtime-/Anbieterpfad, den Sie verwenden dürfen
3. Beginnen Sie mit geringer Autonomie und kleinen Aufgaben
4. Überprüfen Sie Aufgaben-Prompts und generierte Kommentare, bevor Sie den Umfang erweitern
5. Halten Sie Protokolle lokal, sofern Sie sie nicht absichtlich für den Support teilen
## Open-Source-Modell
Die App selbst ist quelloffen und kostenlos. Sie können im Repository nachvollziehen, wie lokale Orchestrierung, Aufgabenverfolgung, Posteingänge, Runtime-Diagnosen und Review-Abläufe funktionieren.

115
landing/product-docs/de/reference/providers-runtimes.md Normal file
View file

@ -0,0 +1,115 @@
---
title: Anbieter und Runtimes – Agent Teams Dokumentation
description: Unterstützte Runtime-Pfade (Claude Code, Codex, OpenCode), Anbieter-IDs, Modellbenennung, Multi-Anbieter-Strategien und Funktionsprüfungen.
lang: de-DE
---
# Anbieter und Runtimes
Agent Teams trennt die Orchestrierung vom Modellzugriff. Die App verwaltet Teams, Aufgaben, Nachrichten, den Startzustand und die Review-UI; der ausgewählte Runtime-/Anbieter-Pfad führt die eigentliche Modellarbeit aus.
## Was die App bereitstellt
Agent Teams stellt bereit:
- Team- und Aufgabenorchestrierung
- Kanban-Board-UI
- Teammitglieder-Messaging
- Aufgabenprotokolle
- Review-UI
- lokale Projektintegration
- Runtime-Erkennung und Funktionsprüfungen
- lokale Protokolle und Diagnosen
## Was die Runtime bereitstellt
Die Runtime stellt bereit:
- Modellausführung
- Anbieter-Authentifizierung
- Verhalten bei der Tool-Ausführung
- modellspezifische Rate-Limits und Funktionen
- runtime-spezifische Transkripte und Zustellungsnachweise
## Unterstützte Runtime-Pfade
| Runtime-Pfad | Anbieter-/Modell-Pfad | Beste Eignung | Hinweise |
| --- | --- | --- | --- |
| Claude Code | Anthropic / Claude-Modelle | Claude-Code-Nutzer und Anthropic-gestützte Workflows | Standardmäßiger Local-First-Pfad für Claude-Teams. Erfordert, dass die Runtime und der Kontozugriff lokal verfügbar sind. |
| Codex | Codex / OpenAI-gestützte Modelle | Codex-native Workflows | Nutzt die Codex-Runtime-Integration sowie den Codex-Auth-/Kontostatus, sofern verfügbar. Einige Diagnosen unterscheiden sich von Claude-Transkripten. |
| OpenCode | OpenCode-verwaltetes Modell-Routing | Multi-Anbieter-Teams und breite Modellabdeckung | OpenCode kann über viele Modellanbieter routen. Agent Teams behandelt OpenCode-Lanes als runtime-spezifischen Nachweis und vermeidet Rätselraten, wenn die Lane-Identität mehrdeutig ist. |
Gemini ist als unterstützter Anbieter-Pfad mit Google ADC (gcloud auth), Gemini CLI OAuth und API-Schlüssel-Authentifizierung verfügbar. Es erscheint zusammen mit anderen Anbietern in der UI für die Teamerstellung und Runtime-Einrichtung, wenn die Runtime es als verfügbar meldet.
## Anbieter-IDs
Die App erkennt derzeit diese Anbieter-IDs in der Team-/Runtime-Konfiguration:
| Anbieter-ID | Anzeigeabsicht |
| --- | --- |
| `anthropic` | Anthropic-/Claude-Code-Pfad |
| `codex` | Codex-Pfad |
| `gemini` | Gemini-Anbieter-Pfad (Google ADC, Gemini CLI oder API-Schlüssel) |
| `opencode` | OpenCode-Pfad, einschließlich OpenCode-verwaltetem Anbieter-Routing |
Lesen Sie diese Tabelle nicht als Garantie dafür, dass jeder Anbieter für jedes Modell auf jedem Rechner authentifiziert, installiert oder verfügbar ist. Der Runtime-Status und die Funktionsprüfungen sind die maßgebliche Quelle für einen bestimmten Start.
## Modell-IDs
Modell-IDs werden an die ausgewählte Runtime übergeben. Agent Teams schreibt den Modellkatalog eines Anbieters nicht in ein universelles Benennungsschema um.
Beispiele:
| Anbieter-Pfad | Beispiel-Modell-ID | Hinweise |
| --- | --- | --- |
| Claude Code | `opus`, `sonnet` oder eine vollständige Claude-Modell-ID | Verfügbarkeit hängt von Claude Code und dem Kontozugriff ab |
| Codex | `gpt-5.4`, `gpt-5.3-codex` | Verfügbarkeit ergibt sich aus dem Codex-Konto-/Runtime-Status |
| OpenCode | `openrouter/moonshotai/kimi-k2.6` | Das Präfix muss mit einer OpenCode-Anbieterkonfiguration übereinstimmen |
Wenn ein Modellname abgelehnt wird, überprüfen Sie ihn zuerst direkt in der Runtime/beim Anbieter. Das Ändern eines Team-Briefings kann ein nicht verfügbares Modell nicht starten.
## Multi-Anbieter-Strategie
Agent Teams hält die Orchestrierung anbieterbewusst, aber nicht anbietergebunden:
- Teams, Aufgaben, Posteingänge, Kommentare, Review-Zustand und Start-Diagnosen verbleiben im lokalen Agent-Teams-Speicher
- jedes Mitglied kann Anbieter-/Modelleinstellungen über die Team-Start-Metadaten mitführen
- Modellverfügbarkeit, Auth, Rate-Limits und Tool-Verhalten bleiben in der Verantwortung von Runtime/Anbieter
- OpenCode ist der breiteste Routing-Pfad, wenn ein Team mehrere Anbieter-/Modell-Lanes nutzen soll
Für die Grenzen aus Sicht von Mitwirkenden und kanonische Implementierungshinweise siehe [Architektur für Mitwirkende](/de/reference/contributor-architecture).
Empfohlene Muster:
| Muster | Wann es hilft | Risiko |
| --- | --- | --- |
| Ein Anbieter für alle Mitglieder | Erster Start, sensible Repos, einfachstes Debugging | Geteilte Rate-Limits können das gesamte Team stoppen |
| Starker Lead + günstigere Builder | Planung/Review zuverlässig halten und gleichzeitig die Implementierungskosten senken | Builder-Output benötigt möglicherweise eine strengere Überprüfung |
| Getrennte Builder- und Reviewer-Modelle | Modellspezifische blinde Flecken erkennen | Mehr Einrichtung und Attribution zu prüfen |
## Anbieterkosten
Agent Teams ist kostenlos und quelloffen. Sie können mit dem enthaltenen kostenlosen Modell ohne Auth starten - ohne Registrierung, API-Schlüssel oder Kreditkarte. Bezahlte oder kontogestützte Anbieternutzung unterliegt der von Ihnen ausgewählten Runtime/dem Anbieter: Abonnementlimits, API-Schlüssel, Konto-Auth, Rate-Limits und Anbieterrichtlinien bleiben allesamt außerhalb der App.
## Funktionsprüfungen
Während der Einrichtung kann die App Zugriffs- und Funktionsprüfungen durchführen. Dies hilft, fehlende Runtime-Auth zu erkennen, bevor ein Team-Start mitten in der Bereitstellung fehlschlägt.
Funktionsprüfungen können melden, dass ein Anbieter existiert, aber nicht authentifiziert ist, dass eine Modellliste nicht verfügbar ist, dass ein Runtime-Pfad fehlt oder dass eine bestimmte Erweiterungsfunktion nicht unterstützt wird. Behandeln Sie diese Ergebnisse als Einrichtungsdiagnosen, nicht als Aufgabenfehler.
Typische Einrichtungsbehebungen:
| Prüfergebnis | Was zu tun ist |
| --- | --- |
| Runtime fehlt | Installieren Sie die CLI oder korrigieren Sie `PATH` |
| Anbieter nicht authentifiziert | Führen Sie den Anbieter-Login-Flow aus oder fügen Sie den erforderlichen API-Schlüssel hinzu |
| Modell nicht verfügbar | Wählen Sie ein Modell, das in der Modellliste dieser Runtime sichtbar ist |
| Funktion nicht unterstützt | Verwenden Sie für dieses Teammitglied einen anderen Runtime-Pfad |
## Zu erwartende Einschränkungen
- Runtime-Unterstützung bedeutet keine gleiche Funktionsparität über Claude Code, Codex und OpenCode hinweg.
- Die Abdeckung von Protokollen und Transkripten unterscheidet sich je nach Runtime.
- OpenCode-Lanes benötigen stabile Lane-/Session-Nachweise, bevor die App Runtime-Protokolle sicher zuordnen kann.
- Anbieter-Modellnamen und -Verfügbarkeit können sich außerhalb der App ändern.
- Ein Team-Prompt kann fehlende Auth, fehlende PATH-Einträge, Anbieterausfälle oder erschöpfte Rate-Limits nicht beheben.

42
landing/product-docs/de/reference/release-notes.md Normal file
View file

@ -0,0 +1,42 @@
---
title: Versionshinweise – Agent Teams Dokumentation
description: Versionshinweise und Changelog für Agent Teams. Verweist auf die maßgeblichen Dateien RELEASE.md und CHANGELOG.md mit allen Details.
lang: de-DE
---
# Versionshinweise
Aktuelle Version: **v1.2.0** (2026-03-31). Die aktive Entwicklung läuft weiter auf dem `main`-Branch mit unveröffentlichten Änderungen für die Arbeitssynchronisierung von Mitgliedern, die Härtung der OpenCode-Auslieferung und die CI-Stabilisierung.
## So funktionieren Releases
Agent Teams folgt der [semantischen Versionierung](https://semver.org/). Tags, die in das Repository gepusht werden, lösen einen automatisierten [Release-Workflow](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) aus, der signierte Pakete für macOS, Windows und Linux erstellt und sie anschließend in GitHub Releases veröffentlicht.
## Aktuelle Releases
### v1.2.0 — Agent Graph, Tool-Freigabe pro Team, interaktives AskUserQuestion
Agent Graph mit kraftgesteuerter Visualisierung und Kanban-Aufgabenlayout, Steuerungen für die Tool-Freigabe pro Team mit lesbaren Berechtigungsabfragen, Benachrichtigungen zu Aufgabenkommentaren und interaktive AskUserQuestion-Schaltflächen. Überarbeitung des Berechtigungssystems mit Vorabfreigabe von Write/Edit/NotebookEdit und Integration des MCP-Tool-Katalogs. Siehe [vollständiges Changelog](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#120---2026-03-31).
### v1.1.0 — React 19 + Electron 40, vom Benutzer initiierte Aufgabenstarts
Migration auf React 19 + Electron 40, vom Benutzer initiierte Aufgabenstarts über das Kanban-Board, Leitfaden zur Behebung von Authentifizierungsproblemen, Syntaxhervorhebung für R/Ruby/PHP/SQL, 3-mal schnellere Transkriptsuche, Korrekturen für WSL-/Windows-Pfade und Behebung einer XSS-Sicherheitslücke. Siehe [vollständiges Changelog](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#110---2026-03-25).
### v1.0.0 — Erste öffentliche Veröffentlichung
Erster stabiler Build: Zuverlässigkeit von CLI/Authentifizierung in paketierten Apps, IPC-Härtung, plattformübergreifende Paketierung mit signierten macOS-Builds, Governance-Dokumente für Open Source (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY). Siehe [vollständiges Changelog](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#100---2026-03-23).
## Maßgebliche Quellen
| Dokument | Beschreibung |
| --- | --- |
| [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) | Release-Prozess, Leitfaden zur Versionierung, Benennung von Artefakten, Einrichtung automatischer Updates und Vorlage für Versionshinweise. |
| [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) | Vollständiges Changelog mit allen Versionen, Funktionen, Verbesserungen und Fehlerbehebungen aus Benutzersicht. |
| [GitHub Releases](https://github.com/777genius/agent-teams-ai/releases) | Herunterladbare Installationsprogramme für alle Plattformen. |
## Verwandte Seiten
- [Installation](/de/guide/installation)
- [Schnellstart](/de/guide/quickstart)
- [Architektur für Mitwirkende](/de/reference/contributor-architecture)
- [Entwickler](/de/developers/)

69
landing/product-docs/es/developers/index.md Normal file
View file

@ -0,0 +1,69 @@
---
title: Centro para desarrolladores – Documentación de Agent Teams
description: Punto de entrada para colaboradores y desarrolladores sobre la arquitectura, los guardrails, la depuración y las vías de extensión con MCP de Agent Teams.
lang: es-ES
---
# Centro para desarrolladores
Usa esta página cuando quieras modificar el propio Agent Teams, depurar el lanzamiento de un equipo o extender un runtime con herramientas de MCP. Los enlaces siguientes apuntan a los documentos canónicos del repositorio para que las reglas de implementación se mantengan en un único lugar.
## Empieza aquí
| Necesidad | Ir a |
| --- | --- |
| Visión general del repositorio, scripts y configuración del código fuente | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) |
| Navegación de agentes e índice de arquitectura | [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) |
| Convenciones de trabajo para agentes y colaboradores | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) |
| Guardrails de implementación estrictos | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) |
| Estructura de funciones medianas y grandes | [Estándar de arquitectura de funciones](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) |
| Depuración del lanzamiento, el bootstrap y la mensajería entre compañeros de equipo | [Runbook de depuración de equipos de agentes](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) |
| Proceso de contribución | [Guía de contribución](https://github.com/777genius/agent-teams-ai/blob/main/.github/CONTRIBUTING.md) |
| Notas de la versión / Changelog | [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) — [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) |
## Vía de desarrollo local
Ejecuta la aplicación de escritorio Electron para el desarrollo habitual:
```bash
pnpm install
pnpm dev
```
La vía de navegador/web no sustituye al runtime de escritorio. El modo de escritorio es la vía local admitida porque incluye IPC, terminales, autenticación de proveedores, gestión del ciclo de vida de los equipos, diagnósticos de lanzamiento y los puentes de runtime que usan los equipos reales.
## Puntos de control de la arquitectura
Antes de modificar una función, identifica su límite:
| Área | Ubicación esperada |
| --- | --- |
| Función de producto mediana o grande | `src/features/<feature-name>/` |
| Orquestación del proceso principal de Electron | `src/main/` |
| Superficie de API segura para el preload | `src/preload/` |
| UI del renderer y estado de la aplicación | `src/renderer/` |
| Tipos compartidos y helpers puros | `src/shared/` |
| Servidor MCP del tablero de Agent Teams | `mcp-server/` |
| Controlador de datos del tablero | `agent-teams-controller/` |
Usa `src/features/recent-projects` como slice de referencia para la organización de funciones. Mantén explícitos los contratos entre procesos y evita las importaciones profundas que cruzan los límites de las funciones.
## Vía de depuración
Para bloqueos en el lanzamiento, estados `registered` / bootstrap sin confirmar de OpenCode, respuestas faltantes de compañeros de equipo o logs de tareas sospechosos:
1. Empieza por el [runbook de depuración](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md).
2. Inspecciona el paquete de artefactos más reciente en `~/.claude/teams/<team>/launch-failure-artifacts/latest.json`.
3. Abre el `manifest.json` del artefacto y revisa `classification`, las migas de pan del bootstrap, los diagnósticos de lanzamiento, los estados de spawn de los miembros y las colas de logs censuradas.
4. Limpia únicamente el equipo, la ejecución, el panel o el proceso que puedas identificar como propiedad de la prueba de humo o del lanzamiento fallido.
## Vía de desarrollo con MCP
Agent Teams usa un servidor MCP integrado llamado `agent-teams` para las operaciones del tablero. Los servidores MCP de usuario y de proyecto pueden añadir capacidades externas para los runtimes. Consulta [Integración de MCP](/es/guide/mcp-integration) para ver ejemplos de configuración, la estructura de `.mcp.json` y orientación sobre el registro de herramientas.
## Documentos relacionados
- [Arquitectura para colaboradores](/es/reference/contributor-architecture)
- [Configuración del runtime](/es/guide/runtime-setup)
- [Integración de MCP](/es/guide/mcp-integration)
- [Solución de problemas](/es/guide/troubleshooting)

121
landing/product-docs/es/guide/agent-workflow.md Normal file
View file

@ -0,0 +1,121 @@
---
title: Flujo de trabajo de los agentes – Documentación de Agent Teams
description: Comprende el ciclo de vida de las tareas, el tablero kanban, los mensajes, los registros de tareas, el trabajo en paralelo, los procesos en vivo y la comunicación entre equipos.
lang: es-ES
---
# Flujo de trabajo de los agentes
Agent Teams hace que el trabajo de los agentes sea visible como estado de las tareas, mensajes, registros y cambios de código revisables.
## Modos
| Modo | Descripción |
| --- | --- |
| Solo | Un compañero de equipo con tareas autogestionadas |
| Equipo | Varios compañeros de equipo trabajando en paralelo y revisándose entre sí |
Ambos modos comparten las mismas superficies de kanban, registros de tareas y revisión de código.
## Ciclo de vida de las tareas
Agent Teams realiza el seguimiento de cada tarea a lo largo de dos dimensiones independientes: el estado del trabajo y el estado de la revisión.
| Dimensión | Estados | Descripción |
| --- | --- | --- |
| Estado del trabajo | `pending`, `in_progress`, `completed` | Indica si la tarea está esperando, si se está trabajando activamente en ella o si el propietario la ha terminado |
| Estado de la revisión | `none`, `review`, `needsFix`, `approved` | Indica en qué punto del flujo de revisión posterior a la finalización se encuentra la tarea |
El tablero kanban muestra la vista combinada, pero las dos dimensiones se mueven de forma independiente.
### Flujo del estado del trabajo
| Etapa | Qué ocurre | Propietario |
| --- | --- | --- |
| Pending | La tarea se crea y está lista, pero nadie ha empezado a trabajar todavía | Lead o usuario |
| In progress | Los agentes trabajan y actualizan el estado de la tarea mediante las herramientas MCP del tablero | Compañeros de equipo |
| Completed | El propietario publica un comentario con el resultado y marca la tarea como terminada | Compañero de equipo |
### Flujo del estado de la revisión
| Etapa | Qué ocurre | Propietario |
| --- | --- | --- |
| None | La tarea aún no está en revisión (puede estar pendiente, en progreso o recién completada) | — |
| Review | Se ha solicitado la revisión; un revisor inspecciona el diff y el resultado | Revisor |
| Needs fix | Se solicitaron cambios durante la revisión; el propietario debe actualizar | Compañero de equipo (propietario) |
| Approved | La revisión se aprobó; la tarea queda finalizada | Revisor |
### Planificación → In progress
Cuando un compañero de equipo empieza una tarea, el estado del trabajo pasa a `in_progress`. El agente crea un comentario en la tarea con su plan y continúa trabajando. Todas las acciones de las herramientas nativas (read, bash, edit, write) se transmiten a un registro de tarea.
### Completed → Review
Cuando el compañero de equipo termina el trabajo, publica un comentario con el resultado y marca el estado del trabajo como `completed`. El lead o el revisor pueden entonces solicitar una revisión para iniciar el flujo de revisión.
### Review → Approved
Si la superficie de revisión muestra cambios aceptables, aprueba la revisión. La tarea queda finalizada y vinculada a su diff.
::: warning Revisión con corrección primero
Si se le piden cambios a un compañero de equipo durante la revisión, este debe publicar un comentario de seguimiento con las correcciones y, a continuación, el lead puede aprobar.
:::
## Tablero kanban
El tablero es la superficie operativa principal. Te permite:
- Examinar el trabajo abierto, bloqueado y en revisión
- Abrir el detalle de la tarea e inspeccionar los registros del runtime
- Revisar los cambios sin leer los archivos de sesión en bruto
- Asignar o reasignar propietarios
::: tip
Usa los botones de acción rápida de las tarjetas para iniciar, completar o solicitar la revisión sin abrir el panel de detalle.
:::
## Mensajes y comentarios
| Canal | Cuándo usarlo |
| --- | --- |
| Mensaje directo | Redirigir a un agente, hacer una pregunta rápida |
| Comentario en la tarea | Notas que pertenecen a una tarea específica |
Los comentarios conservan el contexto para una revisión posterior y aparecen en la línea de tiempo de la tarea.
::: tip Prioriza los comentarios en la tarea
Si la observación se refiere a una tarea específica, añádela como comentario en esa tarea en lugar de enviar un mensaje directo. Así el historial queda vinculado al trabajo.
:::
## Registros de tareas
Los registros específicos de cada tarea aíslan la salida del runtime, las acciones y los mensajes de una asignación concreta. Úsalos para responder:
- ¿Qué ejecutó este agente?
- ¿Por qué cambió este archivo?
- ¿Pidió ayuda a otro compañero de equipo?
- ¿Qué tarea produjo este diff?
### Lista de comprobación de validación
Cuando una tarea parece atascada o su diff parece desvinculado, verifica el ciclo de vida en este orden:
1. La tarea tiene el propietario esperado y pasó a `in_progress`.
2. El propietario publicó un comentario en la tarea con el plan o la primera actualización de progreso.
3. Los registros de la tarea muestran actividad del runtime dentro de la ventana de la tarea.
4. Los cambios de archivos están vinculados a la misma tarea, propietario y sesión.
5. El comentario final de la tarea incluye el comando de verificación y su resultado.
Para una depuración más profunda, usa los comandos de evidencia persistida en [Solución de problemas](/es/guide/troubleshooting#task-log-triage). La interfaz es la superficie de trabajo, pero los archivos de tarea persistidos, los inboxes y la evidencia del runtime son la fuente para los errores difíciles de lanzamiento o de atribución.
## Patrones de trabajo en paralelo
Los compañeros de equipo pueden trabajar en tareas independientes al mismo tiempo. También puedes crear vínculos de dependencia (`blocked-by`) para que una tarea espere hasta que otra se complete. Observa el tablero para detectar carriles bloqueados y reasigna propietarios si un compañero de equipo está inactivo mientras otro está sobrecargado.
## Procesos en vivo
La sección de procesos en vivo muestra las URL y los procesos en ejecución cuando los agentes inician servidores o herramientas locales. Abre las URL directamente desde la aplicación para inspeccionar los resultados. Los procesos permanecen registrados hasta que se detienen explícitamente o el runtime finaliza.
## Comunicación entre equipos
Los agentes pueden enviar mensajes a otros equipos cuando los equipos están vinculados. Usa esto para traspasos, bibliotecas compartidas o comprobaciones de estado entre escuadrones.

119
landing/product-docs/es/guide/code-review.md Normal file
View file

@ -0,0 +1,119 @@
---
title: Revisión de código – Documentación de Agent Teams
description: Inspecciona los diffs delimitados por tarea, acepta o rechaza hunks, deja comentarios en línea y gestiona los estados de revisión desde none hasta approved.
lang: es-ES
---
# Revisión de código
La revisión de código en Agent Teams está centrada en las tareas. Inspeccionas lo que cambió para una tarea específica en lugar de rastrear a través de un diff grande y sin estructura.
## Superficie de revisión
Para cada tarea completada que tocó archivos, la interfaz de revisión te permite:
- Inspeccionar los archivos modificados con contexto de antes/después
- Aceptar o rechazar hunks individuales
- Dejar comentarios en línea
- Conectar el diff con la descripción de la tarea y los registros del agente
## Decisiones a nivel de hunk
Acepta los cambios pequeños y correctos y rechaza los errores aislados sin descartar toda la tarea. Esto es útil cuando un agente resolvió la mayor parte de la tarea pero se extralimitó en un archivo.
::: tip Acepta de forma incremental
Si un diff es mayormente correcto, acepta primero los hunks buenos y solicita cambios únicamente para las partes que necesitan corrección. Esto mantiene el tablero en movimiento.
:::
Usa las decisiones a nivel de hunk para:
| Situación | Acción |
| --- | --- |
| Cambio correcto y delimitado | Acepta el hunk |
| Idea correcta, archivo equivocado o refactor demasiado amplio | Rechaza el hunk y solicita una corrección más acotada |
| Cambio de comportamiento poco claro | Comenta y pide verificación |
| Ruido de formato generado | Rechaza, a menos que el formato formara parte de la tarea |
## Iniciar la revisión
1. Abre una tarea completada
2. Mira la pestaña **Changes**
3. Si el diff parece razonable, haz clic en **Request Review** para mover la tarea a la columna review
Durante la revisión la tarea aún no se considera done, por lo que otros compañeros de equipo o el lead todavía pueden comentar sobre ella.
## Ciclo de revisión
Un ciclo de revisión saludable se ve así:
1. El propietario publica un comentario de resultado con el alcance modificado y la verificación
2. El revisor abre el diff de la tarea y comprueba los hunks frente a la descripción de la tarea
3. El revisor acepta los hunks buenos, rechaza los hunks malos o solicita cambios
4. El propietario corrige únicamente el alcance solicitado y publica un comentario de seguimiento
5. El revisor aprueba cuando el resultado de la tarea y el diff coinciden
Ejemplo de comentario de solicitud de cambios:
```text
Please keep the copy improvements, but revert the unrelated runtime wording in the provider table. Add the `pnpm --dir landing docs:build` result before resubmitting.
```
## Estados de revisión
| Estado | Significado |
| --- | --- |
| `none` | La tarea es nueva, está in progress o completada pero aún no está en revisión |
| `review` | La tarea está activamente bajo revisión |
| `needsFix` | Se solicitaron cambios; el propietario debe actualizar antes de la nueva aprobación |
| `approved` | La revisión fue aceptada y la tarea está finalizada |
## Flujo de trabajo de revisión por agentes
Los equipos pueden revisar el trabajo de los demás antes de que tomes la decisión final. Esto detecta regresiones evidentes y mantiene el tablero honesto, pero aun así deberías revisar tú mismo las áreas de riesgo.
La revisión por agentes es más útil cuando el revisor tiene una rúbrica clara. Por ejemplo, indícale a un revisor que compruebe solo la claridad de la documentación, solo la seguridad de IPC o solo la cobertura de pruebas. Las solicitudes amplias de "revisar todo" tienden a producir comentarios más débiles.
### Estado de revisión gestionado por MCP
Los cambios de estado de revisión (solicitar revisión, solicitar cambios, aprobar) están gestionados por herramientas. Dejar un comentario de "solicitar cambios" en una tarea **no** mueve la columna del kanban a `needsFix`: un lead o un agente debe llamar a la herramienta MCP apropiada:
- `review_request_changes` — mueve la tarea a `needsFix` y notifica al propietario
- `review_approve` — mueve la tarea a `approved` y finaliza la revisión
Los comentarios por sí solos son insuficientes para las transiciones de estado. Para ver la lista completa de herramientas MCP de revisión y sus parámetros, consulta [Integración de MCP](/es/guide/mcp-integration).
## Participantes de la revisión
El lead del equipo es el revisor predeterminado. Puedes configurar revisores adicionales en la configuración del Kanban si quieres que los compañeros revisen el trabajo de los demás.
## Qué comprobar manualmente
Prioriza estas áreas al revisar:
- **Autenticación de proveedores y detección del runtime** — ¿el agente cambió la configuración del runtime de una forma que rompería otras rutas?
- **Límites de IPC, preload y sistema de archivos** — mantén separadas las responsabilidades de Electron
- **Comportamiento de Git y worktree** - verifica el nombrado de ramas, los commits y los pushes; consulta [Estrategia de Git y worktree](/es/guide/git-worktree-strategy) para conocer los patrones de aislamiento.
- **Lógica de parseo y ciclo de vida de las tareas** — los cambios en las referencias de tareas, el chunking o el filtrado pueden romper la entrega de mensajes
- **Flujos de persistencia y revisión de código** — los cambios en el almacenamiento de tareas o en el estado de revisión deben mantenerse consistentes entre las capas de IPC
Para conocer el diseño canónico de las funciones y los enlaces a los guardrails estrictos, usa [Arquitectura para colaboradores](/es/reference/contributor-architecture).
## Verificación
Prefiere comandos de verificación enfocados. No deberían usarse comandos amplios de formato o lint-fix a menos que la tarea pretenda explícitamente un cambio amplio de formato.
Los buenos comentarios de verificación incluyen el comando y el resultado:
```text
Verified with `pnpm --dir landing docs:build`. Build passed.
```
Cuando se omite la verificación, el comentario de la tarea debería indicar por qué:
```text
Docs-only wording change. Build not run because the existing dev server was busy; checked Markdown links manually.
```
::: warning No apliques formato automático en todo el proyecto
A menos que la tarea trate específicamente sobre formato, evita ejecutar `pnpm lint:fix` en archivos no relacionados. Crea ruido en la superficie de revisión.
:::

106
landing/product-docs/es/guide/create-team.md Normal file
View file

@ -0,0 +1,106 @@
---
title: Crear un equipo – Documentación de Agent Teams
description: Define roles, asigna proveedores y modelos, redacta un briefing de equipo y configura el aislamiento por worktree y los niveles de autonomía.
lang: es-ES
---
# Crear un equipo
Un equipo es un grupo con nombre de agentes con roles, un lead, un proyecto objetivo y un prompt de coordinación.
## Primer equipo recomendado
Empieza con un equipo pequeño:
| Rol | Propósito |
| -------- | --------------------------------------------------------- |
| Lead | Divide el trabajo, crea tareas, coordina a los compañeros |
| Builder | Implementa tareas acotadas |
| Reviewer | Revisa el resultado, detecta regresiones, pide correcciones |
Esta estructura te da suficiente coordinación para ver el valor del producto sin hacer ruidoso el primer lanzamiento.
::: tip
Puedes añadir más miembros más adelante. Empieza con poco, valida el flujo de trabajo y luego escala.
:::
## Asignar proveedores y modelos
Cada miembro del equipo se ejecuta sobre un backend de proveedor. En el editor de equipos, elige un proveedor (Claude, Codex u OpenCode) y un modelo para cada miembro. La aplicación solo muestra los proveedores con los que ya te has autenticado.
Se admite mezclar proveedores en un mismo equipo — por ejemplo, un lead de Claude con builders de OpenCode.
::: info
Gemini está disponible como ruta de proveedor compatible. Consulta [Proveedores y runtimes](/es/reference/providers-runtimes) para conocer las opciones de autenticación y el estado actual de los proveedores.
:::
## Redactar un buen briefing de equipo
El briefing de equipo debería incluir:
- el resultado que quieres
- los archivos o áreas de funcionalidad que importan
- los límites de riesgo, como "no refactorizar módulos no relacionados"
- las expectativas de revisión
- los comandos de verificación cuando los conozcas
Ejemplo:
```text
Build a focused improvement to the download flow. Keep changes inside the landing app unless a shared helper is clearly needed. Create tasks before implementation, review each task diff, and run landing lint/build checks.
```
## Aislamiento por worktree
Los miembros de OpenCode pueden usar el **aislamiento por worktree** para trabajar en un worktree de Git independiente en lugar del directorio de trabajo principal. Esto evita conflictos de archivos cuando varios agentes editan el mismo proyecto.
::: warning
El aislamiento por worktree requiere un proyecto rastreado por Git y, actualmente, está limitado a los miembros de OpenCode.
:::
Para activarlo, activa la opción **Worktree isolation** al añadir o editar un miembro de equipo de OpenCode.
## Elegir la autonomía
Agent Teams admite distintos niveles de control. Usa más autonomía para cambios rutinarios y una revisión más estricta para áreas de riesgo como la autenticación de proveedores, el IPC, la persistencia, los flujos de trabajo de Git y las herramientas de publicación.
### Nivel de esfuerzo
Cada miembro del equipo tiene un ajuste de **esfuerzo** que controla cuánto razonamiento invierte el proveedor antes de responder. Un esfuerzo mayor produce un resultado más exhaustivo a costa de tiempo y tokens.
| Nivel | Cuándo usarlo |
| ------ | ------------------------------------------------------------- |
| Low | Consultas rápidas, pequeños cambios de formato, ediciones rutinarias |
| Medium | Predeterminado para la mayoría de tareas de implementación |
| High | Refactorizaciones complejas, cambios transversales, rutas de código de riesgo |
La aplicación ofrece niveles adicionales (minimal, xhigh, max) para los proveedores que los admiten. Si un modelo no admite un esfuerzo configurable, el selector se desactiva y se usa el valor predeterminado del proveedor.
### Modo rápido
Activa el **Modo rápido** por miembro para priorizar la velocidad sobre la profundidad. Esto se corresponde con el modo rápido/de velocidad nativo del proveedor cuando está disponible. Ponlo en **On** para tareas rutinarias, en **Off** para trabajo cuidadoso, o en **Inherit** para seguir el valor predeterminado a nivel de equipo.
### Limitar el contexto
Activa **Limit context** para reducir la ventana de contexto de un miembro. Esto es útil para los modelos de Claude que admiten contexto extendido (p. ej. 1M de tokens) — limitar el contexto evita un uso innecesario de tokens y puede mejorar la latencia en tareas que no necesitan un contexto amplio.
## Añadir contexto
Adjunta archivos, capturas de pantalla o notas concretas cuando cambien la tarea de forma sustancial. Los agentes pueden usar las descripciones de las tareas, los comentarios y los archivos adjuntos como contexto duradero.
## Vigilar la calidad de las tareas
Los buenos equipos crean tareas que son:
- lo bastante específicas para revisar
- lo bastante pequeñas para terminar
- vinculadas a un resultado visible
- respaldadas por una ruta de verificación
Si el lead crea tareas imprecisas, envía un mensaje directo pidiendo tareas más pequeñas y comprobables.
## Próximos pasos
- [Configuración del runtime](/es/guide/runtime-setup) — configura la autenticación de proveedores y los modelos
- [Revisión de código](/es/guide/code-review) — acepta, rechaza o comenta los cambios de los agentes
- [Solución de problemas](/es/guide/troubleshooting) — problemas habituales y soluciones

102
landing/product-docs/es/guide/git-worktree-strategy.md Normal file
View file

@ -0,0 +1,102 @@
---
title: Estrategia de Git y worktree – Documentación de Agent Teams
description: Decide cuándo usar el worktree principal, ramas de funcionalidades o el aislamiento por worktree de OpenCode para el trabajo de agentes en paralelo.
lang: es-ES
---
# Estrategia de Git y worktree
Git le da a Agent Teams la mejor ruta de revisión: diffs reducidos, visibilidad de las ramas, cambios acotados a las tareas y un trabajo en paralelo más seguro.
## Elige una estrategia
| Estrategia | Úsala cuando | Contrapartida |
| --- | --- | --- |
| Worktree principal | Trabajo en solitario, ediciones solo de documentación o un compañero de equipo a la vez | Simple, pero las ediciones en paralelo pueden chocar |
| Rama de funcionalidad | Un equipo está trabajando en un cambio coherente | Objetivo de revisión limpio, pero los compañeros de equipo siguen compartiendo archivos |
| Aislamiento por worktree | Varios compañeros de equipo de OpenCode pueden editar el mismo repositorio en paralelo | Mejor aislamiento, pero el merge y la revisión requieren más disciplina |
Empieza por lo simple. Añade el aislamiento por worktree cuando las ediciones en paralelo sean probables, no porque cada tarea necesite un checkout separado.
## Cuándo activar el aislamiento por worktree
Actívalo para los compañeros de equipo de OpenCode cuando:
- dos o más compañeros de equipo puedan editar el mismo repositorio a la vez
- una tarea pueda ejecutar formateadores, generadores de código o pruebas amplias
- quieras que la rama y el diff de cada compañero de equipo se mantengan separados
- el workspace del lead esté sucio y no deba recibir ediciones directas
Mantenlo desactivado cuando:
- la tarea sea de solo lectura
- un único compañero de equipo se encargue de todas las ediciones
- el repositorio no esté bajo control de versiones de Git
- necesites una ruta de runtime que no admita este modo de aislamiento
::: warning
El aislamiento por worktree se aplica actualmente a los miembros de OpenCode y requiere un proyecto bajo control de versiones de Git.
:::
## Higiene de las ramas
Antes de empezar el trabajo en paralelo:
```bash
git status --short
git branch --show-current
```
Usa una rama limpia cuando sea posible. Si el worktree principal ya tiene cambios del usuario, indica a los agentes que no reviertan archivos no relacionados y que mantengan el alcance de la tarea acotado.
Estilo de rama recomendado:
```text
agent/<team-or-task>/<short-purpose>
```
Ejemplos:
```text
agent/docs/mcp-guide
agent/review/task-log-filtering
agent/ui/code-review-polish
```
## Flujo de revisión
Para los worktrees aislados, revisa el diff del compañero de equipo antes de hacer merge o aplicar los cambios de vuelta al workspace principal.
1. Confirma que el comentario con el resultado de la tarea nombra el alcance modificado y la verificación.
2. Inspecciona el diff de la tarea en la interfaz de revisión.
3. Solicita cambios en la tarea si el diff toca archivos no relacionados.
4. Aprueba solo después de que las pruebas o las comprobaciones manuales coincidan con el riesgo de la tarea.
5. Haz merge o aplica los cambios de forma deliberada.
No hagas merge automático del resultado del worktree solo porque la tarea esté completa. Que esté completa significa que el agente cree que el trabajo está listo para revisión.
## Política de conflictos
Usa esta política para los equipos en paralelo:
| Situación | Acción |
| --- | --- |
| Dos compañeros de equipo editan el mismo archivo | Pausa una tarea o haz que un único responsable se encargue de la integración |
| Archivos generados modificados de forma amplia | Exige un comentario que explique el generador y el comando |
| El worktree principal tiene cambios no relacionados | Consérvalos y revisa solo los cambios propios de la tarea |
| La rama del worktree diverge | Haz rebase o merge manualmente tras la revisión, no dentro de una tarea de agente imprecisa |
## Ejemplo de prompt de tarea
```text
Implement the settings validation fix in your assigned worktree. Keep edits inside src/features/settings and focused tests. Do not touch provider auth or task storage. Post the test command and result before completing the task.
```
Este prompt funciona porque nombra el área permitida, los límites sensibles y la evidencia de finalización.
## Guías relacionadas
- [Crear un equipo](/es/guide/create-team)
- [Revisión de código](/es/guide/code-review)
- [Ejemplos de briefing de equipo](/es/guide/team-brief-examples)
- [Configuración del runtime](/es/guide/runtime-setup)

129
landing/product-docs/es/guide/installation.md Normal file
View file

@ -0,0 +1,129 @@
---
title: Instalación – Documentación de Agent Teams
description: Descarga e instala Agent Teams para macOS, Windows o Linux. Cubre las builds empaquetadas, la configuración desde el código fuente, las actualizaciones automáticas y los requisitos.
lang: es-ES
---
# Instalación
Agent Teams se distribuye como una aplicación de escritorio para macOS, Windows y Linux.
::: tip La vía más rápida
1. Descarga la build para tu plataforma a continuación
2. Inicia la aplicación: empieza con el modelo gratuito sin autenticación o conecta la autenticación de un proveedor desde la interfaz
3. Comienza el [inicio rápido](/es/guide/quickstart) para crear tu primer equipo
Arranque de la aplicación de escritorio: ejecuta `pnpm dev` para la aplicación de Electron. No inicies el modo de desarrollo de navegador/web para el uso normal.
:::
## Descargar builds
Usa la <a href="/es/download/" target="_self">página de descarga</a> o la última [versión de GitHub](https://github.com/777genius/agent-teams-ai/releases) cuando quieras la aplicación empaquetada:
- macOS Apple Silicon: `.dmg`
- macOS Intel: `.dmg`
- Windows: `.exe`
- Linux: `.AppImage`, `.deb`, `.rpm` o `.pacman`
::: warning Windows SmartScreen
Las aplicaciones de código abierto sin firmar o recién publicadas pueden activar SmartScreen. Si confías en la fuente de la versión, elige **More info** y luego **Run anyway**.
:::
## Requisitos
La aplicación empaquetada está diseñada para una incorporación sin configuración. Puedes empezar con el modelo gratuito sin autenticación: sin registro, claves de API ni tarjeta de crédito. Si quieres más modelos, la aplicación te guía en la detección del runtime y la autenticación del proveedor desde la interfaz.
Para modelos de pago o respaldados por una cuenta, conecta al menos un proveedor:
| Proveedor | Método de acceso |
| ------------------ | ------------------------------------------------- |
| Claude (Anthropic) | Inicio de sesión de Claude Code CLI o clave de API |
| Codex (OpenAI) | Inicio de sesión de Codex CLI o clave de API |
| Gemini (Google) | Google ADC, Gemini CLI o clave de API |
| OpenCode | Modelo gratuito incluido sin autenticación, o clave de API para un backend compatible (p. ej. OpenRouter) |
::: info
Gemini está disponible como una ruta de proveedor compatible. Consulta [Proveedores y runtimes](/es/reference/providers-runtimes) para conocer las opciones de autenticación y el estado actual de todos los proveedores.
:::
Para el desarrollo desde el código fuente, también necesitas:
| Herramienta | Versión |
| ----------- | ----------- |
| Node.js | 24.16.0 LTS |
| pnpm | 10+ |
En macOS, los binarios precompilados oficiales de Node.js 24 requieren macOS 13.5+.
## Ejecutar desde el código fuente
<InstallBlock command="git clone https://github.com/777genius/agent-teams-ai.git && cd agent-teams-ai && pnpm install && pnpm dev" label="Copiar" copied-label="Copiado" />
```bash
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
pnpm dev
```
`pnpm dev` inicia la aplicación de escritorio de Electron con recarga en caliente. Este es el objetivo de desarrollo predeterminado — no inicies un servidor de desarrollo web de navegador para el desarrollo normal. La ruta del navegador carece del IPC de escritorio completo, la terminal, la autenticación del proveedor y el comportamiento del ciclo de vida del equipo.
La rama `main` lleva el último desarrollo estable. Cambia a ramas de funciones solo si necesitas un cambio específico aún no publicado.
## Verificar la configuración
Después de instalar, confirma que la build esté en buen estado:
```bash
# Check that the desktop app compiles and starts
pnpm typecheck
# Verify the VitePress documentation site builds
pnpm --dir landing docs:build
```
Si `pnpm typecheck` informa de errores de tipo, busca una versión más reciente de las dependencias o de la versión fijada de TypeScript. Si `pnpm --dir landing docs:build` falla, inspecciona `landing/product-docs/` en busca de errores de sintaxis en el markdown o la configuración.
Si estás editando esta documentación, ejecuta la build para verificar tus cambios:
```bash
pnpm --dir landing docs:build
```
## Actualizaciones automáticas
La aplicación empaquetada busca actualizaciones automáticamente al iniciar y periódicamente mientras se ejecuta. Cuando hay una actualización disponible, la aplicación te pide que la descargues e instales. También puedes comprobarlo manualmente desde el menú de la aplicación.
::: tip
Las actualizaciones automáticas no están disponibles al ejecutar desde el código fuente. Trae los últimos cambios y vuelve a ejecutar `pnpm install` cuando cambien las dependencias.
:::
## Actualizar desde el código fuente
Si ejecutas desde el código fuente, trae la rama `main` y vuelve a ejecutar la instalación cuando cambien las dependencias:
```bash
git pull
pnpm install
```
Después de actualizar, verifica la build y la documentación:
```bash
pnpm typecheck
pnpm --dir landing docs:build
```
Usa siempre `pnpm dev` (Electron) — no el servidor de desarrollo del navegador — para el desarrollo normal.
## Próximos pasos
- [Inicio rápido](/es/guide/quickstart) — desde la instalación hasta el primer equipo en ejecución
- [Configuración del runtime](/es/guide/runtime-setup) — autenticación del proveedor y selección de modelo por runtime
- [Crear un equipo](/es/guide/create-team) — formas de equipo recomendadas y redacción del briefing
### Para colaboradores
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — navegación del repositorio y punteros de arquitectura
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — convenciones de trabajo y reglas del proyecto
- [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) — guardrails de implementación estrictos

225
landing/product-docs/es/guide/mcp-integration.md Normal file
View file

@ -0,0 +1,225 @@
---
title: Integración de MCP – Documentación de Agent Teams
description: Configura MCP en Agent Teams para operaciones del tablero, coordinación entre compañeros de equipo, servidores de herramientas externas y desarrollo de herramientas personalizadas.
lang: es-ES
---
# Integración de MCP
Agent Teams utiliza MCP en dos capas prácticas:
| Capa | Qué hace | Quién la usa |
| --- | --- | --- |
| Servidor de tablero integrado | Expone las herramientas de tareas, mensajes, revisión, procesos, runtime y comunicación entre equipos de Agent Teams | Leads y compañeros de equipo lanzados por la aplicación |
| Servidores MCP externos | Añaden herramientas opcionales como automatización de navegador, contexto de diseño, búsqueda en documentación o sistemas de la empresa | Usuarios y runtimes configurados |
Mantén esas capas separadas. El servidor MCP integrado `agent-teams` es la forma en que los agentes se coordinan dentro de Agent Teams. Los servidores MCP externos son herramientas de runtime opcionales.
## Cómo inyecta MCP Agent Teams
Cuando la aplicación de escritorio lanza miembros de equipo basados en Claude, escribe un archivo JSON temporal `--mcp-config` que contiene el servidor integrado `agent-teams`:
```json
{
"mcpServers": {
"agent-teams": {
"command": "node",
"args": ["/path/to/agent-teams-mcp/index.js"],
"env": {
"AGENT_TEAMS_MCP_CLAUDE_DIR": "/Users/you/.claude"
}
}
}
}
```
En desarrollo, el comando puede apuntar a `mcp-server/src/index.ts` a través de `tsx`. En las compilaciones empaquetadas, la aplicación copia el servidor MCP incluido a una ruta estable de datos de la aplicación y lo ejecuta con Node. El archivo generado es propiedad de la aplicación y se limpia con el mejor esfuerzo posible.
Los servidores MCP de usuario y de proyecto permanecen separados. La aplicación lee los servidores instalados desde:
| Ámbito | Ubicación |
| --- | --- |
| Usuario | `~/.claude.json` bajo `mcpServers` |
| Entrada de proyecto local en la configuración de Claude | `~/.claude.json` bajo `projects[projectPath].mcpServers` |
| Proyecto | `<project>/.mcp.json` bajo `mcpServers` |
Prefiere el ámbito de proyecto para herramientas que pertenecen a un único repositorio. Prefiere el ámbito de usuario para herramientas que reutilizas en proyectos no relacionados.
## Ejemplo de `.mcp.json` de proyecto
Coloca este archivo en la raíz del proyecto cuando un equipo deba ver el mismo servidor con ámbito de proyecto:
```json
{
"mcpServers": {
"docs-search": {
"command": "npx",
"args": ["-y", "@acme/docs-search-mcp"],
"env": {
"DOCS_INDEX_PATH": "./docs-index"
}
},
"local-browser": {
"command": "node",
"args": ["./tools/mcp/browser-server.js"]
}
}
}
```
Mantén los secretos fuera de los archivos `.mcp.json` confirmados en el control de versiones. Coloca las credenciales en tu shell, en una configuración con ámbito de usuario o en el flujo de instalación de MCP personalizado de la aplicación si el valor debe permanecer local.
## Flujo de trabajo de MCP del tablero
Los agentes deben usar las herramientas MCP del tablero cuando el trabajo pertenece a una tarea:
1. Lee el contexto más reciente de la tarea.
2. Inicia la tarea solo cuando realmente comiences a trabajar.
3. Añade comentarios de tarea para bloqueos, planes y resultados finales.
4. Marca la tarea como completada después de publicar el comentario con el resultado.
5. Envía un mensaje breve cuando un lead o un compañero de equipo necesite conocer el resultado.
Ejemplo de flujo de un agente:
```text
task_get -> task_start -> edit/test -> task_add_comment -> task_complete -> message_send
```
Usa un mensaje directo para la coordinación. Usa un comentario de tarea para dejar un historial duradero de la tarea.
::: tip
Si la nota afecta a la revisión, la verificación, un cambio de alcance o un bloqueo, ponla en la tarea.
:::
## Herramientas integradas de Agent Teams
El servidor MCP registra herramientas desde `agent-teams-controller/src/mcpToolCatalog.js`. El bucle de registro vive en `mcp-server/src/tools/index.ts`, y cada grupo tiene su propio archivo bajo `mcp-server/src/tools/`.
Herramientas operativas habituales:
| Herramienta | Uso |
| --- | --- |
| `task_get` | Lee el contexto más reciente de la tarea, los comentarios, los adjuntos, el estado y las relaciones |
| `task_start` | Marca una tarea en in progress cuando el trabajo realmente comienza |
| `task_add_comment` | Añade notas de bloqueo, notas de verificación, planes y resúmenes de resultado final |
| `task_complete` | Completa una tarea después de publicar el comentario con el resultado final |
| `message_send` | Envía un mensaje visible en la bandeja de entrada a un lead, un compañero de equipo o un usuario |
| `review_request`, `review_start`, `review_approve`, `review_request_changes` | Avanzan los flujos de trabajo de revisión con ámbito de tarea |
| `process_register`, `process_list`, `process_stop`, `process_unregister` | Hacen seguimiento de los servidores de desarrollo, watchers y otros servicios en segundo plano propiedad de los compañeros de equipo |
Los nombres de las herramientas pueden aparecer ante los runtimes con prefijos de espacio de nombres de MCP, por ejemplo `mcp__agent-teams__task_get`. El nombre canónico de la herramienta dentro del servidor MCP sigue siendo `task_get`.
## Registrar una nueva herramienta integrada
Para el trabajo en el repositorio de Agent Teams, añade herramientas integradas del tablero a través de la estructura existente de FastMCP:
1. Añade la implementación de la herramienta al archivo correspondiente en `mcp-server/src/tools/`, o crea un nuevo archivo de grupo si el dominio es realmente nuevo.
2. Añade el nombre de la herramienta al grupo apropiado en `agent-teams-controller/src/mcpToolCatalog.js`.
3. Conecta un nuevo grupo a través de `mcp-server/src/tools/index.ts` solo cuando se necesite un nuevo grupo de dominio.
4. Valida la entrada con `zod` y llama a la API del controlador en lugar de leer los archivos del tablero directamente.
5. Añade pruebas específicas en `mcp-server/test/tools.test.ts` o un caso e2e cuando el transporte sea relevante.
Estructura mínima:
```ts
server.addTool({
name: 'task_example',
description: 'Explain what this tool does for agents.',
parameters: z.object({
teamName: z.string().min(1),
claudeDir: z.string().min(1).optional(),
taskId: z.string().min(1)
}),
execute: async ({ teamName, claudeDir, taskId }) => {
assertConfiguredTeam(teamName, claudeDir);
const controller = getController(teamName, claudeDir);
return jsonTextContent(controller.tasks.getTask(taskId));
}
});
```
No crees una herramienta que omita la validación del controlador, modifique archivos de equipo no relacionados o exponga un acceso amplio al sistema de archivos o a los procesos sin una necesidad concreta de la tarea.
## Servidores MCP externos
Usa servidores MCP externos cuando un compañero de equipo necesite una conexión duradera a una herramienta, no solo un prompt con contexto pegado.
Buenos casos de uso:
- herramientas de pruebas de navegador o de sitios web
- herramientas de datos de diseño o de producto
- documentación interna y sistemas de búsqueda
- sistemas de seguimiento de incidencias o de soporte
- herramientas de inspección de bases de datos con credenciales de solo lectura
Malos casos de uso:
- secretos pegados en los prompts
- archivos puntuales que se pueden adjuntar directamente
- herramientas que modifican sistemas de producción sin revisión
- acceso amplio al sistema de archivos local cuando basta con un ámbito de proyecto más reducido
## Ámbitos
Agent Teams reconoce ámbitos de MCP compartidos y orientados al proyecto.
| Ámbito | Úsalo cuando |
| --- | --- |
| Usuario o Global | El mismo servidor debe estar disponible en varios proyectos |
| Proyecto o Local | El servidor pertenece a un único repositorio, espacio de trabajo o contexto de equipo |
Prefiere el ámbito más reducido que aún haga utilizable el flujo de trabajo. Los servidores con ámbito de proyecto son más fáciles de razonar durante la revisión porque la herramienta pertenece al proyecto que se está modificando.
## Lista de comprobación de configuración
Antes de asignar una tarea que dependa de un servidor MCP:
1. Instala o configura el servidor.
2. Confirma que aparece en la lista de MCP instalados de la aplicación para el ámbito previsto.
3. Ejecuta los diagnósticos desde el registro de MCP o la interfaz de extensiones cuando esté disponible.
4. Empieza con una tarea de solo lectura de bajo riesgo.
5. Menciona el uso previsto de la herramienta MCP en la descripción de la tarea o en el briefing del equipo.
Si un servidor falla en los diagnósticos, corrige eso primero. Un mejor prompt de tarea no reparará un comando ausente, una ruta de configuración incorrecta o unas credenciales rechazadas.
## Instalar un servidor personalizado desde la aplicación
La aplicación de escritorio expone las API del registro de MCP a través de IPC de Electron para búsqueda, exploración, instalación, instalación personalizada, desinstalación, lectura del estado instalado y diagnósticos. Las instalaciones personalizadas validan el nombre del servidor, el ámbito, la ruta del proyecto, los nombres de las variables de entorno y las cabeceras HTTP antes de llamar a la ruta de instalación del runtime.
Usa la instalación personalizada cuando tengas un paquete MCP que aún no esté en el registro:
| Campo | Ejemplo |
| --- | --- |
| Nombre del servidor | `docs-search` |
| Ámbito | `project` para este repositorio, `user` para todos los proyectos |
| Tipo | `stdio` para comandos locales, `http` o `sse` para servidores remotos |
| Paquete | `@acme/docs-search-mcp` |
| Env | `DOCS_INDEX_PATH=./docs-index` |
Tras la instalación, ejecuta los diagnósticos y crea una pequeña tarea de solo lectura para comprobar la superficie de la herramienta antes de asignar trabajo más grande.
## Ejemplo de tarea
```text
Audit the docs home page with the browser MCP. Check desktop and mobile widths, capture any layout issue as a task comment, and only edit landing/product-docs files. Run `pnpm --dir landing docs:build` before completion.
```
Esto funciona porque nombra la herramienta, la superficie, el límite de escritura y el paso de verificación.
## Reglas de seguridad
- No des todos los servidores MCP a todos los compañeros de equipo por defecto.
- Mantén las herramientas con capacidad de escritura fuera de los equipos amplios, salvo que la revisión las requiera.
- Prefiere credenciales de solo lectura para las tareas de inspección.
- Pon el uso de herramientas con impacto en producción detrás de comentarios de tarea explícitos y de revisión.
- Trata los fallos de diagnóstico de MCP como fallos de configuración, no como fallos del agente.
- Evita confirmar secretos en `.mcp.json` o en los prompts.
- Usa valores absolutos de `projectPath` al instalar servidores con ámbito de proyecto a través de la aplicación.
- No edites los archivos `agent-teams-mcp-*.json` generados por la aplicación; son artefactos temporales de lanzamiento.
## Guías relacionadas
- [Configuración del runtime](/es/guide/runtime-setup)
- [Ejemplos de briefing de equipo](/es/guide/team-brief-examples)
- [Flujo de trabajo de los agentes](/es/guide/agent-workflow)
- [Desarrolladores](/es/developers/)

193
landing/product-docs/es/guide/quickstart.md Normal file
View file

@ -0,0 +1,193 @@
---
title: Inicio rápido – Documentación de Agent Teams
description: Pasa de una instalación nueva a un equipo de agentes de IA en funcionamiento en unos minutos. Cubre la instalación, la selección del runtime, la creación del equipo y la primera revisión de código.
lang: es-ES
---
# Inicio rápido
Esta guía te lleva de una instalación nueva a un equipo en funcionamiento en unos minutos.
## El camino más corto
```bash
# 1. Install prerequisites
node --version # need 20+
pnpm --version # need 10+
# 2. Clone and install
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
# 3. Start the desktop app (default workflow)
pnpm dev
# 4. Verify a docs-only change
pnpm --dir landing docs:build
```
La aplicación de escritorio Electron (`pnpm dev`) es el objetivo principal: no uses el servidor de desarrollo web/navegador para el desarrollo normal. El camino del navegador carece del IPC de escritorio, la terminal, la autenticación de proveedores y el comportamiento del ciclo de vida del equipo.
## Antes de empezar
Necesitas:
- **Un ordenador** con macOS, Windows o Linux
- **(Recomendado) Un proyecto gestionado con Git** — el aislamiento con worktree y la revisión de diffs dependen de Git
- **(Opcional) Acceso a un proveedor** — la configuración del runtime detecta los proveedores disponibles desde la UI, pero algunos caminos requieren autenticación existente (Anthropic, OpenAI, etc.)
Si alguno de los pasos siguientes no funciona, consulta la [guía de solución de problemas](/es/guide/troubleshooting#team-does-not-launch) para ver soluciones habituales.
Para conocer las convenciones del proyecto y las pautas de arquitectura, consulta estos archivos canónicos antes de hacer cambios:
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — navegación del repositorio y punteros de arquitectura
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — convenciones de trabajo y reglas del proyecto
- [Estándar de arquitectura de funciones](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) — estructura para nuevas funciones
- [Runbook de depuración](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) — diagnósticos de lanzamiento y de compañeros de equipo
## 1. Ejecutar desde el código fuente o descargar
**Descarga la aplicación empaquetada** para macOS, Windows o Linux desde la <a href="/es/download/" target="_self">página de descarga</a> - no se necesitan requisitos previos. Empieza con el modelo gratuito sin autenticación, o conecta la autenticación de un proveedor desde la UI cuando quieras más modelos.
**O ejecuta desde el código fuente** para el desarrollo:
Requiere Node.js 24.16.0 LTS y pnpm 10+. En macOS, los binarios precompilados oficiales de Node.js 24 requieren macOS 13.5+.
```bash
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
pnpm dev
```
`pnpm dev` inicia la aplicación de escritorio Electron con recarga en caliente. Este es el objetivo de desarrollo predeterminado. No inicies un servidor de desarrollo web en el navegador para el desarrollo normal: el camino del navegador carece del IPC de escritorio completo, la terminal, la autenticación de proveedores y el comportamiento del ciclo de vida del equipo.
## 2. Abrir o crear un proyecto
Inicia la aplicación y selecciona el directorio del proyecto en el que quieres que trabajen los agentes. Agent Teams lee los archivos locales del proyecto y el estado del runtime/sesión para que la UI pueda mostrar tareas, registros, diffs y la actividad de los compañeros de equipo.
::: tip
Elige un proyecto gestionado con Git para tener la mejor experiencia. Tanto el aislamiento con worktree como la revisión basada en diffs dependen de Git.
:::
Antes de lanzar un equipo, comprueba que el proyecto tiene una base lo bastante limpia:
```bash
git status --short
```
No necesitas un árbol perfectamente limpio, pero deberías saber qué cambios son tuyos antes de que los agentes empiecen a editar. Esto hace que los diffs de las tareas y la revisión a nivel de hunk sean mucho más fiables.
## 3. Elegir un camino de runtime
El flujo de configuración detecta automáticamente los runtimes instalados en tu máquina. Una primera configuración habitual es:
| Runtime | Bueno para |
| -------- | ----------------------------------------------- |
| Claude | Usuarios de Claude Code y acceso existente a Anthropic |
| Codex | Flujos de trabajo nativos de Codex y acceso a OpenAI |
| OpenCode | Modelo gratuito sin autenticación, equipos multimodelo y muchos backends de proveedores |
::: info
Gemini está disponible como un camino de proveedor compatible. Consulta [Proveedores y runtimes](/es/reference/providers-runtimes) para ver las opciones de autenticación y el estado actual de los proveedores.
:::
Consulta [Configuración del runtime](/es/guide/runtime-setup) para una configuración detallada por proveedor.
Para verificar un runtime de pago o respaldado por una cuenta fuera de la aplicación, comprueba el binario y prueba la autenticación:
```bash
# Check that the runtime is installed and on PATH
command -v claude && claude --version
command -v codex && codex --version
command -v opencode && opencode --version
```
Si el comando falla, primero arregla la instalación del runtime o el `PATH`. Los prompts del equipo no pueden sortear un binario que falta o la falta de autenticación del proveedor para los modelos que la requieren.
::: tip
Si el binario se encuentra pero la aplicación informa de "not logged in", es posible que el entorno difiera entre tu terminal y la aplicación. Consulta el [registro de diagnóstico de autenticación](/es/guide/troubleshooting#auth-diagnostic-log) para compararlos.
:::
## 4. Crear tu primer equipo
Crea un equipo con un lead y uno o más especialistas. Mantén pequeño el primer equipo: un lead, un agente de implementación y un agente orientado a la revisión son suficientes para validar el flujo de trabajo.
Consulta [Crear un equipo](/es/guide/create-team) para ver la estructura recomendada y consejos.
Para el primer lanzamiento, prefiere una forma de equipo como esta:
| Miembro | Responsabilidad | Notas |
| --- | --- | --- |
| Lead | Dividir el objetivo en tareas y coordinar el estado | Mantenlo en el proveedor más fiable que tengas |
| Builder | Implementar tareas acotadas | Dale límites claros de archivo o función |
| Reviewer | Revisar el trabajo completado | Pídele que se centre en regresiones y pruebas faltantes |
Evita empezar con cinco o más compañeros de equipo. Más agentes aumentan la concurrencia, los registros, el uso del proveedor y el riesgo de conflictos antes de que sepas que la configuración está en buen estado.
## 5. Darle al lead un objetivo concreto
Escribe el objetivo como lo harías al instruir a un lead de ingeniería:
```text
Improve the onboarding flow. Split the work into tasks, keep changes small, and ask for review before broad refactors.
```
Los buenos primeros prompts incluyen un alcance concreto, límites de seguridad y verificación:
```text
Improve the docs quickstart. Keep edits inside landing/product-docs. Add practical examples, preserve existing VitePress syntax, and run `pnpm --dir landing docs:build` before marking tasks done.
```
Evita prompts vagos como "make the app better" para la primera ejecución. El lead puede descomponer objetivos grandes, pero una mejor entrada produce tareas más pequeñas y una revisión más limpia.
::: tip
Si el equipo se lanza pero no aparece ninguna tarea, comprueba si el lead recibió tu prompt. Consulta [faltan respuestas de los agentes](/es/guide/troubleshooting#agent-replies-are-missing) para ver diagnósticos.
:::
El lead crea tareas, asigna trabajo y coordina a los compañeros de equipo. Puedes seguir el progreso en el tablero kanban e intervenir con comentarios o mensajes directos en cualquier momento.
## 6. Revisar los resultados
Abre las tareas completadas o listas para revisión, inspecciona el diff y acepta, rechaza o comenta cambios individuales. Usa los registros de las tareas cuando necesites entender por qué un agente tomó una decisión.
Consulta [Revisión de código](/es/guide/code-review) para ver el flujo de trabajo de revisión completo.
Antes de aprobar la primera tarea, comprueba tres cosas:
1. El comentario de la tarea explica qué cambió
2. Los archivos modificados coinciden con el alcance de la tarea
3. El resultado de la verificación es visible en el comentario o los registros de la tarea
## Errores comunes
| Síntoma | Causa probable | Comprobación |
| --- | --- | --- |
| La aplicación no detecta un runtime | El binario no está en el `PATH`, o la aplicación y la terminal ven entornos diferentes | Ejecuta `command -v <runtime>` en una terminal y luego usa el mismo entorno de terminal para lanzar la aplicación |
| El lanzamiento del equipo se queda colgado | Falta la autenticación del proveedor para un modelo de pago/cuenta, cadena de modelo incorrecta o no se encuentra el binario del runtime | Consulta [Solución de problemas](/es/guide/troubleshooting#team-does-not-launch) |
| El carril de OpenCode atascado en `registered` | La evidencia del carril aún no se ha confirmado, o hay una discrepancia en la cadena de modelo | Inspecciona `~/.claude/teams/<team>/.opencode-runtime/lanes/` |
| Faltan respuestas de los agentes | Problema de reintento de entrega del runtime, de análisis o de atribución de tareas | Abre los registros de la tarea y revisa el ledger de entrega |
| El proveedor devuelve errores 429 | Se alcanzó el límite de velocidad | Espera a que se restablezca o cambia de modelo/proveedor |
## Próximos pasos
- [Crear un equipo](/es/guide/create-team) — formas de equipo recomendadas y redacción del briefing
- [Configuración del runtime](/es/guide/runtime-setup) — autenticación de proveedores y selección de modelo
- [Revisión de código](/es/guide/code-review) — revisar, aprobar o solicitar cambios
### Para colaboradores
Si vas a modificar Agent Teams o esta documentación, empieza por los archivos canónicos del proyecto en la raíz del repositorio:
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — convenciones de trabajo y reglas del proyecto
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — capa de navegación para las pautas de arquitectura e implementación
- [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) — guardrails estrictos de implementación
- [Estándar de arquitectura de funciones](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) — estructura para nuevas funciones
- [Runbook de depuración de equipos de agentes](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) — diagnósticos de lanzamiento, bootstrap y de compañeros de equipo
Para verificar que este sitio de documentación se compila correctamente:
```bash
pnpm --dir landing docs:build
```

179
landing/product-docs/es/guide/runtime-setup.md Normal file
View file

@ -0,0 +1,179 @@
---
title: Configuración del runtime – Documentación de Agent Teams
description: Configura los runtimes de Claude Code, Codex u OpenCode. Cubre la autenticación, el acceso a proveedores, el modo multimodelo y las comprobaciones previas al lanzamiento.
lang: es-ES
---
# Configuración del runtime
Agent Teams es una capa de coordinación. El trabajo real del modelo se ejecuta a través de runtimes y proveedores locales compatibles.
::: tip Inicio rápido: elige tu primer runtime
| Si tú ... | Empieza con |
| --- | --- |
| Ya usas Claude Code o tienes acceso a Anthropic | **Claude**: autenticación familiar, configuración mínima |
| Usas Codex o flujos de trabajo basados en OpenAI | **Codex**: integración nativa |
| Quieres probar Agent Teams sin registro ni claves de API | **OpenCode**: usa el modelo gratuito incluido sin autenticación |
| Quieres enrutamiento multimodelo o una amplia cobertura de proveedores | **OpenCode**: el más flexible, una sola configuración para muchos backends |
| No estás seguro de qué runtime encaja | **OpenCode**: cubre la mayor cantidad de opciones de proveedores y te permite cambiar más adelante |
Empieza con un runtime y un compañero de equipo. Confirma que un lanzamiento funciona antes de expandirte al modo multimodelo.
:::
## Requisitos previos
Antes de lanzar un equipo, asegúrate de que:
- El binario del runtime está instalado y en tu `PATH`.
- Tu cuenta de proveedor tiene acceso activo al modelo que pretendes usar, a menos que empieces con el modelo gratuito de OpenCode incluido sin autenticación.
- La ruta del proyecto existe y se puede leer.
- La aplicación y tu terminal usan el mismo entorno de home/configuración cuando pruebas la autenticación manualmente.
::: tip
Empieza con un solo compañero de equipo y un proveedor. Confirma que un lanzamiento funciona antes de añadir carriles multimodelo.
:::
Comprobaciones rápidas en la terminal:
```bash
command -v claude
command -v codex
command -v opencode
```
Ejecuta el comando del runtime que planeas usar. Si no imprime nada, instala el runtime o corrige el `PATH` antes de lanzar un equipo.
## Rutas compatibles
| Ruta | CLI predeterminada | Proveedores típicos | Úsala cuando |
| --- | --- | --- | --- |
| Claude | `claude` | Anthropic | Ya usas Claude Code o flujos de trabajo respaldados por Anthropic |
| Codex | `codex` | OpenAI | Quieres una integración de runtime nativa de Codex |
| OpenCode | `opencode` | OpenRouter y muchos backends | Quieres enrutamiento multimodelo y una amplia cobertura de proveedores |
La aplicación detecta los runtimes compatibles y guía la configuración desde la interfaz cuando es posible.
Gemini está disponible como una ruta de proveedor compatible con autenticación mediante Google ADC (`gcloud auth`), OAuth de Gemini CLI y clave de API. Configúralo desde la interfaz de configuración del runtime cuando se detecte el backend de Gemini.
## Acceso a proveedores
Agent Teams no tiene ningún nivel de pago propio. Puedes empezar con el modelo gratuito de OpenCode incluido sin autenticación: sin registro, sin claves de API ni tarjeta de crédito. Para modelos adicionales, aporta el acceso a proveedores que ya tengas: suscripciones, autenticación del runtime local o claves de API, según la ruta que elijas.
- Las rutas de **Claude** y **Codex** dependen de sus respectivas herramientas de autenticación de la CLI.
- **OpenCode** puede ejecutar primero el modelo gratuito incluido sin autenticación. Otros modelos de OpenCode pueden necesitar claves de API específicas del proveedor en un archivo de configuración (p. ej., `openrouter`, `openai`, `anthropic`).
## Configuración de la autenticación
### Claude Code
Ejecuta el flujo de autenticación estándar en una terminal:
```bash
claude login
```
Después, verifica que la CLI es accesible:
```bash
claude --version
```
Si la aplicación empaquetada informa de "not logged in" mientras que tu terminal funciona, compara el `$HOME` y el `PATH` que ve la aplicación con los de la terminal que usaste para iniciar sesión. El registro de diagnóstico de autenticación descrito en [Solución de problemas](/es/guide/troubleshooting#auth-diagnostic-log) es el mejor punto de partida.
### Codex
Instala y autentícate mediante el flujo de la CLI de OpenAI:
```bash
codex login
```
Después, verifica que el runtime es accesible:
```bash
codex --version
```
Los lanzamientos nativos de Codex usan el estado de la cuenta de Codex y los datos del catálogo de modelos cuando están disponibles. Si falta un modelo en la interfaz, actualiza el estado del proveedor antes de editar los prompts del equipo.
### OpenCode
Para usar el modelo gratuito incluido sin autenticación, selecciónalo en la aplicación y lánzalo sin registrarte en un proveedor. Para usar otros backends de OpenCode, crea o edita `~/.opencode/config.json` (o la ruta equivalente en tu plataforma) con la clave del proveedor que quieras:
```json
{
"providers": {
"openrouter": {
"apiKey": "sk-or-..."
}
}
}
```
Usa el nombre de proveedor exacto que OpenCode espera. Si configuras un nombre de proveedor personalizado, compruébalo dos veces contra el ID de proveedor que usas en la cadena del modelo (por ejemplo, `openrouter/moonshotai/kimi-k2.6` usaría el bloque `openrouter`).
Ejemplos de cadenas de modelo:
| Cadena de modelo | Bloque de proveedor que debe existir |
| --- | --- |
| `openrouter/moonshotai/kimi-k2.6` | `openrouter` |
| `openai/gpt-5.4` | `openai` |
| `anthropic/claude-sonnet-4-6` | `anthropic` |
Si OpenCode se lanza pero un compañero de equipo nunca llega a ser entregable, inspecciona la evidencia del carril antes de asumir que el modelo ignoró el prompt. Consulta [Solución de problemas](/es/guide/troubleshooting#opencode-registered-but-bootstrap-unconfirmed).
### Gemini
Gemini admite tres métodos de autenticación:
- **Google ADC** — ejecuta `gcloud auth application-default login` para autenticarte mediante las credenciales predeterminadas de aplicación de Google (Application Default Credentials).
- **Gemini CLI** — ejecuta `gemini login` si la CLI de Gemini está instalada.
- **Clave de API** — define `GEMINI_API_KEY` en tu entorno o configúrala a través de la interfaz Manage Providers de la aplicación.
La aplicación detecta automáticamente qué método de autenticación está disponible y muestra el proveedor Gemini en la interfaz de configuración del runtime y de creación de equipos cuando el backend es accesible.
## Modo multimodelo
El modo multimodelo puede enrutar el trabajo a través de muchos backends de proveedores mediante una configuración compatible con OpenCode. Úsalo cuando necesites flexibilidad de proveedores o quieras que los compañeros de equipo usen carriles de modelo diferentes.
::: info Carriles de modelo
Cada compañero de equipo puede usar un par `providerId` + `model` diferente. En la interfaz de edición del equipo, expande las opciones del miembro para anular los valores predeterminados globales.
:::
Una configuración multimodelo conservadora:
| Rol | Proveedor | Por qué |
| --- | --- | --- |
| Lead | Claude o Codex | Mantén la coordinación en el proveedor en el que más confías |
| Builder | OpenCode | Usa un amplio enrutamiento de modelos para el trabajo de implementación |
| Reviewer | Claude, Codex o un segundo modelo de OpenCode | Separa el criterio de revisión del carril del builder |
Evita mezclar muchos proveedores desconocidos en el primer lanzamiento. Confirma una tarea pequeña por carril antes de asignar trabajo amplio.
## Lista de comprobación previa al lanzamiento
Antes de lanzar un equipo:
1. El runtime seleccionado está instalado
2. El binario del runtime está en el `PATH` del entorno
3. La autenticación del proveedor está configurada para el backend elegido
4. El proveedor tiene acceso a la cadena de modelo exacta que especifiques
5. La ruta del proyecto existe y se puede leer
## Cuándo cambiar de ruta de runtime
Cambia cuando la ruta actual esté bloqueada por la disponibilidad del modelo, los límites de tasa, las capacidades del proveedor o las necesidades de los roles del equipo. Mantén el mismo proyecto y flujo de trabajo del equipo, pero valida una tarea pequeña después de cambiar.
::: warning Trata los errores de configuración como problemas de configuración
Si la autenticación falla, se rechaza el nombre de un modelo o no se encuentra el binario del runtime, corrige primero la configuración. No cambies los prompts del equipo ni el código del proyecto para sortear un problema de configuración del runtime.
:::
Usa esta tabla de decisiones:
| Síntoma | Mejor primera acción |
| --- | --- |
| Binario no encontrado | Corrige la instalación o el `PATH` |
| El inicio de sesión funciona en la terminal pero no en la aplicación | Revisa el registro de diagnóstico de autenticación de Electron y el entorno |
| Modelo rechazado | Verifica el ID exacto del modelo en el runtime del proveedor |
| 429 repetidos | Reduce la concurrencia o cambia de modelo/proveedor |
| Carril de OpenCode atascado | Inspecciona el manifiesto del carril y `opencode-sessions.json` |

131
landing/product-docs/es/guide/team-brief-examples.md Normal file
View file

@ -0,0 +1,131 @@
---
title: Ejemplos de briefing de equipo – Documentación de Agent Teams
description: Plantillas prácticas de briefing de equipo para correcciones pequeñas, trabajo de documentación, tareas de implementación, revisiones y áreas de alto riesgo.
lang: es-ES
---
# Ejemplos de briefing de equipo
Un buen briefing de equipo da al lead suficiente estructura para crear tareas pequeñas sin imponer cada detalle de implementación de antemano.
Usa esta estructura:
```text
Outcome:
Scope:
Boundaries:
Coordination:
Verification:
Review:
```
## Briefing mínimo
Úsalo para trabajo pequeño y de bajo riesgo.
```text
Outcome: Improve the quickstart so a new user can launch one team successfully.
Scope: Keep edits inside landing/product-docs.
Boundaries: Do not rewrite the whole docs structure.
Coordination: Create one or two tasks, keep comments on the task.
Verification: Run `pnpm --dir landing docs:build`.
Review: Summarize changed pages and any remaining gaps.
```
## Briefing de implementación
Úsalo cuando los cambios de código afectan a un área de funcionalidad.
```text
Outcome: Add a focused improvement to task comment filtering.
Scope: Work inside the task/comment feature files unless a shared helper is clearly needed.
Boundaries: Do not change task storage format or review state semantics.
Coordination: Split parser, UI, and tests into separate tasks if they can be reviewed independently.
Verification: Run the focused unit tests first, then the feature typecheck if touched.
Review: Call out parsing edge cases and any behavior that affects existing task comments.
```
## Briefing de documentación
Úsalo para trabajo de documentación y guías.
```text
Outcome: Draft practical workflow guides from the docs audit.
Scope: Add concise VitePress pages under landing/product-docs/guide.
Boundaries: Avoid moving existing navigation hubs owned by other tasks.
Coordination: Check related docs tasks before editing nav.
Verification: Run `pnpm --dir landing docs:build`.
Review: Include links added to sidebar and any pages intentionally left as drafts.
```
## Briefing centrado en la revisión
Úsalo para áreas de riesgo como IPC, autenticación de proveedores, persistencia, Git o lógica del ciclo de vida de las tareas.
```text
Outcome: Fix the launch failure without changing successful launch behavior.
Scope: Start from the newest launch-failure artifact and the affected runtime adapter.
Boundaries: Do not change provider prompts until setup and runtime evidence are inspected.
Coordination: Make one diagnostic task and one fix task if the cause is confirmed.
Verification: Run focused tests and one desktop smoke check when practical.
Review: Lead must inspect the diff before approval.
```
## Briefing de proveedores mixtos
Úsalo cuando los compañeros de equipo ejecutan distintos carriles de proveedor/modelo.
```text
Outcome: Implement and review a small feature using separate builder and reviewer lanes.
Scope: Builder edits the feature. Reviewer inspects only the task diff and tests.
Boundaries: Do not switch model ids mid-task unless launch fails before work begins.
Coordination: Builder posts result comment first. Reviewer posts findings as task comments.
Verification: Builder runs focused tests. Reviewer checks failure output and changed scope.
Review: Lead approves only after reviewer comments are resolved.
```
## Bloques de agente en los briefings
Los bloques de agente son texto oculto exclusivo para agentes, envuelto en marcadores como `<info_for_agent>...</info_for_agent>`. La aplicación los elimina de la visualización normal, pero los mantiene disponibles para la coordinación entre agentes. Úsalos cuando el briefing necesite decir algo a los agentes que sería ruido para un lector humano.
Ejemplo: un briefing que indica al lead cómo dividir el trabajo sin exponer las instrucciones de coordinación al usuario:
```text
Outcome: Add a dark mode toggle to the application settings.
Scope: Settings UI, theme context, and CSS variables.
Boundaries: Do not change existing light theme values or provider auth screens.
<info_for_agent>
Split this into three tasks: (1) theme context and CSS vars, (2) toggle component and settings wiring, (3) dark mode preview in existing docs screenshots if practical.
</info_for_agent>
```
El bloque mantiene limpio el briefing orientado al humano mientras da al lead una orientación estructurada para dividir las tareas.
## Qué evitar
| Briefing débil | Mejor reemplazo |
| --- | --- |
| "Improve the app" | Nombra el flujo de trabajo, los archivos y la comprobación de éxito |
| "Fix all docs" | Elige un grupo de guías y un comando de build |
| "Use the best model" | Nombra las opciones de proveedor/modelo o deja que se mantengan los valores predeterminados de la aplicación |
| "Refactor as needed" | Indica qué módulos pueden cambiar |
| "Make it production ready" | Define la revisión, las pruebas y las comprobaciones de despliegue |
## Antes del lanzamiento
Comprueba estos puntos antes de iniciar el equipo:
1. El briefing nombra un resultado concreto.
2. Los límites de riesgo son explícitos.
3. El lead puede dividir el trabajo en tareas revisables.
4. Se incluyen comandos de verificación cuando se conocen.
5. Las áreas sensibles requieren revisión antes de la aprobación.
Si el briefing sigue siendo amplio, lanza primero un agente en solitario o un equipo pequeño y pídele que produzca un plan de tareas en lugar de la implementación.
## Guías relacionadas
- [Crear un equipo](/es/guide/create-team)
- [Integración de MCP](/es/guide/mcp-integration)
- [Estrategia de Git y worktree](/es/guide/git-worktree-strategy)

310
landing/product-docs/es/guide/troubleshooting.md Normal file
View file

@ -0,0 +1,310 @@
---
title: Solución de problemas – Documentación de Agent Teams
description: Resuelve problemas de lanzamiento de equipos, respuestas de agentes faltantes, límites de uso, problemas de autenticación de la CLI y bloqueos en el bootstrap de los lanes con diagnósticos locales.
lang: es-ES
---
# Solución de problemas
La mayoría de los problemas de equipo entran en una de cuatro categorías: configuración del runtime, confirmación del lanzamiento, análisis de tareas y límites del proveedor.
## Configuración rápida de evidencias
Para cualquier problema del ciclo de vida del equipo, define primero estas variables y reutiliza el mismo shell:
```bash
TEAM="<team-name>"
TEAM_DIR="$HOME/.claude/teams/$TEAM"
TASKS_DIR="$HOME/.claude/tasks/$TEAM"
```
Luego confirma que los archivos esperados existen antes de interpretar el estado de la interfaz:
```bash
test -d "$TEAM_DIR" && find "$TEAM_DIR" -maxdepth 2 -type f | sort | sed -n '1,80p'
test -d "$TASKS_DIR" && find "$TASKS_DIR" -maxdepth 1 -name '*.json' | sort | sed -n '1,40p'
```
::: warning Las evidencias primero
No corrijas los prompts, la configuración del proveedor ni la limpieza de procesos basándote únicamente en una insignia atascada. Primero correlaciona la interfaz con los archivos persistidos, los artefactos de lanzamiento y la evidencia del runtime.
:::
## El equipo no se lanza
Comprueba cada elemento en orden:
1. **Runtime disponible** — la CLI seleccionada (`claude`, `codex`, `opencode`) está instalada
2. **PATH accesible** — el binario está disponible en el `PATH` del entorno
3. **Acceso al modelo** — el proveedor tiene acceso a la cadena de modelo solicitada (especialmente en OpenCode, donde los nombres exactos de proveedor/modelo importan)
4. **Ruta del proyecto** — el directorio del proyecto existe y se puede leer
5. **Red / VPN** — algunos proveedores descartan el tráfico cuando hay una VPN activa
::: tip
Ejecuta el binario del runtime en una terminal para verificar el `PATH` y la autenticación. Por ejemplo: `claude --version` u `opencode --version`.
:::
### OpenCode: registrado pero bootstrap sin confirmar
Si OpenCode muestra `registered` pero el bootstrap no está confirmado, inspecciona los artefactos primero antes de cambiar los prompts del equipo.
Los detalles para colaboradores/depuración están en [Arquitectura para colaboradores](/es/reference/contributor-architecture), que enlaza con el runbook canónico de depuración de equipos de agentes.
Observa el artefacto de fallo de lanzamiento más reciente:
```bash
LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
MANIFEST_PATH="$(jq -r '.manifestPath' "$LATEST_FAILURE")"
jq '.classification, .bootstrapTransportBreadcrumb, .memberSpawnStatuses' "$MANIFEST_PATH"
```
`latest.json` apunta al directorio de artefactos empaquetados más reciente y a su `manifest.json`. El manifiesto incluye:
- `classification` — por qué se consideró que el lanzamiento fue un fallo
- `bootstrapTransportBreadcrumb` — ruta de entrega utilizada
- Los estados de spawn de los miembros
- Registros y trazas redactados
Comprueba también el manifiesto del lane:
```bash
jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime/lanes" -maxdepth 2 -name manifest.json -print -exec jq '.activeRunId, .entries' {} \; 2>/dev/null
```
::: tip No adivines a partir de la interfaz
Correlaciona siempre los diagnósticos de la interfaz con los archivos persistidos (`launch-state.json`, `bootstrap-journal.jsonl`) y la evidencia específica del runtime.
:::
## Diagnósticos generales
Empieza por los archivos persistidos en disco en lugar de basarte solo en la interfaz.
### Raíz del equipo
```bash
printf '%s\n' "$TEAM_DIR"
```
Archivos clave y lo que te indican:
- `launch-state.json` — estado de lanzamiento/actividad de los miembros (`.teamLaunchState`, `.summary`, `.members`)
- `bootstrap-journal.jsonl` — eventos de bootstrap ordenados desde la CLI/runtime (`tail -80`)
- `bootstrap-state.json` — resumen de la fase de bootstrap
- `config.json` — configuración del proveedor, el modelo y el proyecto
- `inboxes/*.json` y `sentMessages.json` — estado de entrega de los mensajes
```bash
jq '.teamLaunchState, .summary, .members' "$TEAM_DIR/launch-state.json"
tail -80 "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
```
### Evidencia del runtime de OpenCode
Para los compañeros de equipo de OpenCode, la prueba de la sesión está en el almacén del runtime del lane:
- `.opencode-runtime/lanes.json` — índice de lanes con su estado
- `.opencode-runtime/lanes/<lane>/manifest.json` — `activeRunId` y entradas de evidencia
- `.opencode-runtime/lanes/<lane>/opencode-sessions.json` — registros de sesión confirmados
Estado saludable esperado: estado del lane `active`, el manifiesto tiene `activeRunId` con al menos una entrada de evidencia, el miembro tiene `bootstrapConfirmed: true`.
```bash
jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime" -maxdepth 3 -type f | sort
```
### Artefactos de fallo de lanzamiento
Cuando un lanzamiento se marca como fallo, inspecciona `latest.json`:
```bash
LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
jq '.' "$LATEST_FAILURE"
jq '.' "$(jq -r '.manifestPath' "$LATEST_FAILURE")"
```
El manifiesto incluye:
- `classification` — por qué se consideró que el lanzamiento fue un fallo
- `bootstrapTransportBreadcrumb` — ruta de entrega utilizada
- Los estados de spawn de los miembros y los registros/trazas redactados
## Faltan respuestas de los agentes
Abre los registros de tareas y los mensajes de los compañeros de equipo. Las respuestas faltantes suelen deberse a:
- **Reintento de entrega del runtime** — puede que el agente haya respondido, pero el mensaje no se entregó a la aplicación. Comprueba el ledger de entrega.
- **Análisis o filtrado** — la salida del agente no incluía los marcadores esperados ni las referencias de tarea.
- **Atribución de tarea** — el trabajo ocurrió durante la sesión pero no se vinculó a la tarea porque faltaba el id de tarea correcto en la salida.
::: warning No supongas que el silencio significa que se ignoró
No supongas que el modelo ignoró el mensaje hasta que los registros lo confirmen.
:::
Usa el estado persistido de los mensajes para separar lo "no enviado" de lo "enviado pero no renderizado":
```bash
jq '.' "$TEAM_DIR/inboxes/user.json" 2>/dev/null
jq '.' "$TEAM_DIR/sentMessages.json" 2>/dev/null
```
Comprueba `from`, `to`, `messageId`, `relayOfMessageId` y `taskRefs`. Para los compañeros de equipo de OpenCode, inspecciona también la evidencia de entrega del runtime antes de suponer que el modelo ignoró el prompt.
## Las tareas no están vinculadas a los cambios
Usa los registros específicos de cada tarea y los enlaces de revisión de código. Si un diff parece desvinculado:
- Comprueba si el id de tarea o la referencia de tarea se incluyó en la salida del agente.
- Verifica que el agente llamó a `task_add_comment` antes de hacer ediciones.
- Asegúrate de que el agente llamó a `task_start` para que el tablero supiera que el trabajo había comenzado.
Para los compañeros de equipo de OpenCode, la prueba fehaciente de que una sesión pertenece a una tarea está en `opencode-sessions.json` y la entrada del manifiesto del lane, no solo en el flujo de mensajes de la interfaz.
### Triaje del registro de tareas
Cuando un registro de tarea parezca incompleto, busca por id de tarea en el JSON de tareas, las bandejas de entrada y los eventos de bootstrap:
```bash
TASK="<short-or-full-task-id>"
rg -n "$TASK" "$TASKS_DIR" "$TEAM_DIR/inboxes" "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
```
Interpreta el resultado con cuidado:
| Evidencia | Qué demuestra | Qué no demuestra |
| --- | --- | --- |
| Mensaje entregado | La aplicación escribió o retransmitió un prompt | Que el agente progresó |
| Comentario de tarea | El agente publicó texto visible en el tablero | Que el comentario sea progreso significativo |
| Filas de herramientas nativas | El runtime hizo trabajo en una sesión | Que el trabajo pertenezca a esta tarea, a menos que la atribución coincida |
| Entrada del ledger de cambios | La aplicación registró cambios de archivo | Que la implementación sea correcta |
En OpenCode, un registro de tarea saludable suele incluir filas nativas del runtime como `read`, `bash`, `edit` o `write`, además de filas de MCP de Agent Teams. Si solo ves filas `agent-teams_*`, confirma la atribución de la tarea y los límites de la sesión antes de ampliar la coincidencia de registros.
## Límites de uso
Si un proveedor informa de una hora de restablecimiento conocida, Agent Teams puede indicar al lead que continúe tras el enfriamiento. Si se desconoce la hora de restablecimiento, espera o cambia de proveedor/ruta de runtime.
| Comportamiento del proveedor | Acción sugerida |
| --- | --- |
| Se muestra una hora de restablecimiento conocida | Espera el enfriamiento y continúa |
| No se muestra ninguna hora de restablecimiento | Cambia de proveedor o de ruta de runtime |
| 429 repetidos | Reduce la concurrencia o usa un lane de modelo distinto |
## Problemas de autenticación de la CLI
### `claude login` no persiste
Si la CLI está autenticada en una terminal pero la aplicación dice que no lo está, verifica que la autenticación se guarda en la ruta de configuración esperada y que el proceso de la aplicación ve el mismo `$HOME`.
### Clave del proveedor de OpenCode rechazada
- Verifica que el nombre del proveedor en `config.json` coincide con el prefijo del proveedor en la cadena de modelo
- Asegúrate de que la clave no haya caducado ni haya sido revocada en el panel del proveedor
### Registro de diagnóstico de autenticación
Cada llamada a `CliInstallerService.getStatus()` añade una línea a `claude-cli-auth-diag.ndjson` en la carpeta de registros de Electron (normalmente `~/Library/Logs/<product-name>/` en macOS). Si el archivo supera los **512 KiB**, se trunca a vacío antes de la siguiente escritura.
Comprueba este archivo si ves "Not logged in" o errores de autenticación en la aplicación empaquetada.
## Bootstrap del lane atascado
Para los lanes secundarios de OpenCode:
- La ausencia de `inboxes/<member>.json` no es automáticamente un error. Los lanes de OpenCode no tienen que crearse mediante la bandeja de entrada primaria antes de arrancar.
- Si la interfaz muestra que el equipo aún se está lanzando mientras los miembros primarios ya son utilizables, "se han unido todos los compañeros de equipo" está esperando a los lanes secundarios.
- Si `Prepared communication channels for X/Y members` se queda colgado, verifica si `Y` incluye incorrectamente a miembros secundarios de OpenCode.
### Entradas vacías en el manifiesto del lane
Si el puente dice que el bootstrap tuvo éxito pero `manifest.json` muestra `entries: []`, el problema es la **confirmación de la evidencia**, no el comportamiento del modelo. El miembro no debe considerarse entregable hasta que existan `opencode-sessions.json` y su entrada en el manifiesto.
## Estados comunes de los miembros
| Estado | Significado |
| --- | --- |
| `confirmed_alive` + `bootstrapConfirmed` | Saludable y listo |
| `registered` / `runtime_pending_bootstrap` | El proceso o el lane existe, pero la prueba de bootstrap aún no se ha confirmado |
| `failed_to_start` + `runtime_process` | El proceso existe, pero la puerta de lanzamiento falló. Comprueba los diagnósticos |
| `failed_to_start` + `stale_metadata` | El pid/sesión guardado está obsoleto o muerto |
::: warning
`member_briefing` por sí solo NO es evidencia del runtime. Para OpenCode, la prueba fehaciente es la evidencia del runtime confirmada, como `opencode-sessions.json` y la entrada del manifiesto.
:::
## Modo de depuración del runtime
Para la depuración local, puedes forzar que los compañeros de equipo se ejecuten en paneles de tmux:
```bash
# Launch from a terminal
CLAUDE_TEAM_TEAMMATE_MODE=tmux pnpm dev
# Or add to custom CLI args
--teammate-mode tmux
```
Úsalo para inspeccionar el comportamiento interactivo de la CLI. No lo consideres totalmente equivalente al backend de procesos.
## Comprobaciones rápidas
Usa la aplicación de escritorio Electron para la validación normal. El modo de desarrollo en navegador/web no incluye el runtime de escritorio completo, el IPC, la autenticación del proveedor, la terminal ni el comportamiento del ciclo de vida del equipo.
### Cambios solo en la documentación
Desde la raíz del repositorio:
```bash
pnpm --dir landing docs:build
git diff --check -- landing/product-docs
```
### Cambios en el ciclo de vida del equipo
Empieza de forma acotada y luego amplía:
```bash
pnpm test -- test/main/services/team/TeamProvisioningService.test.ts
pnpm test -- test/main/services/team/TeamAgentLaunchMatrix.safe-e2e.test.ts
pnpm typecheck
git diff --check
```
### Prueba rápida de un equipo en vivo
Usa un equipo pequeño y un proyecto desechable bajo control de Git:
1. Inicia la aplicación de escritorio con `pnpm dev`.
2. Crea un lead más un builder.
3. Pide un cambio mínimo con un comando de verificación explícito.
4. Confirma que la tarea pasa de `pending` -> `in_progress` -> `completed`.
5. Abre los registros de tareas y verifica que las filas de herramientas, los comentarios de tarea y los cambios de archivo cuadran.
6. Detén únicamente el equipo/procesos propios de la prueba rápida al limpiar.
::: warning Limpieza acotada únicamente
No mates todos los hosts de OpenCode, paneles de tmux no relacionados ni equipos de usuario mientras limpias una prueba rápida.
:::
## Limpieza segura
Al limpiar procesos obsoletos:
1. Identifica el pid y confirma que pertenece al equipo / lane actual.
2. Detén únicamente los procesos que pertenezcan explícitamente a una prueba rápida o al lanzamiento que estás depurando.
3. **No mates** todos los procesos de OpenCode ni de hosts compartidos como atajo.
## Cuándo recopilar evidencias
Antes de pedir ayuda, recopila:
- El id de tarea (corto o completo)
- El nombre del equipo
- La ruta del runtime (`claude`, `codex` u `opencode`)
- Un extracto del registro de lanzamiento (de `latest.json` o `bootstrap-journal.jsonl`)
- La cadena de proveedor / modelo
- La ventana de tiempo exacta en la que ocurrió el problema
Estos datos suelen ser suficientes para depurar problemas del ciclo de vida del lanzamiento y de las tareas.
::: tip
Si el problema persiste, abre los archivos persistidos del equipo en `~/.claude/teams/<teamName>/` y correlaciona los diagnósticos de la interfaz con el estado de los procesos en vivo antes de cambiar código.
:::

81
landing/product-docs/es/index.md Normal file
View file

@ -0,0 +1,81 @@
---
title: Documentación de Agent Teams – Ejecuta equipos de agentes de IA desde una aplicación de escritorio local
description: Documentación de Agent Teams, una aplicación de escritorio gratuita para la orquestación de agentes de IA. Crea equipos, observa el trabajo en un tablero kanban, revisa los cambios de código y coordina flujos de trabajo con Claude, Codex, OpenCode y multimodelo.
lang: es-ES
layout: home
hero:
name: Documentación de Agent Teams
text: Ejecuta equipos de agentes de IA desde una aplicación de escritorio local
tagline: Crea equipos, observa el trabajo moverse por un tablero kanban, revisa los cambios de código y coordina flujos de trabajo con Claude, Codex, OpenCode y multimodelo sin renunciar al control local.
actions:
- theme: brand
text: Inicio rápido
link: /es/guide/quickstart
- theme: alt
text: Instalar
link: /es/guide/installation
- theme: alt
text: Conceptos
link: /es/reference/concepts
features:
- icon: "01"
title: Flujo de trabajo centrado en el equipo
details: Define roles, lanza un lead y deja que los agentes dividan, reclamen y coordinen las tareas.
link: /es/guide/create-team
linkText: Crear un equipo
- icon: "02"
title: Tablero kanban en vivo
details: Observa cómo las tareas avanzan por todo, in progress, review, done y approved a medida que los agentes trabajan.
link: /es/guide/agent-workflow
linkText: Entender el flujo de trabajo
- icon: "03"
title: Revisión de código integrada
details: Inspecciona los diffs por tarea, acepta o rechaza hunks y comenta donde los agentes necesiten orientación.
link: /es/guide/code-review
linkText: Revisar cambios
- icon: "04"
title: Configuración adaptada al runtime
details: Usa Claude, Codex, OpenCode o proveedores multimodelo a través del acceso que ya tienes.
link: /es/guide/runtime-setup
linkText: Configurar los runtimes
- icon: "05"
title: Control local-first
details: La aplicación de escritorio lee el estado local del proyecto y del runtime. Tu código permanece en tu máquina a menos que un proveedor seleccionado reciba el contexto del prompt.
link: /es/reference/privacy-local-data
linkText: Modelo de privacidad
- icon: "06"
title: Equipos depurables
details: Rastrea los logs de las tareas, la salida del runtime, los mensajes de los compañeros de equipo y los procesos en vivo cuando un lanzamiento o una tarea se atasca.
link: /es/guide/troubleshooting
linkText: Solución de problemas
---
<InstallBlock label="Copiar" copied-label="Copiado" />
## Empieza aquí
Agent Teams es una aplicación de escritorio gratuita para orquestar equipos de agentes de IA. No te limitas a enviar prompts aislados a un solo agente: creas un equipo, asignas roles y observas cómo los agentes coordinan el trabajo a través de un tablero de tareas.
<DocsCardGrid />
## Próximos pasos después del lanzamiento
Después de crear tu primer equipo, explora estas guías para ir más allá:
- **Configuración del runtime** - configura Claude, Codex, OpenCode o proveedores multimodelo: [Configurar los runtimes](/es/guide/runtime-setup)
- **Flujo de trabajo de los agentes** - entiende cómo los agentes coordinan a través del tablero de tareas: [Entender el flujo de trabajo](/es/guide/agent-workflow)
- **Ejemplos de briefing de equipo** - aprende patrones de prompts a partir de briefings del mundo real: [Ver ejemplos](/es/guide/team-brief-examples)
- **Revisión de código** - inspecciona los diffs, acepta o rechaza los cambios: [Revisar cambios](/es/guide/code-review)
- **Solución de problemas** - diagnostica lanzamientos atascados, compañeros de equipo ausentes y fallos de tareas: [Solución de problemas](/es/guide/troubleshooting)
- **Estrategia de Git y worktree** - usa el aislamiento con worktree cuando varios compañeros de equipo editan el mismo repositorio en paralelo: [Conoce más sobre los worktrees](/es/guide/git-worktree-strategy)
- **Notas de la versión** - consulta las novedades de cada versión: [Ver versiones](/es/reference/release-notes)
## Referencia
Usa las páginas de referencia cuando necesites terminología exacta, el comportamiento de los proveedores, la arquitectura para colaboradores o los límites de privacidad.
<DocsCardGrid type="reference" />
## Vista previa del producto
<ZoomImage src="/screenshots/1.jpg" alt="Tablero kanban de Agent Teams" caption="El estado de las tareas, la actividad de los compañeros de equipo y el flujo de revisión permanecen visibles en un único espacio de trabajo." />

85
landing/product-docs/es/reference/concepts.md Normal file
View file

@ -0,0 +1,85 @@
---
title: Conceptos – Documentación de Agent Teams
description: Vocabulario fundamental de Agent Teams — equipos, leads, compañeros de equipo, tareas, kanban, bandejas de entrada, runtimes y revisión.
lang: es-ES
---
# Conceptos
Esta página define los términos fundamentales que se utilizan en todo Agent Teams. Úsala como vocabulario compartido para la aplicación, el tablero de tareas, los mensajes y el flujo de revisión.
## Equipo
Un equipo es un grupo nombrado de agentes vinculado a una única ruta de proyecto. Tiene un lead, compañeros de equipo opcionales, ajustes de runtime/proveedor, prompts, bandejas de entrada, tareas y estado de lanzamiento local.
## Lead {#lead}
El lead es el coordinador del equipo. Convierte el objetivo de un usuario en tareas, asigna o reorienta a los compañeros de equipo, hace seguimiento de los bloqueos, solicita revisiones y mantiene el trabajo avanzando por el tablero.
[Compañero de equipo →](#teammate)
Los mensajes del lead siguen una ruta de entrega distinta a la de los mensajes de los compañeros de equipo: la aplicación retransmite las entradas de la bandeja de entrada del lead hacia el runtime del lead, mientras que los compañeros de equipo leen sus propios archivos de bandeja de entrada entre turnos.
## Compañero de equipo {#teammate}
Un compañero de equipo es un agente del equipo que no es el lead. Los compañeros de equipo suelen asumir roles específicos, como builder, revisor, investigador o tester. Un compañero de equipo puede recibir mensajes directos, asignaciones de tareas, comentarios de tareas y solicitudes de revisión.
[Lead ↑](#lead)
## Tarea
Una tarea es la unidad de trabajo duradera. Tiene un id, un estado, un propietario, una descripción, comentarios, registros, adjuntos, referencias a tareas y cambios revisables.
Los estados habituales de una tarea son `todo`, `in_progress`, `done`, `review` y `approved`. Internamente, el archivo de la tarea almacena el estado de trabajo, mientras que la ubicación de revisión y aprobación también puede usar el estado de superposición del kanban.
## Kanban
El kanban es la vista de tablero para el trabajo del equipo. Te permite escanear las tareas por estado, abrir los detalles de una tarea, inspeccionar registros, revisar diffs, aprobar el trabajo terminado o solicitar cambios.
## Bandeja de entrada
Una bandeja de entrada es un archivo de mensajes local para un participante del equipo. Agent Teams usa las bandejas de entrada para los mensajes de usuario, los mensajes del lead, los mensajes de los compañeros de equipo, los metadatos de entrega del runtime, los mensajes entre equipos y algunas notificaciones del sistema.
Los mensajes son registros locales duraderos. La entrega sigue dependiendo de que el runtime seleccionado esté activo y sea capaz de procesar su siguiente turno.
## Bloque de agente
Un bloque de agente es texto de instrucciones oculto y exclusivo para agentes, envuelto con `<info_for_agent>...</info_for_agent>`. La interfaz elimina estos bloques de la visualización normal orientada a las personas, pero los agentes y la entrega del runtime pueden usarlos para detalles de coordinación.
El marcador canónico actual es `info_for_agent`. Documentos más antiguos pueden usar bloques de código entre comillas con un marcador `info_for_agent`, o etiquetas al estilo XML `<agent_block>` — estos son patrones heredados y, cuando se encuentren, deberían migrarse a `info_for_agent`. (El nombre de etiqueta original era `agent-block`; la forma con guion bajo `<agent_block>` se usa en el código fuente de VitePress para evitar el análisis HTML.)
## Fase de contexto
Una fase de contexto es un segmento de la línea de tiempo del contexto de una sesión. La compactación inicia una nueva fase, de modo que el uso de tokens y de contexto puede analizarse antes y después del reinicio.
El seguimiento del contexto separa categorías como las instrucciones del proyecto, los archivos mencionados, la salida de las herramientas, el texto de razonamiento, la coordinación del equipo y los mensajes de usuario. Estas cifras son diagnósticos, no estados de cuenta de facturación del proveedor.
## Runtime
Un runtime es la ruta de ejecución local que ejecuta el turno de un agente. Las rutas de runtime admitidas incluyen Claude Code, Codex y OpenCode.
El runtime se encarga del comportamiento de ejecución del modelo, los detalles de autenticación, la semántica de ejecución de las herramientas, los límites de tasa, la disponibilidad de los modelos y algunos formatos de transcripción/registro.
## Proveedor
Un proveedor es la ruta de acceso a los modelos que hay detrás de un runtime. Los ids de proveedor actuales incluyen Anthropic, Codex, Gemini y OpenCode. OpenCode puede enrutar hacia muchos proveedores de modelos mediante su propia configuración.
Agent Teams orquesta tareas y mensajes, pero no sustituye la autenticación del proveedor ni la política del proveedor.
## Modo solo
El modo solo ejecuta un equipo de un solo miembro. Resulta útil para trabajos rápidos, para reducir la sobrecarga de coordinación y para validar un prompt antes de expandirlo a un equipo completo.
## Comunicación entre equipos
Los agentes pueden enviarse mensajes dentro de un mismo equipo y entre equipos distintos. Úsalo cuando equipos separados se encargan de trabajos relacionados y necesitan coordinarse sin agruparlo todo en un único equipo de gran tamaño.
## Nivel de autonomía
La autonomía controla cuánto pueden hacer los agentes antes de preguntar. Una autonomía más alta es más rápida; una autonomía más baja es más segura para rutas de código sensibles, persistencia, autenticación de proveedores, operaciones de Git y publicaciones de versiones.
## Revisión
La revisión es el flujo de aceptación con alcance de tarea. Una tarea puede pasar a review, recibir comentarios o cambios solicitados y, después, pasar a approved cuando se acepta el resultado.
La revisión está ligada a los diffs locales y al historial de la tarea, por lo que funciona mejor cuando las tareas se mantienen acotadas y los agentes mencionan la tarea en la que están trabajando.

55
landing/product-docs/es/reference/contributor-architecture.md Normal file
View file

@ -0,0 +1,55 @@
---
title: Arquitectura para colaboradores – Documentación de Agent Teams
description: Guía para colaboradores sobre la estructura de las funciones, los límites entre runtime y proveedor, los guardrails estrictos y los documentos canónicos de arquitectura.
lang: es-ES
---
# Arquitectura para colaboradores
Esta página es un mapa para colaboradores. Apunta a la guía canónica del repositorio en lugar de reformular cada regla de implementación.
## Fuentes canónicas
Usa estos archivos como fuente de verdad al cambiar la aplicación:
| Necesidad | Fuente canónica |
| --- | --- |
| Resumen del repositorio y comandos | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) |
| Convenciones de trabajo local | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) |
| Guardrails estrictos | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) |
| Estructura de funciones medianas y grandes | [docs/FEATURE_ARCHITECTURE_STANDARD.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) |
| Depuración del lanzamiento de equipos de agentes | [docs/team-management/debugging-agent-teams.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) |
## Estructura de las funciones
Las funciones medianas y grandes deben residir bajo `src/features/<feature-name>/` y seguir el estándar de arquitectura de funciones. Mantén los detalles internos de cada función detrás de puntos de entrada públicos y evita las importaciones profundas que crucen los límites entre funciones.
Para el trabajo nuevo, parte del slice existente `src/features/recent-projects` como implementación de referencia local. Las correcciones pequeñas pueden permanecer cerca de la ruta de código existente cuando crear un slice de función añadiría más estructura que valor.
## Límites entre runtime y proveedor
Agent Teams es responsable de la orquestación: equipos, tareas, mensajes, estado de lanzamiento, interfaz de revisión, diagnósticos y persistencia local.
La ruta de runtime/proveedor seleccionada es responsable de la ejecución del modelo, la autenticación, la disponibilidad de modelos, los límites de tasa, la semántica de las herramientas y las evidencias de transcripción específicas del runtime. No hagas que los prompts o el estado de la interfaz compensen una autenticación faltante, binarios faltantes, ids de modelo rechazados o interrupciones del proveedor. Para los detalles de configuración orientados al usuario, consulta [Proveedores y runtimes](/es/reference/providers-runtimes).
## Depuración de equipos de agentes
Para los bloqueos en el lanzamiento, los estados `registered` / bootstrap no confirmado de OpenCode, las respuestas faltantes de los compañeros de equipo o los registros de tareas sospechosos, comienza por el runbook de depuración dedicado. Inspecciona el artefacto de fallo de lanzamiento más reciente en `~/.claude/teams/<team>/launch-failure-artifacts/latest.json` y, a continuación, correlaciona el estado de la interfaz con los archivos persistidos y la evidencia específica del runtime.
Evita las limpiezas amplias mientras depuras. Detén únicamente el proceso, la lane, el equipo o la ejecución de smoke que puedas identificar como pertenecientes al problema.
## Convenciones para colaboradores
- Usa `pnpm dev` para la aplicación de escritorio Electron durante el desarrollo normal.
- No uses el modo de desarrollo del navegador como sustituto del runtime de escritorio, IPC, terminal, autenticación del proveedor o comportamiento del ciclo de vida del equipo.
- Mantén separadas las responsabilidades de main, preload, renderer, shared y feature de Electron.
- Usa `wrapAgentBlock(text)` para los bloques exclusivos de agentes en lugar de concatenar marcadores manualmente.
- Prefiere la verificación enfocada. Evita el ruido de `lint:fix` o de formateo amplio a menos que la tarea trate explícitamente sobre el formateo.
- Trata el parsing, el ciclo de vida de las tareas, la detección de proveedor/runtime, la persistencia, IPC, Git y los flujos de revisión como áreas de alto riesgo que necesitan pruebas específicas o una ruta de verificación clara.
## Páginas relacionadas
- [Configuración del runtime](/es/guide/runtime-setup)
- [Solución de problemas](/es/guide/troubleshooting)
- [Revisión de código](/es/guide/code-review)
- [Privacidad y datos locales](/es/reference/privacy-local-data)

95
landing/product-docs/es/reference/faq.md Normal file
View file

@ -0,0 +1,95 @@
---
title: Preguntas frecuentes – Documentación de Agent Teams
description: Preguntas frecuentes sobre Agent Teams — precios, acceso a modelos, runtimes, privacidad, revisión y solución de problemas.
lang: es-ES
---
# Preguntas frecuentes
## ¿Agent Teams es gratis?
Sí. La aplicación es gratuita y de código abierto. El acceso al proveedor o al runtime puede tener un costo dependiendo de lo que uses.
## ¿Agent Teams incluye acceso a modelos?
No. Agent Teams es la capa local de orquestación e interfaz de usuario. El acceso a los modelos proviene de la ruta de runtime/proveedor seleccionada, como Claude Code, Codex u OpenCode.
## ¿Qué runtimes son compatibles?
Las rutas de runtime compatibles son Claude Code, Codex y OpenCode. La aplicación también rastrea ids de proveedor como Anthropic, Codex, Gemini y OpenCode cuando el runtime los expone.
## ¿Necesito instalar primero Claude Code o Codex?
No siempre. La aplicación guía la detección y la configuración del runtime desde la interfaz de usuario. Algunas rutas todavía requieren autenticación de runtime externa.
La configuración de OpenCode es independiente de la configuración de Claude Code y Codex. Si un lanzamiento falla, revisa el estado del runtime y la autenticación del proveedor antes de cambiar el prompt del equipo.
## ¿Cómo compruebo si un runtime está listo?
Primero ejecuta el comando del runtime en una terminal:
```bash
claude --version
codex --version
opencode --version
```
Luego confirma la autenticación del proveedor para la ruta que seleccionaste. Si el comando o la comprobación de autenticación falla fuera de Agent Teams, corrige la configuración antes de lanzar un equipo.
## ¿Sube mi código a los servidores de Agent Teams?
No. Agent Teams no es un servicio de sincronización de código en la nube. Las llamadas a modelos respaldadas por un proveedor pueden recibir contexto del prompt dependiendo del runtime que selecciones.
## ¿Dónde se almacenan los archivos del equipo?
Los datos de coordinación del equipo se almacenan localmente en `~/.claude/teams/<team>/` (macOS/Linux) o `%APPDATA%\Claude\teams\<team>\` (Windows), los archivos de tareas en `~/.claude/tasks/<team>/` o `%APPDATA%\Claude\tasks\<team>\`, y los datos de sesión del proyecto en `~/.claude/projects/<encoded-project>/` cuando están disponibles.
## ¿Qué puede salir de mi máquina?
El contexto del prompt, el contenido de los archivos seleccionados, los resultados de las herramientas, la salida de los comandos, el texto de las tareas, los comentarios y los archivos adjuntos pueden salir de tu máquina a través de la ruta de runtime/proveedor cuando un agente usa un modelo respaldado por un proveedor. El comportamiento exacto depende del runtime y del proveedor.
## ¿Los agentes pueden comunicarse entre sí?
Sí. Los agentes pueden enviar mensajes a sus compañeros de equipo, comentar en las tareas, coordinarse entre equipos y usar referencias de tareas para mantener las conversaciones vinculadas al trabajo.
## ¿Qué debo poner en el primer prompt del equipo?
Dale al lead un resultado concreto, los límites de archivos o funciones, los límites de riesgo y las expectativas de verificación. Por ejemplo:
```text
Improve the docs quickstart. Keep edits inside landing/product-docs, add practical examples, and run `pnpm --dir landing docs:build` before marking work done.
```
## ¿Puedo revisar el código antes de aceptarlo?
Sí. El flujo de revisión está construido en torno a diffs con alcance de tarea y decisiones a nivel de hunk.
## ¿Qué es un Agent Block?
Un Agent Block es texto oculto solo para agentes envuelto en marcadores como `<info_for_agent>...</info_for_agent>`. La aplicación lo elimina de la visualización normal orientada al usuario, pero lo mantiene disponible para la coordinación entre agentes.
## ¿Qué es el modo solo?
El modo solo es un equipo de un solo agente. Es útil para tareas más pequeñas y con menor sobrecarga de coordinación.
## ¿Debería usar el aislamiento por worktree?
Úsalo cuando varios compañeros de equipo de OpenCode puedan editar el mismo proyecto de Git en paralelo. Reduce los conflictos de archivos, pero requiere un proyecto rastreado por Git y actualmente se aplica a los miembros de OpenCode.
## ¿Pueden distintos compañeros de equipo usar distintos proveedores?
Sí, la configuración de proveedor/modelo se puede llevar por miembro del equipo cuando la ruta de runtime seleccionada lo admite. OpenCode es la ruta principal para el enrutamiento amplio entre múltiples proveedores.
## ¿Por qué una tarea muestra review o approved por separado de done?
El estado del trabajo y el estado de revisión están relacionados, pero no son idénticos. Una tarea puede estar done desde la perspectiva del agente y luego pasar por review y aprobación en la interfaz kanban.
## ¿Qué debo hacer cuando un lanzamiento se queda colgado?
Abre la solución de problemas, recopila los diagnósticos de lanzamiento, revisa `~/.claude/teams/<team>/` y verifica la autenticación del runtime/proveedor antes de cambiar los prompts.
Para OpenCode, revisa la evidencia de lane/sesión antes de suponer que un compañero de equipo está en línea pero ignora los mensajes.
## ¿Por qué los logs son diferentes entre runtimes?
Claude Code, Codex y OpenCode exponen distintos formatos de transcripción y evidencia de runtime. Agent Teams normaliza lo que puede, pero la completitud de los logs y la atribución pueden variar según el runtime.

82
landing/product-docs/es/reference/privacy-local-data.md Normal file
View file

@ -0,0 +1,82 @@
---
title: Privacidad y datos locales – Documentación de Agent Teams
description: Qué almacena Agent Teams de forma local, qué puede salir de tu equipo a través de las llamadas a modelos respaldadas por el proveedor y orientación práctica sobre privacidad.
lang: es-ES
---
# Privacidad y datos locales
Agent Teams es local-first, pero la ruta de runtime/proveedor seleccionada sigue siendo importante. Esta página describe qué almacena localmente la aplicación de escritorio y qué puede salir de tu equipo cuando los agentes llaman a modelos respaldados por el proveedor.
## Qué permanece local
La aplicación de escritorio se ejecuta en tu máquina y lee datos locales de proyecto/runtime para alimentar la interfaz. Los datos locales habituales incluyen:
- archivos de proyecto
- configuración del equipo y metadatos de los miembros
- metadatos de tareas, comentarios de tareas y referencias de tareas
- mensajes de la bandeja de entrada
- registros de runtime/sesión
- estado de lanzamiento y diagnósticos de bootstrap
- estado de la revisión
- ajustes locales de la aplicación
Las ubicaciones locales importantes incluyen:
| Plataforma | Ubicación | Propósito |
| --- | --- | --- |
| macOS/Linux | `~/.claude/teams/<team>/` | Configuración del equipo, metadatos de los miembros, bandejas de entrada, estado de lanzamiento, evidencia de bootstrap, diagnósticos de runtime, registros de mensajes enviados, estado del kanban y archivos de equipo relacionados con la revisión. |
| Windows | `%APPDATA%\Claude\teams\<team>\` | Igual: configuración del equipo, metadatos de los miembros, bandejas de entrada, estado de lanzamiento y diagnósticos. |
| macOS/Linux | `~/.claude/tasks/<team>/` | Archivos JSON de tareas duraderos para el tablero del equipo. |
| Windows | `%APPDATA%\Claude\tasks\<team>\` | Igual: archivos JSON de tareas duraderos. |
| macOS/Linux | `~/.claude/projects/<encoded-project>/` | Archivos de sesión de proyecto de tipo Claude/Codex que se usan para el historial de sesiones, el análisis de contexto y la interfaz respaldada por transcripciones. |
| Windows | `%APPDATA%\Claude\projects\<encoded-project>\` | Igual: archivos de sesión de proyecto. |
Los archivos exactos pueden variar según el runtime y la versión de la aplicación. Para depurar el lanzamiento, la evidencia más reciente suele estar en la carpeta `~/.claude/teams/<team>/` (o `%APPDATA%\Claude\teams\<team>\`) correspondiente.
## Qué puede salir de tu equipo
Agent Teams en sí no es un servicio de sincronización de código en la nube para tu repositorio. No necesita subir todo tu proyecto a un servidor de Agent Teams para mostrar el tablero, la bandeja de entrada, los registros o la interfaz de revisión.
Sin embargo, cuando un agente le pide a un modelo respaldado por el proveedor que trabaje, el contexto del prompt, el contenido de los archivos seleccionados, el texto de las tareas, los comentarios, los resultados de las herramientas, la salida de los comandos y otro contexto proporcionado por el runtime pueden enviarse a través de la ruta de runtime/proveedor seleccionada. Lo que se envía depende del runtime, el modelo, las llamadas a herramientas, el prompt y la configuración del proveedor.
La autenticación del proveedor, la retención por parte del proveedor, el entrenamiento, el registro, el procesamiento regional y la facturación se rigen por el proveedor/runtime que elijas. Revisa esas políticas para proyectos sensibles.
Ejemplos habituales:
| Acción | Datos que pueden enviarse a través del runtime/proveedor |
| --- | --- |
| Pedir a un agente que edite un archivo | El prompt de la tarea, el contenido de los archivos relevantes, los resultados de las herramientas y la salida de los comandos |
| Adjuntar una captura de pantalla | El contenido del adjunto y el texto de la tarea/comentario circundante |
| Pedir una revisión de código | El contexto del diff, los archivos seleccionados, los comentarios y los registros de verificación |
| Depurar un comando que falla | La salida de error, los stack traces y los fragmentos de código fuente referenciados |
## Qué no garantiza la aplicación
- No puede garantizar que las llamadas a modelos respaldadas por el proveedor nunca reciban código privado.
- No puede anular las políticas de retención o facturación del proveedor.
- No puede hacer que un proveedor remoto se comporte como un modelo totalmente local.
- No puede proteger secretos que se le indique a un agente pegar en prompts, comentarios de tareas, archivos o comandos.
- No puede hacer que todos los runtimes expongan la misma transcripción o el mismo nivel de detalle de auditoría.
## Orientación práctica
- No adjuntes secretos a tareas, comentarios ni mensajes directos.
- Revisa las políticas del proveedor para proyectos sensibles.
- Usa una autonomía más baja para repositorios de riesgo.
- Mantén el alcance de las tareas reducido cuando trabajes con código privado.
- Prioriza la evidencia y los registros locales al depurar.
- Comprueba los prompts generados, las descripciones de tareas y los archivos adjuntos antes de pedir a los agentes que trabajen con material confidencial.
- Usa rutas de proveedor/modelo que se ajusten a tus requisitos de privacidad.
Antes de usar Agent Teams en un repositorio sensible:
1. Elimina los secretos del árbol de trabajo y de los adjuntos de las tareas
2. Elige la ruta de runtime/proveedor que tengas permitido usar
3. Empieza con autonomía baja y tareas pequeñas
4. Revisa los prompts de las tareas y los comentarios generados antes de ampliar el alcance
5. Mantén los registros locales a menos que los compartas intencionadamente para soporte
## Modelo de código abierto
La aplicación en sí es de código abierto y gratuita. Puedes inspeccionar cómo funcionan la orquestación local, el seguimiento de tareas, las bandejas de entrada, los diagnósticos de runtime y los flujos de revisión en el repositorio.

115
landing/product-docs/es/reference/providers-runtimes.md Normal file
View file

@ -0,0 +1,115 @@
---
title: Proveedores y runtimes – Documentación de Agent Teams
description: Rutas de runtime compatibles (Claude Code, Codex, OpenCode), IDs de proveedor, nomenclatura de modelos, estrategias multiproveedor y comprobaciones de capacidades.
lang: es-ES
---
# Proveedores y runtimes
Agent Teams separa la orquestación del acceso a los modelos. La aplicación gestiona los equipos, las tareas, los mensajes, el estado de lanzamiento y la interfaz de revisión; la ruta de runtime/proveedor seleccionada realiza el trabajo real del modelo.
## Qué proporciona la aplicación
Agent Teams proporciona:
- orquestación de equipos y tareas
- interfaz del tablero kanban
- mensajería entre compañeros de equipo
- registros de tareas
- interfaz de revisión
- integración con proyectos locales
- detección del runtime y comprobaciones de capacidades
- registros y diagnósticos locales
## Qué proporciona el runtime
El runtime proporciona:
- ejecución del modelo
- autenticación del proveedor
- comportamiento de la ejecución de herramientas
- límites de tasa y capacidades específicas del modelo
- transcripciones y pruebas de entrega específicas del runtime
## Rutas de runtime compatibles
| Ruta de runtime | Ruta de proveedor/modelo | Mejor para | Notas |
| --- | --- | --- | --- |
| Claude Code | Anthropic / modelos Claude | Usuarios de Claude Code y flujos de trabajo respaldados por Anthropic | Ruta predeterminada local-first para equipos de Claude. Requiere que el runtime y el acceso a la cuenta estén disponibles localmente. |
| Codex | Codex / modelos respaldados por OpenAI | Flujos de trabajo nativos de Codex | Utiliza la integración del runtime de Codex y el estado de auth/cuenta de Codex cuando está disponible. Algunos diagnósticos difieren de las transcripciones de Claude. |
| OpenCode | Enrutamiento de modelos gestionado por OpenCode | Equipos multiproveedor y amplia cobertura de modelos | OpenCode puede enrutar a través de muchos proveedores de modelos. Agent Teams trata las lanes de OpenCode como pruebas específicas del runtime y evita hacer suposiciones cuando la identidad de la lane es ambigua. |
Gemini está disponible como ruta de proveedor compatible con autenticación mediante Google ADC (gcloud auth), OAuth de Gemini CLI y clave de API. Aparece junto a otros proveedores en la interfaz de creación de equipos y de configuración del runtime cuando el runtime lo reporta como disponible.
## IDs de proveedor
Actualmente la aplicación reconoce estos IDs de proveedor en la configuración de equipo/runtime:
| ID de proveedor | Intención de visualización |
| --- | --- |
| `anthropic` | Ruta de Anthropic / Claude Code |
| `codex` | Ruta de Codex |
| `gemini` | Ruta del proveedor Gemini (Google ADC, Gemini CLI o clave de API) |
| `opencode` | Ruta de OpenCode, incluido el enrutamiento de proveedores gestionado por OpenCode |
No interpretes esta tabla como una garantía de que todos los proveedores estén autenticados, instalados o disponibles para todos los modelos en todas las máquinas. El estado del runtime y las comprobaciones de capacidades son la fuente de verdad para un lanzamiento determinado.
## IDs de modelo
Los IDs de modelo se pasan al runtime seleccionado. Agent Teams no reescribe el catálogo de modelos de un proveedor en un esquema de nomenclatura universal.
Ejemplos:
| Ruta de proveedor | Ejemplo de ID de modelo | Notas |
| --- | --- | --- |
| Claude Code | `opus`, `sonnet`, o un ID completo de modelo Claude | La disponibilidad depende de Claude Code y del acceso a la cuenta |
| Codex | `gpt-5.4`, `gpt-5.3-codex` | La disponibilidad proviene del estado de cuenta/runtime de Codex |
| OpenCode | `openrouter/moonshotai/kimi-k2.6` | El prefijo debe coincidir con una configuración de proveedor de OpenCode |
Si un nombre de modelo es rechazado, verifícalo primero directamente en el runtime/proveedor. Cambiar el briefing de un equipo no puede hacer que se lance un modelo no disponible.
## Estrategia multiproveedor
Agent Teams mantiene la orquestación consciente del proveedor, pero no propiedad del proveedor:
- los equipos, las tareas, las bandejas de entrada, los comentarios, el estado de revisión y los diagnósticos de lanzamiento permanecen en el almacenamiento local de Agent Teams
- cada miembro puede llevar configuraciones de proveedor/modelo a través de los metadatos de lanzamiento del equipo
- la disponibilidad de modelos, la autenticación, los límites de tasa y el comportamiento de las herramientas siguen siendo responsabilidades del runtime/proveedor
- OpenCode es la ruta de enrutamiento más amplia cuando quieres que un equipo utilice varias lanes de proveedor/modelo
Para conocer los límites orientados a colaboradores y la guía canónica de implementación, consulta [Arquitectura para colaboradores](/es/reference/contributor-architecture).
Patrones recomendados:
| Patrón | Cuándo ayuda | Riesgo |
| --- | --- | --- |
| Un proveedor para todos los miembros | Primer lanzamiento, repos sensibles, depuración más sencilla | Los límites de tasa compartidos pueden detener a todo el equipo |
| Lead potente + builders más económicos | Mantener la planificación/revisión fiable mientras se reduce el coste de implementación | La salida de los builders puede requerir una revisión más estricta |
| Modelos separados para builder y reviewer | Detectar puntos ciegos específicos de cada modelo | Más configuración y atribución que inspeccionar |
## Costes del proveedor
Agent Teams es gratis y de código abierto. Puedes empezar con el modelo gratuito incluido sin autenticación: sin registro, claves de API ni tarjeta de crédito. El uso de proveedores de pago o respaldados por una cuenta se rige por el runtime/proveedor que selecciones: los límites de suscripción, las claves de API, la autenticación de la cuenta, los límites de tasa y las políticas del proveedor permanecen todos externos a la aplicación.
## Comprobaciones de capacidades
Durante la configuración, la aplicación puede realizar comprobaciones de acceso y de capacidades. Esto ayuda a detectar la falta de autenticación del runtime antes de que un lanzamiento de equipo falle a mitad del aprovisionamiento.
Las comprobaciones de capacidades pueden informar de que un proveedor existe pero no está autenticado, de que una lista de modelos no está disponible, de que falta una ruta de runtime o de que una capacidad de extensión específica no es compatible. Trata esos resultados como diagnósticos de configuración, no como fallos de tareas.
Soluciones típicas de configuración:
| Resultado de la comprobación | Qué hacer |
| --- | --- |
| Runtime ausente | Instala la CLI o corrige el `PATH` |
| Proveedor no autenticado | Ejecuta el flujo de inicio de sesión del proveedor o añade la clave de API requerida |
| Modelo no disponible | Elige un modelo visible en la lista de modelos de ese runtime |
| Capacidad no compatible | Usa otra ruta de runtime para ese compañero de equipo |
## Límites que cabe esperar
- La compatibilidad con un runtime no significa una paridad de funciones igual entre Claude Code, Codex y OpenCode.
- La cobertura de registros y transcripciones difiere según el runtime.
- Las lanes de OpenCode necesitan pruebas estables de lane/sesión antes de que la aplicación pueda atribuir los registros del runtime de forma segura.
- Los nombres de modelo de los proveedores y su disponibilidad pueden cambiar al margen de la aplicación.
- Un prompt de equipo no puede solucionar la falta de autenticación, las entradas de PATH ausentes, las interrupciones del proveedor ni los límites de tasa agotados.

42
landing/product-docs/es/reference/release-notes.md Normal file
View file

@ -0,0 +1,42 @@
---
title: Notas de la versión – Documentación de Agent Teams
description: Notas de la versión y registro de cambios de Agent Teams. Enlaces a los archivos canónicos RELEASE.md y CHANGELOG.md con todos los detalles.
lang: es-ES
---
# Notas de la versión
Versión actual: **v1.2.0** (2026-03-31). El desarrollo activo continúa en la rama `main` con cambios sin publicar para la sincronización del trabajo de los miembros, el endurecimiento de la entrega en OpenCode y la estabilización de la CI.
## Cómo funcionan las versiones
Agent Teams sigue el [versionado semántico](https://semver.org/). Las etiquetas enviadas al repositorio activan un [flujo de trabajo de publicación](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) automatizado que compila paquetes firmados para macOS, Windows y Linux, y luego los publica en GitHub Releases.
## Versiones recientes
### v1.2.0 — Agent Graph, aprobación de herramientas por equipo, AskUserQuestion interactivo
Agent Graph con visualización dirigida por fuerzas y disposición de tareas en kanban, controles de aprobación de herramientas por equipo con prompts de permisos legibles, notificaciones de comentarios en las tareas y botones interactivos de AskUserQuestion. Renovación del sistema de permisos con la inicialización de Write/Edit/NotebookEdit e integración del catálogo de herramientas de MCP. Consulta el [registro de cambios completo](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#120---2026-03-31).
### v1.1.0 — React 19 + Electron 40, inicios de tareas iniciados por el usuario
Migración a React 19 + Electron 40, inicios de tareas iniciados por el usuario desde el tablero kanban, guía de solución de problemas de autenticación, resaltado de sintaxis para R/Ruby/PHP/SQL, búsqueda de transcripciones 3 veces más rápida, correcciones de rutas en WSL/Windows y corrección de una vulnerabilidad XSS. Consulta el [registro de cambios completo](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#110---2026-03-25).
### v1.0.0 — Primera versión pública
Primera compilación estable: fiabilidad de CLI/autenticación en las aplicaciones empaquetadas, endurecimiento de IPC, empaquetado multiplataforma con compilaciones firmadas para macOS, documentos de gobernanza de código abierto (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY). Consulta el [registro de cambios completo](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#100---2026-03-23).
## Fuentes canónicas
| Documento | Descripción |
| --- | --- |
| [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) | Proceso de publicación, guía de versionado, nomenclatura de los artefactos, configuración de la actualización automática y plantilla de notas de la versión. |
| [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) | Registro de cambios completo con todas las versiones, funciones, mejoras y correcciones de errores desde la perspectiva del usuario. |
| [GitHub Releases](https://github.com/777genius/agent-teams-ai/releases) | Instaladores descargables para todas las plataformas. |
## Páginas relacionadas
- [Instalación](/es/guide/installation)
- [Inicio rápido](/es/guide/quickstart)
- [Arquitectura para colaboradores](/es/reference/contributor-architecture)
- [Desarrolladores](/es/developers/)

69
landing/product-docs/fr/developers/index.md Normal file
View file

@ -0,0 +1,69 @@
---
title: Hub développeur – Documentation Agent Teams
description: Point d'entrée pour les contributeurs et les développeurs sur l'architecture d'Agent Teams, les garde-fous, le débogage et les chemins d'extension MCP.
lang: fr-FR
---
# Hub développeur
Utilisez cette page lorsque vous souhaitez modifier Agent Teams lui-même, déboguer un lancement d'équipe ou étendre un runtime avec des outils MCP. Les liens ci-dessous pointent vers les documents canoniques du dépôt afin que les règles d'implémentation restent centralisées.
## Commencez ici
| Besoin | Aller à |
| --- | --- |
| Vue d'ensemble du dépôt, scripts et configuration des sources | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) |
| Index de navigation et d'architecture pour les agents | [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) |
| Conventions de travail pour les agents et les contributeurs | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) |
| Garde-fous d'implémentation stricts | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) |
| Structure des fonctionnalités moyennes et grandes | [Standard d'architecture des fonctionnalités](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) |
| Débogage du lancement, du bootstrap et de la messagerie des coéquipiers | [Runbook de débogage des équipes d'agents](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) |
| Processus de contribution | [Guide de contribution](https://github.com/777genius/agent-teams-ai/blob/main/.github/CONTRIBUTING.md) |
| Notes de version / Changelog | [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) — [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) |
## Chemin de développement local
Lancez l'application de bureau Electron pour un développement normal :
```bash
pnpm install
pnpm dev
```
Le chemin navigateur/web ne remplace pas le runtime de bureau. Le mode bureau est le chemin local pris en charge, car il inclut l'IPC, les terminaux, l'authentification des fournisseurs, la gestion du cycle de vie des équipes, les diagnostics de lancement et les ponts runtime utilisés par les véritables équipes.
## Points de contrôle de l'architecture
Avant de modifier une fonctionnalité, identifiez sa frontière :
| Domaine | Emplacement attendu |
| --- | --- |
| Fonctionnalité produit moyenne ou grande | `src/features/<feature-name>/` |
| Orchestration du processus principal Electron | `src/main/` |
| Surface d'API sûre pour le preload | `src/preload/` |
| Interface du renderer et état de l'application | `src/renderer/` |
| Types partagés et helpers purs | `src/shared/` |
| Serveur MCP du tableau Agent Teams | `mcp-server/` |
| Contrôleur de données du tableau | `agent-teams-controller/` |
Utilisez `src/features/recent-projects` comme slice de référence pour l'organisation des fonctionnalités. Gardez les contrats inter-processus explicites et évitez les imports profonds au travers des frontières de fonctionnalités.
## Chemin de débogage
Pour les blocages au lancement, les états OpenCode `registered` / bootstrap non confirmé, les réponses de coéquipiers manquantes ou les journaux de tâches suspects :
1. Commencez par le [runbook de débogage](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md).
2. Inspectez le pack d'artefacts le plus récent sous `~/.claude/teams/<team>/launch-failure-artifacts/latest.json`.
3. Ouvrez l'artefact `manifest.json` et vérifiez `classification`, les fils d'Ariane du bootstrap, les diagnostics de lancement, les statuts de spawn des membres et les fins de journaux expurgées.
4. Ne nettoyez que l'équipe, l'exécution, le panneau ou le processus que vous pouvez identifier comme appartenant au smoke test ou au lancement échoué.
## Chemin de développement MCP
Agent Teams utilise un serveur MCP intégré nommé `agent-teams` pour les opérations du tableau. Les serveurs MCP utilisateur et projet peuvent ajouter des capacités externes pour les runtimes. Consultez [Intégration MCP](/fr/guide/mcp-integration) pour des exemples de configuration, la structure de `.mcp.json` et des conseils sur l'enregistrement des outils.
## Docs associées
- [Architecture pour les contributeurs](/fr/reference/contributor-architecture)
- [Configuration du runtime](/fr/guide/runtime-setup)
- [Intégration MCP](/fr/guide/mcp-integration)
- [Dépannage](/fr/guide/troubleshooting)

121
landing/product-docs/fr/guide/agent-workflow.md Normal file
View file

@ -0,0 +1,121 @@
---
title: Flux de travail des agents – Documentation Agent Teams
description: Comprenez le cycle de vie des tâches, le tableau kanban, les messages, les journaux de tâches, le travail en parallèle, les processus en direct et la communication inter-équipes.
lang: fr-FR
---
# Flux de travail des agents
Agent Teams rend le travail des agents visible sous forme d'état de tâche, de messages, de journaux et de modifications de code révisables.
## Modes
| Mode | Description |
| --- | --- |
| Solo | Un coéquipier avec des tâches auto-gérées |
| Équipe | Plusieurs coéquipiers travaillant en parallèle et se révisant mutuellement |
Les deux modes partagent les mêmes surfaces de kanban, de journaux de tâches et de revue de code.
## Cycle de vie des tâches
Agent Teams suit chaque tâche selon deux dimensions indépendantes : le statut de travail et l'état de revue.
| Dimension | États | Description |
| --- | --- | --- |
| Statut de travail | `pending`, `in_progress`, `completed` | Indique si la tâche est en attente, activement en cours de traitement ou terminée par son propriétaire |
| État de revue | `none`, `review`, `needsFix`, `approved` | Indique où en est la tâche dans le flux de revue post-achèvement |
Le tableau kanban affiche la vue combinée, mais les deux dimensions évoluent indépendamment.
### Flux du statut de travail
| Étape | Ce qui se passe | Propriétaire |
| --- | --- | --- |
| Pending | La tâche est créée et prête, mais personne n'a encore commencé le travail | Lead ou utilisateur |
| In progress | Les agents travaillent et mettent à jour l'état de la tâche via les outils MCP du tableau | Coéquipiers |
| Completed | Le propriétaire publie un commentaire de résultat et marque la tâche comme terminée | Coéquipier |
### Flux de l'état de revue
| Étape | Ce qui se passe | Propriétaire |
| --- | --- | --- |
| None | La tâche n'est pas encore en revue (elle peut être pending, in progress ou récemment completed) | — |
| Review | Une revue a été demandée ; un relecteur inspecte le diff et le résultat | Relecteur |
| Needs fix | Des modifications ont été demandées lors de la revue ; le propriétaire doit mettre à jour | Coéquipier (propriétaire) |
| Approved | La revue a réussi ; la tâche est finalisée | Relecteur |
### Planification → In progress
Lorsqu'un coéquipier démarre une tâche, le statut de travail passe à `in_progress`. L'agent crée un commentaire de tâche avec son plan et poursuit le travail. Toutes les actions des outils natifs (read, bash, edit, write) sont diffusées dans un journal de tâche.
### Completed → Review
Lorsque le coéquipier termine son travail, il publie un commentaire de résultat et fait passer le statut de travail à `completed`. Le lead ou le relecteur peut alors demander une revue pour lancer le flux de revue.
### Review → Approved
Si la surface de revue affiche des modifications acceptables, approuvez la revue. La tâche est finalisée et liée à son diff.
::: warning Revue par correction d'abord
Si l'on demande des modifications à un coéquipier lors de la revue, il doit publier un commentaire de suivi avec les corrections, puis le lead peut approuver.
:::
## Tableau kanban
Le tableau est la principale surface d'exploitation. Il vous permet de :
- Parcourir le travail ouvert, bloqué et en revue
- Ouvrir le détail d'une tâche et inspecter les journaux d'exécution
- Réviser les modifications sans lire les fichiers de session bruts
- Attribuer ou réattribuer des propriétaires
::: tip
Utilisez les boutons d'action rapide sur les cartes pour démarrer, terminer ou demander une revue sans ouvrir le panneau de détail.
:::
## Messages et commentaires
| Canal | Quand l'utiliser |
| --- | --- |
| Message direct | Rediriger un agent, poser une question rapide |
| Commentaire de tâche | Notes appartenant à une tâche spécifique |
Les commentaires conservent le contexte pour une revue ultérieure et apparaissent dans la chronologie de la tâche.
::: tip Préférez les commentaires de tâche
Si la remarque concerne une tâche spécifique, ajoutez-la en commentaire sur cette tâche plutôt que d'envoyer un message direct. Cela garde l'historique lié au travail.
:::
## Journaux de tâches
Les journaux propres à une tâche isolent la sortie d'exécution, les actions et les messages d'une seule affectation. Utilisez-les pour répondre à :
- Qu'a exécuté cet agent ?
- Pourquoi a-t-il modifié ce fichier ?
- A-t-il demandé de l'aide à un autre coéquipier ?
- Quelle tâche a produit ce diff ?
### Liste de vérification
Lorsqu'une tâche semble bloquée ou que son diff paraît détaché, vérifiez le cycle de vie dans cet ordre :
1. La tâche a le propriétaire attendu et est passée à `in_progress`.
2. Le propriétaire a publié un commentaire de tâche avec le plan ou la première mise à jour d'avancement.
3. Les journaux de tâche montrent une activité d'exécution dans la fenêtre de la tâche.
4. Les modifications de fichiers sont liées à la même tâche, au même propriétaire et à la même session.
5. Le commentaire final de la tâche inclut la commande de vérification et son résultat.
Pour un débogage plus poussé, utilisez les commandes de preuve persistée dans [Dépannage](/fr/guide/troubleshooting#task-log-triage). L'interface est la surface de travail, mais les fichiers de tâches persistés, les boîtes de réception et les preuves d'exécution sont la source pour les bugs difficiles de lancement ou d'attribution.
## Modèles de travail en parallèle
Les coéquipiers peuvent travailler simultanément sur des tâches indépendantes. Vous pouvez également créer des liens de dépendance (`blocked-by`) pour qu'une tâche attende qu'une autre soit terminée. Surveillez le tableau pour repérer les voies bloquées et réattribuez les propriétaires si un coéquipier est inactif tandis qu'un autre est surchargé.
## Processus en direct
La section des processus en direct affiche les URL et les processus en cours d'exécution lorsque les agents démarrent des serveurs ou des outils locaux. Ouvrez les URL directement depuis l'application pour inspecter les résultats. Les processus restent enregistrés jusqu'à ce qu'ils soient explicitement arrêtés ou que le runtime se ferme.
## Communication inter-équipes
Les agents peuvent envoyer des messages à d'autres équipes lorsque les équipes sont liées. Utilisez cela pour les transferts, les bibliothèques partagées ou les vérifications de statut entre escouades.

119
landing/product-docs/fr/guide/code-review.md Normal file
View file

@ -0,0 +1,119 @@
---
title: Revue de code – Documentation Agent Teams
description: Inspectez les diffs liés aux tâches, acceptez ou rejetez des hunks, laissez des commentaires en ligne et gérez les états de revue, de none jusqu'à approved.
lang: fr-FR
---
# Revue de code
La revue de code dans Agent Teams est centrée sur les tâches. Vous inspectez ce qui a changé pour une tâche précise au lieu de fouiller dans un diff volumineux et non structuré.
## Surface de revue
Pour chaque tâche terminée qui a modifié des fichiers, l'interface de revue vous permet de :
- Inspecter les fichiers modifiés avec le contexte avant/après
- Accepter ou rejeter des hunks individuels
- Laisser des commentaires en ligne
- Relier le diff à la description de la tâche et aux journaux de l'agent
## Décisions au niveau du hunk
Acceptez les petites modifications correctes et rejetez les erreurs isolées sans jeter toute la tâche. C'est utile lorsqu'un agent a globalement résolu la tâche mais est allé trop loin dans un fichier.
::: tip Accepter de façon incrémentale
Si un diff est globalement correct, acceptez d'abord les bons hunks et demandez des modifications uniquement pour les parties à corriger. Cela permet de garder le tableau en mouvement.
:::
Utilisez les décisions au niveau du hunk pour :
| Situation | Action |
| --- | --- |
| Modification correcte et ciblée | Accepter le hunk |
| Bonne idée, mauvais fichier ou refactor trop large | Rejeter le hunk et demander une correction plus ciblée |
| Changement de comportement peu clair | Commenter et demander une vérification |
| Bruit de formatage généré | Rejeter sauf si le formatage faisait partie de la tâche |
## Lancer une revue
1. Ouvrez une tâche terminée
2. Regardez l'onglet **Changes**
3. Si le diff semble raisonnable, cliquez sur **Request Review** pour déplacer la tâche dans la colonne review
Pendant la revue, la tâche n'est pas encore considérée comme done, de sorte que d'autres coéquipiers ou le lead peuvent encore la commenter.
## Boucle de revue
Une boucle de revue saine ressemble à ceci :
1. Le propriétaire publie un commentaire de résultat avec le périmètre modifié et la vérification
2. Le relecteur ouvre le diff de la tâche et confronte les hunks à la description de la tâche
3. Le relecteur accepte les bons hunks, rejette les mauvais hunks ou demande des modifications
4. Le propriétaire corrige uniquement le périmètre demandé et publie un commentaire de suivi
5. Le relecteur approuve lorsque le résultat de la tâche et le diff correspondent
Exemple de commentaire de demande de modifications :
```text
Please keep the copy improvements, but revert the unrelated runtime wording in the provider table. Add the `pnpm --dir landing docs:build` result before resubmitting.
```
## États de revue
| État | Signification |
| --- | --- |
| `none` | La tâche est nouvelle, in progress, ou terminée mais pas encore en revue |
| `review` | La tâche est activement en cours de revue |
| `needsFix` | Des modifications ont été demandées ; le propriétaire doit mettre à jour avant une nouvelle approbation |
| `approved` | La revue a été acceptée et la tâche est finalisée |
## Flux de revue par les agents
Les équipes peuvent relire le travail des unes et des autres avant que vous ne preniez la décision finale. Cela permet de détecter les régressions évidentes et de garder le tableau honnête, mais vous devriez tout de même relire vous-même les zones à risque.
La revue par les agents est la plus utile lorsque le relecteur dispose d'une grille claire. Par exemple, demandez à un relecteur de vérifier uniquement la clarté de la documentation, uniquement la sécurité de l'IPC ou uniquement la couverture de tests. Les demandes larges de type « tout relire » tendent à produire des retours plus faibles.
### État de revue piloté par MCP
Les changements d'état de revue (request review, request changes, approve) sont pilotés par des outils. Laisser un commentaire « request changes » sur une tâche ne déplace **pas** la colonne kanban vers `needsFix` — un lead ou un agent doit appeler l'outil MCP approprié :
- `review_request_changes` — déplace la tâche vers `needsFix` et notifie le propriétaire
- `review_approve` — déplace la tâche vers `approved` et finalise la revue
Les commentaires seuls ne suffisent pas pour les transitions d'état. Pour la liste complète des outils MCP de revue et leurs paramètres, voir [Intégration MCP](/fr/guide/mcp-integration).
## Participants à la revue
Le lead de l'équipe est le relecteur par défaut. Vous pouvez configurer des relecteurs supplémentaires dans les paramètres du Kanban si vous souhaitez que des pairs relisent le travail des unes et des autres.
## Ce qu'il faut vérifier manuellement
Priorisez ces domaines lors de la revue :
- **Authentification des fournisseurs et détection du runtime** — l'agent a-t-il modifié la configuration du runtime d'une manière qui casserait d'autres chemins ?
- **IPC, preload et frontières du système de fichiers** — gardez les responsabilités d'Electron séparées
- **Comportement Git et worktree** - vérifiez le nommage des branches, les commits et les pushes ; voir [Stratégie Git et worktree](/fr/guide/git-worktree-strategy) pour les patterns d'isolation.
- **Logique de parsing et de cycle de vie des tâches** — les modifications des références de tâches, du chunking ou du filtrage peuvent casser la livraison des messages
- **Flux de persistance et de revue de code** — les modifications du stockage des tâches ou de l'état de revue doivent rester cohérentes entre les couches IPC
Pour la disposition canonique des fonctionnalités et les liens des garde-fous stricts, utilisez [Architecture pour les contributeurs](/fr/reference/contributor-architecture).
## Vérification
Préférez des commandes de vérification ciblées. Les commandes de formatage large ou de lint-fix ne devraient pas être utilisées sauf si la tâche vise explicitement un brassage de formatage à grande échelle.
Les bons commentaires de vérification incluent la commande et le résultat :
```text
Verified with `pnpm --dir landing docs:build`. Build passed.
```
Lorsque la vérification est omise, le commentaire de tâche devrait en expliquer la raison :
```text
Docs-only wording change. Build not run because the existing dev server was busy; checked Markdown links manually.
```
::: warning Ne pas formater automatiquement tout le projet
Sauf si la tâche concerne spécifiquement le formatage, évitez d'exécuter `pnpm lint:fix` sur des fichiers sans rapport. Cela crée du bruit dans la surface de revue.
:::

106
landing/product-docs/fr/guide/create-team.md Normal file
View file

@ -0,0 +1,106 @@
---
title: Créer une équipe – Documentation Agent Teams
description: Définissez les rôles, attribuez des fournisseurs et des modèles, rédigez un brief d'équipe et configurez l'isolation par worktree ainsi que les niveaux d'autonomie.
lang: fr-FR
---
# Créer une équipe
Une équipe est un groupe nommé d'agents doté de rôles, d'un lead, d'un projet cible et d'un prompt de coordination.
## Première équipe recommandée
Commencez par une petite équipe :
| Rôle | Objectif |
| -------- | --------------------------------------------------------- |
| Lead | Répartit le travail, crée les tâches, coordonne l'équipe |
| Builder | Implémente des tâches au périmètre défini |
| Reviewer | Examine les résultats, repère les régressions, demande des correctifs |
Cette configuration vous donne assez de coordination pour percevoir la valeur du produit sans rendre le premier lancement trop bruyant.
::: tip
Vous pourrez ajouter d'autres membres plus tard. Commencez petit, validez le flux de travail, puis montez en puissance.
:::
## Attribuer des fournisseurs et des modèles
Chaque membre de l'équipe s'exécute sur un backend fournisseur. Dans l'éditeur d'équipe, choisissez un fournisseur (Claude, Codex ou OpenCode) et un modèle pour chaque membre. L'application n'affiche que les fournisseurs que vous avez déjà authentifiés.
Le mélange de fournisseurs au sein d'une même équipe est pris en charge — par exemple, un lead Claude avec des builders OpenCode.
::: info
Gemini est disponible comme parcours fournisseur pris en charge. Consultez [Fournisseurs et runtimes](/fr/reference/providers-runtimes) pour les options d'authentification et le statut actuel des fournisseurs.
:::
## Rédiger un bon brief d'équipe
Le brief d'équipe doit inclure :
- le résultat que vous souhaitez
- les fichiers ou les domaines fonctionnels qui comptent
- les limites de risque, par exemple « ne pas refactoriser des modules sans rapport »
- les attentes en matière de revue
- les commandes de vérification lorsque vous les connaissez
Exemple :
```text
Build a focused improvement to the download flow. Keep changes inside the landing app unless a shared helper is clearly needed. Create tasks before implementation, review each task diff, and run landing lint/build checks.
```
## Isolation par worktree
Les membres OpenCode peuvent utiliser l'**isolation par worktree** pour travailler dans un worktree Git distinct plutôt que dans le répertoire de travail principal. Cela évite les conflits de fichiers lorsque plusieurs agents modifient le même projet.
::: warning
L'isolation par worktree nécessite un projet suivi par Git et est actuellement limitée aux membres OpenCode.
:::
Pour l'activer, basculez l'option **Worktree isolation** lors de l'ajout ou de la modification d'un membre d'équipe OpenCode.
## Choisir l'autonomie
Agent Teams prend en charge différents niveaux de contrôle. Utilisez davantage d'autonomie pour les modifications de routine et une revue plus stricte pour les zones à risque comme l'authentification des fournisseurs, l'IPC, la persistance, les workflows Git et l'outillage de release.
### Niveau d'effort
Chaque membre de l'équipe dispose d'un paramètre d'**effort** qui contrôle la quantité de raisonnement que le fournisseur investit avant de répondre. Un effort plus élevé produit des résultats plus approfondis au prix de plus de temps et de tokens.
| Niveau | Quand l'utiliser |
| ------- | ------------------------------------------------------------- |
| Low | Recherches rapides, petites modifications de mise en forme, retouches de routine |
| Medium | Valeur par défaut pour la plupart des tâches d'implémentation |
| High | Refactorisations complexes, changements transversaux, chemins de code à risque |
L'application propose des niveaux supplémentaires (minimal, xhigh, max) pour les fournisseurs qui les prennent en charge. Si un modèle ne prend pas en charge l'effort configurable, le sélecteur est désactivé et la valeur par défaut du fournisseur est utilisée.
### Mode rapide
Basculez le **Fast mode** par membre pour privilégier la vitesse à la profondeur. Cela correspond au mode rapide/vitesse natif du fournisseur lorsqu'il est disponible. Réglez-le sur **On** pour les tâches de routine, sur **Off** pour le travail minutieux, ou sur **Inherit** pour suivre la valeur par défaut au niveau de l'équipe.
### Limiter le contexte
Activez **Limit context** pour réduire la fenêtre de contexte d'un membre. C'est utile pour les modèles Claude qui prennent en charge un contexte étendu (par exemple 1M de tokens) — limiter le contexte évite une consommation inutile de tokens et peut améliorer la latence des tâches qui n'ont pas besoin d'un large contexte.
## Ajouter du contexte
Joignez des fichiers, des captures d'écran ou des notes spécifiques lorsqu'ils modifient sensiblement la tâche. Les agents peuvent utiliser les descriptions de tâches, les commentaires et les pièces jointes comme contexte durable.
## Veiller à la qualité des tâches
Les bonnes équipes créent des tâches qui sont :
- assez spécifiques pour être examinées
- assez petites pour être terminées
- liées à un résultat visible
- adossées à un chemin de vérification
Si le lead crée des tâches vagues, envoyez-lui un message direct pour demander des tâches plus petites et testables.
## Étapes suivantes
- [Configuration du runtime](/fr/guide/runtime-setup) — configurez l'authentification des fournisseurs et les modèles
- [Revue de code](/fr/guide/code-review) — acceptez, rejetez ou commentez les modifications des agents
- [Dépannage](/fr/guide/troubleshooting) — problèmes courants et solutions

102
landing/product-docs/fr/guide/git-worktree-strategy.md Normal file
View file

@ -0,0 +1,102 @@
---
title: Stratégie Git et worktree – Documentation Agent Teams
description: Déterminez quand utiliser le worktree principal, les branches de fonctionnalité ou l'isolation par worktree d'OpenCode pour le travail d'agents en parallèle.
lang: fr-FR
---
# Stratégie Git et worktree
Git offre à Agent Teams le meilleur parcours de revue : des diffs ciblés, une visibilité des branches, des modifications délimitées par tâche et un travail parallèle plus sûr.
## Choisir une stratégie
| Stratégie | À utiliser quand | Compromis |
| --- | --- | --- |
| Worktree principal | Travail en solo, modifications de documentation uniquement, ou un seul coéquipier à la fois | Simple, mais les modifications parallèles peuvent entrer en collision |
| Branche de fonctionnalité | Une équipe travaille sur une modification cohérente unique | Cible de revue propre, mais les coéquipiers partagent toujours les fichiers |
| Isolation par worktree | Plusieurs coéquipiers OpenCode peuvent modifier le même dépôt en parallèle | Meilleure isolation, mais la fusion/revue demande plus de discipline |
Commencez simple. Ajoutez l'isolation par worktree lorsque des modifications parallèles sont probables, et non parce que chaque tâche nécessiterait un checkout distinct.
## Quand activer l'isolation par worktree
Activez-la pour les coéquipiers OpenCode quand :
- deux coéquipiers ou plus peuvent modifier le même dépôt en même temps
- une tâche peut exécuter des formateurs, des générateurs de code ou des tests étendus
- vous souhaitez que la branche et le diff de chaque coéquipier restent séparés
- l'espace de travail du lead est sale et ne devrait pas recevoir de modifications directes
Laissez-la désactivée quand :
- la tâche est en lecture seule
- un seul coéquipier détient toutes les modifications
- le dépôt n'est pas suivi par Git
- vous avez besoin d'un chemin de runtime qui ne prend pas en charge ce mode d'isolation
::: warning
L'isolation par worktree s'applique actuellement aux membres OpenCode et nécessite un projet suivi par Git.
:::
## Hygiène des branches
Avant de démarrer un travail en parallèle :
```bash
git status --short
git branch --show-current
```
Utilisez une branche propre lorsque c'est possible. Si le worktree principal contient déjà des modifications de l'utilisateur, demandez aux agents de ne pas annuler les fichiers sans rapport et de garder un périmètre de tâche étroit.
Style de branche recommandé :
```text
agent/<team-or-task>/<short-purpose>
```
Exemples :
```text
agent/docs/mcp-guide
agent/review/task-log-filtering
agent/ui/code-review-polish
```
## Flux de revue
Pour les worktrees isolés, examinez le diff du coéquipier avant de fusionner ou d'appliquer les modifications dans l'espace de travail principal.
1. Vérifiez que le commentaire de résultat de la tâche nomme le périmètre modifié et la vérification.
2. Inspectez le diff de la tâche dans l'interface de revue.
3. Demandez des modifications sur la tâche si le diff touche des fichiers sans rapport.
4. Approuvez uniquement après que les tests ou les vérifications manuelles correspondent au risque de la tâche.
5. Fusionnez ou appliquez les modifications délibérément.
Ne fusionnez pas automatiquement la sortie d'un worktree juste parce que la tâche est terminée. L'achèvement signifie que l'agent estime que le travail est prêt pour la revue.
## Politique de conflits
Utilisez cette politique pour les équipes en parallèle :
| Situation | Action |
| --- | --- |
| Deux coéquipiers modifient le même fichier | Mettez une tâche en pause ou désignez un responsable unique de l'intégration |
| Des fichiers générés ont été modifiés de manière étendue | Exigez un commentaire expliquant le générateur et la commande |
| Le worktree principal contient des modifications sans rapport | Préservez-les et n'examinez que les modifications propres à la tâche |
| La branche du worktree diverge | Rebasez ou fusionnez manuellement après la revue, pas dans une tâche d'agent floue |
## Exemple de prompt de tâche
```text
Implement the settings validation fix in your assigned worktree. Keep edits inside src/features/settings and focused tests. Do not touch provider auth or task storage. Post the test command and result before completing the task.
```
Ce prompt fonctionne parce qu'il nomme la zone autorisée, les frontières sensibles et la preuve d'achèvement.
## Guides associés
- [Créer une équipe](/fr/guide/create-team)
- [Revue de code](/fr/guide/code-review)
- [Exemples de briefs d'équipe](/fr/guide/team-brief-examples)
- [Configuration du runtime](/fr/guide/runtime-setup)

129
landing/product-docs/fr/guide/installation.md Normal file
View file

@ -0,0 +1,129 @@
---
title: Installation – Documentation Agent Teams
description: Téléchargez et installez Agent Teams pour macOS, Windows ou Linux. Couvre les builds packagés, la configuration depuis les sources, les mises à jour automatiques et les prérequis.
lang: fr-FR
---
# Installation
Agent Teams est distribué sous forme d'application de bureau pour macOS, Windows et Linux.
::: tip Chemin le plus court
1. Téléchargez le build correspondant à votre plateforme ci-dessous
2. Lancez l'application - commencez avec le modèle gratuit sans authentification ou connectez l'authentification d'un fournisseur depuis l'interface
3. Lancez le [démarrage rapide](/fr/guide/quickstart) pour créer votre première équipe
Démarrage de l'application de bureau : exécutez `pnpm dev` pour l'application Electron. Ne lancez pas le mode dev navigateur/web pour un usage normal.
:::
## Télécharger les builds
Utilisez la <a href="/fr/download/" target="_self">page de téléchargement</a> ou la dernière [version GitHub](https://github.com/777genius/agent-teams-ai/releases) lorsque vous souhaitez l'application packagée :
- macOS Apple Silicon : `.dmg`
- macOS Intel : `.dmg`
- Windows : `.exe`
- Linux : `.AppImage`, `.deb`, `.rpm` ou `.pacman`
::: warning Windows SmartScreen
Les applications open source non signées ou récemment publiées peuvent déclencher SmartScreen. Si vous faites confiance à la source de la version, choisissez **More info** puis **Run anyway**.
:::
## Prérequis
L'application packagée est conçue pour une intégration sans configuration. Vous pouvez commencer avec le modèle gratuit sans authentification - sans inscription, sans clés API ni carte de crédit. Si vous souhaitez davantage de modèles, l'application vous guide pour la détection du runtime et l'authentification des fournisseurs depuis l'interface.
Pour les modèles payants ou liés à un compte, connectez au moins un fournisseur :
| Fournisseur | Méthode d'accès |
| ------------------ | ------------------------------------------------- |
| Claude (Anthropic) | Connexion à la CLI Claude Code ou clé API |
| Codex (OpenAI) | Connexion à la CLI Codex ou clé API |
| Gemini (Google) | Google ADC, CLI Gemini ou clé API |
| OpenCode | Modèle gratuit inclus sans authentification, ou clé API pour un backend pris en charge (par ex. OpenRouter) |
::: info
Gemini est disponible comme chemin de fournisseur pris en charge. Consultez [Fournisseurs et runtimes](/fr/reference/providers-runtimes) pour les options d'authentification et l'état actuel de tous les fournisseurs.
:::
Pour le développement depuis les sources, vous avez également besoin de :
| Outil | Version |
| ------- | ------- |
| Node.js | 24.16.0 LTS |
| pnpm | 10+ |
Sur macOS, les binaires précompilés officiels de Node.js 24 nécessitent macOS 13.5 ou ultérieur.
## Exécuter depuis les sources
<InstallBlock command="git clone https://github.com/777genius/agent-teams-ai.git && cd agent-teams-ai && pnpm install && pnpm dev" label="Copier" copied-label="Copié" />
```bash
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
pnpm dev
```
`pnpm dev` démarre l'application de bureau Electron avec rechargement à chaud. C'est la cible de développement par défaut — ne lancez pas de serveur de dev web dans le navigateur pour le développement normal. Le chemin navigateur ne dispose pas de l'ensemble du comportement de bureau : IPC, terminal, authentification des fournisseurs et cycle de vie des équipes.
La branche `main` contient le dernier développement stable. Passez à des branches de fonctionnalités uniquement si vous avez besoin d'un changement spécifique non encore publié.
## Vérifier la configuration
Après l'installation, confirmez que le build est sain :
```bash
# Check that the desktop app compiles and starts
pnpm typecheck
# Verify the VitePress documentation site builds
pnpm --dir landing docs:build
```
Si `pnpm typecheck` signale des erreurs de type, vérifiez s'il existe une version plus récente des dépendances ou un TypeScript épinglé. Si `pnpm --dir landing docs:build` échoue, inspectez `landing/product-docs/` pour détecter des erreurs de syntaxe dans le markdown ou la configuration.
Si vous modifiez cette documentation, exécutez le build pour vérifier vos changements :
```bash
pnpm --dir landing docs:build
```
## Mises à jour automatiques
L'application packagée recherche des mises à jour automatiquement au démarrage et périodiquement pendant son exécution. Lorsqu'une mise à jour est disponible, l'application vous invite à la télécharger et à l'installer. Vous pouvez également vérifier manuellement depuis le menu de l'application.
::: tip
Les mises à jour automatiques ne sont pas disponibles lors de l'exécution depuis les sources. Récupérez les dernières modifications et relancez `pnpm install` lorsque les dépendances changent.
:::
## Mettre à jour depuis les sources
Si vous exécutez depuis les sources, récupérez la branche `main` et relancez l'installation lorsque les dépendances changent :
```bash
git pull
pnpm install
```
Après la mise à jour, vérifiez le build et la documentation :
```bash
pnpm typecheck
pnpm --dir landing docs:build
```
Utilisez toujours `pnpm dev` (Electron) — et non le serveur de dev navigateur — pour le développement normal.
## Étapes suivantes
- [Démarrage rapide](/fr/guide/quickstart) — de l'installation à la première équipe en cours d'exécution
- [Configuration du runtime](/fr/guide/runtime-setup) — authentification des fournisseurs et sélection du modèle par runtime
- [Créer une équipe](/fr/guide/create-team) — formes d'équipe recommandées et rédaction du brief
### Pour les contributeurs
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — navigation dans le dépôt et repères d'architecture
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — conventions de travail et règles du projet
- [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) — garde-fous stricts d'implémentation

225
landing/product-docs/fr/guide/mcp-integration.md Normal file
View file

@ -0,0 +1,225 @@
---
title: Intégration MCP – Documentation Agent Teams
description: Configurez MCP dans Agent Teams pour les opérations sur le tableau, la coordination des coéquipiers, les serveurs d'outils externes et le développement d'outils personnalisés.
lang: fr-FR
---
# Intégration MCP
Agent Teams utilise MCP dans deux couches pratiques :
| Couche | Ce qu'elle fait | Qui l'utilise |
| --- | --- | --- |
| Serveur de tableau intégré | Expose les outils Agent Teams de tâche, message, revue, processus, runtime et inter-équipes | Les leads et les coéquipiers lancés par l'application |
| Serveurs MCP externes | Ajoutent des outils optionnels comme l'automatisation de navigateur, le contexte de conception, la recherche dans la documentation ou les systèmes d'entreprise | Les utilisateurs et les runtimes configurés |
Gardez ces couches séparées. Le serveur MCP intégré `agent-teams` est la manière dont les agents se coordonnent à l'intérieur d'Agent Teams. Les serveurs MCP externes sont des outils de runtime optionnels.
## Comment Agent Teams injecte MCP
Lorsque l'application de bureau lance des membres d'équipe basés sur Claude, elle écrit un fichier JSON `--mcp-config` temporaire contenant le serveur intégré `agent-teams` :
```json
{
"mcpServers": {
"agent-teams": {
"command": "node",
"args": ["/path/to/agent-teams-mcp/index.js"],
"env": {
"AGENT_TEAMS_MCP_CLAUDE_DIR": "/Users/you/.claude"
}
}
}
}
```
En développement, la commande peut pointer vers `mcp-server/src/index.ts` via `tsx`. Dans les builds empaquetés, l'application copie le serveur MCP fourni vers un chemin de données applicatives stable et l'exécute avec Node. Le fichier généré appartient à l'application et est nettoyé au mieux.
Les serveurs MCP utilisateur et projet restent séparés. L'application lit les serveurs installés depuis :
| Portée | Emplacement |
| --- | --- |
| Utilisateur | `~/.claude.json` sous `mcpServers` |
| Entrée de projet locale dans la configuration Claude | `~/.claude.json` sous `projects[projectPath].mcpServers` |
| Projet | `<project>/.mcp.json` sous `mcpServers` |
Préférez la portée projet pour les outils qui appartiennent à un seul dépôt. Préférez la portée utilisateur pour les outils que vous réutilisez dans des projets sans rapport.
## Exemple de `.mcp.json` de projet
Placez ce fichier à la racine du projet lorsqu'une équipe doit voir le même serveur à portée de projet :
```json
{
"mcpServers": {
"docs-search": {
"command": "npx",
"args": ["-y", "@acme/docs-search-mcp"],
"env": {
"DOCS_INDEX_PATH": "./docs-index"
}
},
"local-browser": {
"command": "node",
"args": ["./tools/mcp/browser-server.js"]
}
}
}
```
Ne mettez pas de secrets dans les fichiers `.mcp.json` commités. Placez les identifiants dans votre shell, une configuration à portée utilisateur, ou le flux d'installation MCP personnalisé de l'application si la valeur doit rester locale.
## Flux de travail MCP du tableau
Les agents doivent utiliser les outils MCP du tableau lorsque le travail relève d'une tâche :
1. Lisez le dernier contexte de la tâche.
2. Démarrez la tâche uniquement au moment où le travail commence réellement.
3. Ajoutez des commentaires de tâche pour les blocages, les plans et les résultats finaux.
4. Marquez la tâche comme terminée après avoir publié le commentaire de résultat.
5. Envoyez un court message lorsqu'un lead ou un coéquipier doit connaître le résultat.
Exemple de flux d'agent :
```text
task_get -> task_start -> edit/test -> task_add_comment -> task_complete -> message_send
```
Utilisez un message direct pour la coordination. Utilisez un commentaire de tâche pour un historique de tâche durable.
::: tip
Si la note concerne la revue, la vérification, un changement de périmètre ou un blocage, placez-la sur la tâche.
:::
## Outils Agent Teams intégrés
Le serveur MCP enregistre les outils depuis `agent-teams-controller/src/mcpToolCatalog.js`. La boucle d'enregistrement se trouve dans `mcp-server/src/tools/index.ts`, et chaque groupe a son propre fichier sous `mcp-server/src/tools/`.
Outils opérationnels courants :
| Outil | Usage |
| --- | --- |
| `task_get` | Lire le dernier contexte de la tâche, les commentaires, les pièces jointes, le statut et les relations |
| `task_start` | Marquer une tâche in progress lorsque le travail commence réellement |
| `task_add_comment` | Ajouter des notes de blocage, des notes de vérification, des plans et des résumés de résultats finaux |
| `task_complete` | Terminer une tâche après la publication du commentaire de résultat final |
| `message_send` | Envoyer un message de boîte de réception visible à un lead, un coéquipier ou un utilisateur |
| `review_request`, `review_start`, `review_approve`, `review_request_changes` | Faire avancer les flux de revue à portée de tâche |
| `process_register`, `process_list`, `process_stop`, `process_unregister` | Suivre les serveurs de développement, les watchers et autres services en arrière-plan détenus par les coéquipiers |
Les noms d'outils peuvent apparaître aux runtimes avec des préfixes d'espace de noms MCP, par exemple `mcp__agent-teams__task_get`. Le nom d'outil canonique à l'intérieur du serveur MCP reste `task_get`.
## Enregistrer un nouvel outil intégré
Pour le travail sur le dépôt Agent Teams, ajoutez des outils de tableau intégrés via la structure FastMCP existante :
1. Ajoutez l'implémentation de l'outil au fichier correspondant dans `mcp-server/src/tools/`, ou créez un nouveau fichier de groupe si le domaine est véritablement nouveau.
2. Ajoutez le nom de l'outil au groupe approprié dans `agent-teams-controller/src/mcpToolCatalog.js`.
3. Câblez un nouveau groupe via `mcp-server/src/tools/index.ts` uniquement lorsqu'un nouveau groupe de domaine est nécessaire.
4. Validez l'entrée avec `zod` et appelez l'API du contrôleur au lieu de lire directement les fichiers du tableau.
5. Ajoutez des tests ciblés dans `mcp-server/test/tools.test.ts` ou un cas e2e lorsque le transport importe.
Forme minimale :
```ts
server.addTool({
name: 'task_example',
description: 'Explain what this tool does for agents.',
parameters: z.object({
teamName: z.string().min(1),
claudeDir: z.string().min(1).optional(),
taskId: z.string().min(1)
}),
execute: async ({ teamName, claudeDir, taskId }) => {
assertConfiguredTeam(teamName, claudeDir);
const controller = getController(teamName, claudeDir);
return jsonTextContent(controller.tasks.getTask(taskId));
}
});
```
Ne créez pas un outil qui contourne la validation du contrôleur, modifie des fichiers d'équipe sans rapport, ou expose un accès large au système de fichiers/aux processus sans un besoin de tâche restreint.
## Serveurs MCP externes
Utilisez des serveurs MCP externes lorsqu'un coéquipier a besoin d'une connexion d'outil durable, et pas seulement d'un prompt avec du contexte collé.
Bons cas d'usage :
- outils de test de navigateur ou de site web
- outils de données de conception ou de produit
- systèmes de documentation interne et de recherche
- systèmes de suivi de tickets ou de support
- outils d'inspection de base de données avec des identifiants en lecture seule
Mauvais cas d'usage :
- secrets collés dans les prompts
- fichiers ponctuels qui peuvent être attachés directement
- outils qui modifient les systèmes de production sans revue
- accès large au système de fichiers local lorsqu'une portée de projet plus étroite suffit
## Portées
Agent Teams reconnaît les portées MCP partagées et orientées projet.
| Portée | À utiliser quand |
| --- | --- |
| Utilisateur ou Global | Le même serveur doit être disponible dans tous les projets |
| Projet ou Local | Le serveur appartient à un seul dépôt, espace de travail ou contexte d'équipe |
Préférez la portée la plus étroite qui rend tout de même le flux de travail utilisable. Les serveurs à portée de projet sont plus faciles à raisonner pendant la revue, car l'outil appartient au projet en cours de modification.
## Liste de vérification de configuration
Avant d'assigner une tâche qui dépend d'un serveur MCP :
1. Installez ou configurez le serveur.
2. Confirmez qu'il apparaît dans la liste MCP installée de l'application pour la portée prévue.
3. Lancez les diagnostics depuis le registre MCP ou l'interface des extensions lorsqu'ils sont disponibles.
4. Commencez par une tâche en lecture seule à faible risque.
5. Mentionnez l'utilisation attendue de l'outil MCP dans la description de la tâche ou le brief d'équipe.
Si un serveur échoue aux diagnostics, corrigez cela d'abord. Un meilleur prompt de tâche ne réparera pas une commande manquante, un mauvais chemin de configuration ou des identifiants rejetés.
## Installer un serveur personnalisé depuis l'application
L'application de bureau expose les API du registre MCP via Electron IPC pour la recherche, le parcours, l'installation, l'installation personnalisée, la désinstallation, la lecture de l'état installé et les diagnostics. Les installations personnalisées valident le nom du serveur, la portée, le chemin du projet, les noms des variables d'environnement et les en-têtes HTTP avant d'appeler le chemin d'installation du runtime.
Utilisez l'installation personnalisée lorsque vous avez un paquet MCP qui n'est pas encore dans le registre :
| Champ | Exemple |
| --- | --- |
| Nom du serveur | `docs-search` |
| Portée | `project` pour ce dépôt, `user` pour tous les projets |
| Type | `stdio` pour les commandes locales, `http` ou `sse` pour les serveurs distants |
| Paquet | `@acme/docs-search-mcp` |
| Env | `DOCS_INDEX_PATH=./docs-index` |
Après l'installation, lancez les diagnostics et créez une petite tâche en lecture seule pour éprouver la surface d'outils avant d'assigner un travail plus important.
## Exemple de tâche
```text
Audit the docs home page with the browser MCP. Check desktop and mobile widths, capture any layout issue as a task comment, and only edit landing/product-docs files. Run `pnpm --dir landing docs:build` before completion.
```
Cela fonctionne parce que cela nomme l'outil, la surface, la limite d'écriture et l'étape de vérification.
## Règles de sécurité
- Ne donnez pas par défaut à chaque coéquipier chaque serveur MCP.
- Tenez les outils capables d'écriture hors des équipes larges, sauf si la revue les exige.
- Préférez les identifiants en lecture seule pour les tâches d'inspection.
- Placez l'utilisation d'outils ayant un impact sur la production derrière des commentaires de tâche explicites et une revue.
- Traitez les échecs de diagnostic MCP comme des échecs de configuration, pas des échecs d'agent.
- Évitez de commiter des secrets dans `.mcp.json` ou dans les prompts.
- Utilisez des valeurs `projectPath` absolues lors de l'installation de serveurs à portée de projet via l'application.
- Ne modifiez pas les fichiers `agent-teams-mcp-*.json` générés par l'application ; ce sont des artefacts de lancement temporaires.
## Guides associés
- [Configuration du runtime](/fr/guide/runtime-setup)
- [Exemples de briefs d'équipe](/fr/guide/team-brief-examples)
- [Flux de travail des agents](/fr/guide/agent-workflow)
- [Développeurs](/fr/developers/)

193
landing/product-docs/fr/guide/quickstart.md Normal file
View file

@ -0,0 +1,193 @@
---
title: Démarrage rapide – Documentation Agent Teams
description: Passez d'une installation neuve à une équipe d'agents IA en fonctionnement en quelques minutes. Couvre l'installation, la sélection du runtime, la création d'équipe et la première revue de code.
lang: fr-FR
---
# Démarrage rapide
Ce guide vous fait passer d'une installation neuve à une équipe en fonctionnement en quelques minutes.
## Le chemin le plus court
```bash
# 1. Install prerequisites
node --version # need 20+
pnpm --version # need 10+
# 2. Clone and install
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
# 3. Start the desktop app (default workflow)
pnpm dev
# 4. Verify a docs-only change
pnpm --dir landing docs:build
```
L'application de bureau Electron (`pnpm dev`) est la cible principale — n'utilisez pas le serveur de développement navigateur/web pour le développement normal. Le chemin navigateur ne dispose pas de l'IPC de bureau, du terminal, de l'authentification fournisseur, ni du comportement de cycle de vie des équipes.
## Avant de commencer
Vous avez besoin de :
- **Un ordinateur** sous macOS, Windows ou Linux
- **(Recommandé) Un projet suivi par Git** — l'isolation par worktree et la revue des diffs reposent sur Git
- **(Optionnel) Un accès fournisseur** — la configuration du runtime détecte les fournisseurs disponibles depuis l'interface, mais certains chemins nécessitent une authentification existante (Anthropic, OpenAI, etc.)
Si une étape ci-dessous ne fonctionne pas, consultez le [guide de dépannage](/fr/guide/troubleshooting#team-does-not-launch) pour les correctifs courants.
Pour les conventions de projet et les recommandations d'architecture, reportez-vous à ces fichiers canoniques avant d'apporter des modifications :
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — repères de navigation et d'architecture du dépôt
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — conventions de travail et règles du projet
- [Standard d'architecture des fonctionnalités](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) — structure pour les nouvelles fonctionnalités
- [Runbook de débogage](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) — diagnostics de lancement et de coéquipiers
## 1. Exécuter depuis les sources ou télécharger
**Téléchargez l'application packagée** pour macOS, Windows ou Linux depuis la <a href="/fr/download/" target="_self">page de téléchargement</a> - aucun prérequis nécessaire. Commencez avec le modèle gratuit sans authentification, ou connectez une authentification fournisseur depuis l'interface lorsque vous souhaitez davantage de modèles.
**Ou exécutez depuis les sources** pour le développement :
Nécessite Node.js 24.16.0 LTS et pnpm 10+. Sur macOS, les binaires précompilés officiels de Node.js 24 nécessitent macOS 13.5+.
```bash
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
pnpm dev
```
`pnpm dev` démarre l'application de bureau Electron avec rechargement à chaud. C'est la cible de développement par défaut. Ne démarrez pas un serveur de développement web navigateur pour le développement normal — le chemin navigateur ne dispose pas de l'IPC de bureau complet, du terminal, de l'authentification fournisseur, ni du comportement de cycle de vie des équipes.
## 2. Ouvrir ou créer un projet
Lancez l'application et sélectionnez le répertoire du projet dans lequel vous voulez que les agents travaillent. Agent Teams lit les fichiers locaux du projet et l'état du runtime/de la session afin que l'interface puisse afficher les tâches, les journaux, les diffs et l'activité des coéquipiers.
::: tip
Choisissez un projet suivi par Git pour la meilleure expérience. L'isolation par worktree et la revue basée sur les diffs reposent toutes deux sur Git.
:::
Avant de lancer une équipe, vérifiez que le projet dispose d'une base de référence suffisamment propre :
```bash
git status --short
```
Vous n'avez pas besoin d'un arbre parfaitement propre, mais vous devriez savoir quelles modifications sont les vôtres avant que les agents ne commencent à éditer. Cela rend les diffs de tâche et la revue au niveau du hunk bien plus fiables.
## 3. Choisir un chemin de runtime
Le flux de configuration détecte automatiquement les runtimes installés sur votre machine. Une première configuration courante est :
| Runtime | Adapté à |
| -------- | ----------------------------------------------- |
| Claude | Utilisateurs de Claude Code et accès Anthropic existant |
| Codex | Flux de travail natifs Codex et accès OpenAI |
| OpenCode | Modèle gratuit sans authentification, équipes multimodèles et nombreux backends fournisseurs |
::: info
Gemini est disponible en tant que chemin fournisseur pris en charge. Voir [Fournisseurs et runtimes](/fr/reference/providers-runtimes) pour les options d'authentification et l'état actuel des fournisseurs.
:::
Voir [Configuration du runtime](/fr/guide/runtime-setup) pour une configuration détaillée par fournisseur.
Pour vérifier un runtime payant ou adossé à un compte en dehors de l'application, vérifiez le binaire et testez l'authentification :
```bash
# Check that the runtime is installed and on PATH
command -v claude && claude --version
command -v codex && codex --version
command -v opencode && opencode --version
```
Si la commande échoue, corrigez d'abord l'installation du runtime ou le `PATH`. Les prompts d'équipe ne peuvent pas contourner un binaire manquant ou une authentification fournisseur manquante pour les modèles qui l'exigent.
::: tip
Si le binaire est trouvé mais que l'application signale « not logged in », l'environnement peut différer entre votre terminal et l'application. Voir le [journal de diagnostic d'authentification](/fr/guide/troubleshooting#auth-diagnostic-log) pour les comparer.
:::
## 4. Créer votre première équipe
Créez une équipe avec un lead et un ou plusieurs spécialistes. Gardez la première équipe petite : un lead, un agent d'implémentation et un agent orienté revue suffisent pour valider le flux de travail.
Voir [Créer une équipe](/fr/guide/create-team) pour la structure recommandée et des conseils.
Pour le premier lancement, privilégiez une forme d'équipe comme celle-ci :
| Membre | Responsabilité | Notes |
| --- | --- | --- |
| Lead | Découper l'objectif en tâches et coordonner le statut | Conservez-le sur le fournisseur le plus fiable dont vous disposez |
| Builder | Implémenter les tâches délimitées | Donnez des frontières claires de fichiers ou de fonctionnalités |
| Reviewer | Examiner le travail terminé | Demandez-lui de se concentrer sur les régressions et les tests manquants |
Évitez de commencer avec cinq coéquipiers ou plus. Davantage d'agents augmentent la concurrence, les journaux, l'utilisation des fournisseurs et le risque de conflits avant que vous ne sachiez que la configuration est saine.
## 5. Donner au lead un objectif concret
Rédigez l'objectif comme vous briefieriez un lead d'ingénierie :
```text
Improve the onboarding flow. Split the work into tasks, keep changes small, and ask for review before broad refactors.
```
Les bons premiers prompts incluent un périmètre concret, des frontières de sécurité et une vérification :
```text
Improve the docs quickstart. Keep edits inside landing/product-docs. Add practical examples, preserve existing VitePress syntax, and run `pnpm --dir landing docs:build` before marking tasks done.
```
Évitez les prompts vagues comme « rendre l'application meilleure » pour la première exécution. Le lead peut décomposer de grands objectifs, mais une meilleure entrée produit des tâches plus petites et une revue plus propre.
::: tip
Si l'équipe se lance mais qu'aucune tâche n'apparaît, vérifiez si le lead a reçu votre prompt. Voir [les réponses des agents sont manquantes](/fr/guide/troubleshooting#agent-replies-are-missing) pour les diagnostics.
:::
Le lead crée les tâches, attribue le travail et coordonne les coéquipiers. Vous pouvez suivre la progression sur le tableau kanban et intervenir à tout moment avec des commentaires ou des messages directs.
## 6. Examiner les résultats
Ouvrez les tâches terminées ou prêtes pour la revue, inspectez le diff, et acceptez, rejetez ou commentez les modifications individuelles. Utilisez les journaux de tâche lorsque vous avez besoin de comprendre pourquoi un agent a fait un choix.
Voir [Revue de code](/fr/guide/code-review) pour le flux de travail de revue complet.
Avant d'approuver la première tâche, vérifiez trois choses :
1. Le commentaire de la tâche explique ce qui a changé
2. Les fichiers modifiés correspondent au périmètre de la tâche
3. Le résultat de la vérification est visible dans le commentaire de la tâche ou les journaux
## Pièges courants
| Symptôme | Cause probable | Vérification |
| --- | --- | --- |
| L'application ne détecte pas de runtime | Binaire absent du `PATH`, ou l'application et le terminal voient des environnements différents | Exécutez `command -v <runtime>` dans un terminal, puis utilisez le même environnement de terminal pour lancer l'application |
| Le lancement de l'équipe se bloque | Authentification fournisseur manquante pour un modèle payant/adossé à un compte, mauvaise chaîne de modèle, ou binaire du runtime introuvable | Voir [Dépannage](/fr/guide/troubleshooting#team-does-not-launch) |
| La voie OpenCode reste bloquée sur `registered` | Preuve de voie pas encore committée, ou incohérence de chaîne de modèle | Inspectez `~/.claude/teams/<team>/.opencode-runtime/lanes/` |
| Réponses des agents manquantes | Problème de réessai de livraison du runtime, d'analyse, ou d'attribution de tâche | Ouvrez les journaux de tâche et vérifiez le registre de livraison |
| Le fournisseur renvoie des 429 | Limite de débit atteinte | Attendez la réinitialisation ou changez de modèle/fournisseur |
## Étapes suivantes
- [Créer une équipe](/fr/guide/create-team) — formes d'équipe recommandées et rédaction du brief
- [Configuration du runtime](/fr/guide/runtime-setup) — authentification fournisseur et sélection du modèle
- [Revue de code](/fr/guide/code-review) — examiner, approuver ou demander des modifications
### Pour les contributeurs
Si vous modifiez Agent Teams ou cette documentation, commencez par les fichiers canoniques du projet à la racine du dépôt :
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — conventions de travail et règles du projet
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — couche de navigation pour l'architecture et les recommandations d'implémentation
- [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) — garde-fous d'implémentation stricts
- [Standard d'architecture des fonctionnalités](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) — structure pour les nouvelles fonctionnalités
- [Runbook de débogage des équipes d'agents](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) — diagnostics de lancement, de bootstrap et de coéquipiers
Pour vérifier que ce site de documentation se construit correctement :
```bash
pnpm --dir landing docs:build
```

179
landing/product-docs/fr/guide/runtime-setup.md Normal file
View file

@ -0,0 +1,179 @@
---
title: Configuration du runtime – Documentation Agent Teams
description: Configurez les runtimes Claude Code, Codex ou OpenCode. Couvre l'authentification, l'accès aux fournisseurs, le mode multimodèle et les vérifications avant lancement.
lang: fr-FR
---
# Configuration du runtime
Agent Teams est une couche de coordination. Le véritable travail des modèles s'exécute via les runtimes et les fournisseurs locaux pris en charge.
::: tip Démarrage rapide - choisir votre premier runtime
| Si vous ... | Commencez par |
| --- | --- |
| Utilisez déjà Claude Code ou disposez d'un accès Anthropic | **Claude** - authentification familière, configuration minimale |
| Utilisez Codex ou des flux de travail basés sur OpenAI | **Codex** - intégration native |
| Voulez essayer Agent Teams sans inscription ni clés d'API | **OpenCode** - utilisez le modèle gratuit inclus sans authentification |
| Voulez un routage multimodèle ou une large couverture de fournisseurs | **OpenCode** - le plus flexible, une seule configuration pour de nombreux backends |
| N'êtes pas sûr du runtime qui vous convient | **OpenCode** - couvre le plus d'options de fournisseurs et vous permet de changer plus tard |
Commencez avec un seul runtime et un seul coéquipier. Confirmez qu'un lancement fonctionne avant de passer au multimodèle.
:::
## Prérequis
Avant de lancer une équipe, assurez-vous que :
- Le binaire du runtime est installé et présent dans votre `PATH`.
- Votre compte fournisseur dispose d'un accès actif au modèle que vous comptez utiliser, sauf si vous commencez avec le modèle OpenCode gratuit inclus sans authentification.
- Le chemin du projet existe et est lisible.
- L'application et votre terminal utilisent le même environnement home/config lorsque vous testez l'authentification manuellement.
::: tip
Commencez avec un seul coéquipier et un seul fournisseur. Confirmez qu'un lancement fonctionne avant d'ajouter des voies multimodèles.
:::
Vérifications rapides dans le terminal :
```bash
command -v claude
command -v codex
command -v opencode
```
Exécutez la commande correspondant au runtime que vous prévoyez d'utiliser. Si elle n'affiche rien, installez le runtime ou corrigez le `PATH` avant de lancer une équipe.
## Chemins pris en charge
| Chemin | CLI par défaut | Fournisseurs typiques | À utiliser quand |
| --- | --- | --- | --- |
| Claude | `claude` | Anthropic | Vous utilisez déjà Claude Code ou des flux de travail adossés à Anthropic |
| Codex | `codex` | OpenAI | Vous voulez une intégration runtime native de Codex |
| OpenCode | `opencode` | OpenRouter et de nombreux backends | Vous voulez un routage multimodèle et une large couverture de fournisseurs |
L'application détecte les runtimes pris en charge et guide la configuration depuis l'interface lorsque cela est possible.
Gemini est disponible comme chemin de fournisseur pris en charge avec Google ADC (`gcloud auth`), l'OAuth de Gemini CLI et l'authentification par clé d'API. Configurez-le depuis l'interface de configuration du runtime lorsque le backend Gemini est détecté.
## Accès aux fournisseurs
Agent Teams n'a pas de palier payant propre. Vous pouvez commencer avec le modèle OpenCode gratuit inclus sans authentification - sans inscription, clés d'API ni carte de crédit. Pour des modèles supplémentaires, apportez l'accès fournisseur dont vous disposez déjà : abonnements, authentification de runtime local ou clés d'API selon le chemin que vous choisissez.
- Les chemins **Claude** et **Codex** s'appuient sur leurs outils d'authentification CLI respectifs.
- **OpenCode** peut d'abord exécuter le modèle gratuit inclus sans authentification. D'autres modèles OpenCode peuvent nécessiter des clés d'API spécifiques au fournisseur dans un fichier de configuration (par exemple `openrouter`, `openai`, `anthropic`).
## Configuration de l'authentification
### Claude Code
Exécutez le flux d'authentification standard dans un terminal :
```bash
claude login
```
Vérifiez ensuite que la CLI est accessible :
```bash
claude --version
```
Si l'application packagée signale « not logged in » alors que votre terminal fonctionne, comparez les `$HOME` et `PATH` vus par l'application avec ceux du terminal que vous avez utilisé pour la connexion. Le journal de diagnostic d'authentification décrit dans [Dépannage](/fr/guide/troubleshooting#auth-diagnostic-log) est le meilleur point de départ.
### Codex
Installez et authentifiez-vous via le flux CLI d'OpenAI :
```bash
codex login
```
Vérifiez ensuite que le runtime est accessible :
```bash
codex --version
```
Les lancements natifs de Codex utilisent l'état du compte Codex et les données du catalogue de modèles lorsqu'elles sont disponibles. Si un modèle est absent de l'interface, actualisez le statut du fournisseur avant de modifier les prompts d'équipe.
### OpenCode
Pour utiliser le modèle gratuit inclus sans authentification, sélectionnez-le dans l'application et lancez sans inscription auprès d'un fournisseur. Pour utiliser d'autres backends OpenCode, créez ou modifiez `~/.opencode/config.json` (ou le chemin équivalent sur votre plateforme) avec la clé de fournisseur souhaitée :
```json
{
"providers": {
"openrouter": {
"apiKey": "sk-or-..."
}
}
}
```
Utilisez le nom de fournisseur exact attendu par OpenCode. Si vous définissez un nom de fournisseur personnalisé, vérifiez bien qu'il correspond à l'ID de fournisseur que vous utilisez dans la chaîne de modèle (par exemple `openrouter/moonshotai/kimi-k2.6` utiliserait le bloc `openrouter`).
Exemples de chaînes de modèle :
| Chaîne de modèle | Bloc de fournisseur qui doit exister |
| --- | --- |
| `openrouter/moonshotai/kimi-k2.6` | `openrouter` |
| `openai/gpt-5.4` | `openai` |
| `anthropic/claude-sonnet-4-6` | `anthropic` |
Si OpenCode se lance mais qu'un coéquipier ne devient jamais livrable, inspectez les preuves de voie avant de supposer que le modèle a ignoré le prompt. Voir [Dépannage](/fr/guide/troubleshooting#opencode-registered-but-bootstrap-unconfirmed).
### Gemini
Gemini prend en charge trois méthodes d'authentification :
- **Google ADC** — exécutez `gcloud auth application-default login` pour vous authentifier via les Google Application Default Credentials.
- **Gemini CLI** — exécutez `gemini login` si la CLI Gemini est installée.
- **Clé d'API** — définissez `GEMINI_API_KEY` dans votre environnement ou configurez-la via l'interface Manage Providers de l'application.
L'application détecte automatiquement la méthode d'authentification disponible et affiche le fournisseur Gemini dans l'interface de configuration du runtime et de création d'équipe lorsque le backend est accessible.
## Mode multimodèle
Le mode multimodèle peut router le travail à travers de nombreux backends de fournisseurs via une configuration compatible OpenCode. Utilisez-le lorsque vous avez besoin de flexibilité de fournisseur ou que vous voulez que les coéquipiers utilisent différentes voies de modèles.
::: info Voies de modèles
Chaque coéquipier peut utiliser une paire `providerId` + `model` différente. Dans l'interface d'édition d'équipe, déployez les options de membre pour remplacer les valeurs par défaut globales.
:::
Une configuration multimodèle prudente :
| Rôle | Fournisseur | Pourquoi |
| --- | --- | --- |
| Lead | Claude ou Codex | Gardez la coordination sur le fournisseur en qui vous avez le plus confiance |
| Builder | OpenCode | Utilisez un large routage de modèles pour le travail d'implémentation |
| Reviewer | Claude, Codex ou un second modèle OpenCode | Séparez le jugement de revue de la voie du builder |
Évitez de mélanger de nombreux fournisseurs inconnus dès le premier lancement. Confirmez une petite tâche par voie avant d'assigner un travail plus large.
## Liste de vérification avant lancement
Avant de lancer une équipe :
1. Le runtime sélectionné est installé
2. Le binaire du runtime est dans le `PATH` de l'environnement
3. L'authentification du fournisseur est configurée pour le backend choisi
4. Le fournisseur a accès à la chaîne de modèle exacte que vous spécifiez
5. Le chemin du projet existe et est lisible
## Quand changer de chemin de runtime
Changez lorsque le chemin actuel est bloqué par la disponibilité du modèle, les limites de débit, les capacités du fournisseur ou les besoins de rôle de l'équipe. Conservez le même projet et le même flux de travail d'équipe, mais validez une petite tâche après le changement.
::: warning Traitez les erreurs de configuration comme des problèmes de configuration
Si l'authentification échoue, qu'un nom de modèle est rejeté ou que le binaire du runtime est introuvable, corrigez d'abord la configuration. Ne modifiez pas les prompts d'équipe ni le code du projet pour contourner un problème de configuration du runtime.
:::
Utilisez ce tableau de décision :
| Symptôme | Meilleure première action |
| --- | --- |
| Binaire introuvable | Corrigez l'installation ou le `PATH` |
| La connexion fonctionne dans le terminal mais pas dans l'application | Vérifiez le journal de diagnostic d'authentification Electron et l'environnement |
| Modèle rejeté | Vérifiez l'identifiant de modèle exact dans le runtime du fournisseur |
| 429 répétés | Réduisez la concurrence ou changez de modèle/fournisseur |
| Voie OpenCode bloquée | Inspectez le manifeste de la voie et `opencode-sessions.json` |

131
landing/product-docs/fr/guide/team-brief-examples.md Normal file
View file

@ -0,0 +1,131 @@
---
title: Exemples de briefs d'équipe – Documentation Agent Teams
description: Modèles pratiques de briefs d'équipe pour les petits correctifs, le travail documentaire, les tâches d'implémentation, les revues et les zones à haut risque.
lang: fr-FR
---
# Exemples de briefs d'équipe
Un bon brief d'équipe donne au lead suffisamment de structure pour créer de petites tâches sans imposer dès le départ chaque détail d'implémentation.
Utilisez cette forme :
```text
Outcome:
Scope:
Boundaries:
Coordination:
Verification:
Review:
```
## Brief minimal
À utiliser pour un travail réduit et à faible risque.
```text
Outcome: Improve the quickstart so a new user can launch one team successfully.
Scope: Keep edits inside landing/product-docs.
Boundaries: Do not rewrite the whole docs structure.
Coordination: Create one or two tasks, keep comments on the task.
Verification: Run `pnpm --dir landing docs:build`.
Review: Summarize changed pages and any remaining gaps.
```
## Brief d'implémentation
À utiliser lorsque des modifications de code touchent une seule zone fonctionnelle.
```text
Outcome: Add a focused improvement to task comment filtering.
Scope: Work inside the task/comment feature files unless a shared helper is clearly needed.
Boundaries: Do not change task storage format or review state semantics.
Coordination: Split parser, UI, and tests into separate tasks if they can be reviewed independently.
Verification: Run the focused unit tests first, then the feature typecheck if touched.
Review: Call out parsing edge cases and any behavior that affects existing task comments.
```
## Brief documentaire
À utiliser pour le travail de documentation et de guides.
```text
Outcome: Draft practical workflow guides from the docs audit.
Scope: Add concise VitePress pages under landing/product-docs/guide.
Boundaries: Avoid moving existing navigation hubs owned by other tasks.
Coordination: Check related docs tasks before editing nav.
Verification: Run `pnpm --dir landing docs:build`.
Review: Include links added to sidebar and any pages intentionally left as drafts.
```
## Brief à forte composante de revue
À utiliser pour les zones risquées telles que l'IPC, l'authentification des fournisseurs, la persistance, Git ou la logique du cycle de vie des tâches.
```text
Outcome: Fix the launch failure without changing successful launch behavior.
Scope: Start from the newest launch-failure artifact and the affected runtime adapter.
Boundaries: Do not change provider prompts until setup and runtime evidence are inspected.
Coordination: Make one diagnostic task and one fix task if the cause is confirmed.
Verification: Run focused tests and one desktop smoke check when practical.
Review: Lead must inspect the diff before approval.
```
## Brief multifournisseur
À utiliser lorsque les coéquipiers s'exécutent sur des lanes fournisseur/modèle différentes.
```text
Outcome: Implement and review a small feature using separate builder and reviewer lanes.
Scope: Builder edits the feature. Reviewer inspects only the task diff and tests.
Boundaries: Do not switch model ids mid-task unless launch fails before work begins.
Coordination: Builder posts result comment first. Reviewer posts findings as task comments.
Verification: Builder runs focused tests. Reviewer checks failure output and changed scope.
Review: Lead approves only after reviewer comments are resolved.
```
## Blocs d'agent dans les briefs
Les blocs d'agent sont des textes destinés uniquement aux agents, masqués et encadrés par des marqueurs tels que `<info_for_agent>...</info_for_agent>`. L'application les supprime de l'affichage normal mais les conserve disponibles pour la coordination entre agents. Utilisez-les lorsque le brief doit dire quelque chose aux agents qui serait du bruit pour un lecteur humain.
Exemple - un brief qui indique au lead comment répartir le travail sans exposer les instructions de coordination à l'utilisateur :
```text
Outcome: Add a dark mode toggle to the application settings.
Scope: Settings UI, theme context, and CSS variables.
Boundaries: Do not change existing light theme values or provider auth screens.
<info_for_agent>
Split this into three tasks: (1) theme context and CSS vars, (2) toggle component and settings wiring, (3) dark mode preview in existing docs screenshots if practical.
</info_for_agent>
```
Le bloc garde le brief destiné aux humains propre tout en donnant au lead des indications structurées pour découper les tâches.
## Ce qu'il faut éviter
| Brief faible | Meilleure formulation |
| --- | --- |
| « Améliorer l'application » | Nommez le flux de travail, les fichiers et le contrôle de réussite |
| « Corriger toute la doc » | Choisissez un seul groupe de guides et une seule commande de build |
| « Utiliser le meilleur modèle » | Nommez les choix de fournisseur/modèle ou laissez les valeurs par défaut de l'application en place |
| « Refactoriser au besoin » | Indiquez quels modules ont le droit de changer |
| « Le rendre prêt pour la production » | Définissez la revue, les tests et les contrôles de déploiement |
## Avant le lancement
Vérifiez ces points avant de démarrer l'équipe :
1. Le brief nomme un résultat concret.
2. Les limites de risque sont explicites.
3. Le lead peut découper le travail en tâches révisables.
4. Les commandes de vérification sont incluses lorsqu'elles sont connues.
5. Les zones sensibles exigent une revue avant approbation.
Si le brief reste trop large, lancez d'abord une équipe solo ou réduite et demandez-lui de produire un plan de tâches plutôt qu'une implémentation.
## Guides associés
- [Créer une équipe](/fr/guide/create-team)
- [Intégration MCP](/fr/guide/mcp-integration)
- [Stratégie Git et worktree](/fr/guide/git-worktree-strategy)

310
landing/product-docs/fr/guide/troubleshooting.md Normal file
View file

@ -0,0 +1,310 @@
---
title: Dépannage – Documentation Agent Teams
description: Résolvez les problèmes de lancement d'équipe, les réponses d'agent manquantes, les limites de débit, les problèmes d'authentification CLI et les blocages de bootstrap de lane grâce à des diagnostics locaux.
lang: fr-FR
---
# Dépannage
La plupart des problèmes d'équipe relèvent de l'une de ces quatre catégories : configuration du runtime, confirmation de lancement, analyse des tâches et limites du fournisseur.
## Mise en place rapide des preuves
Pour tout problème lié au cycle de vie d'une équipe, définissez d'abord ces variables et réutilisez le même shell :
```bash
TEAM="<team-name>"
TEAM_DIR="$HOME/.claude/teams/$TEAM"
TASKS_DIR="$HOME/.claude/tasks/$TEAM"
```
Confirmez ensuite que les fichiers attendus existent avant d'interpréter l'état de l'interface :
```bash
test -d "$TEAM_DIR" && find "$TEAM_DIR" -maxdepth 2 -type f | sort | sed -n '1,80p'
test -d "$TASKS_DIR" && find "$TASKS_DIR" -maxdepth 1 -name '*.json' | sort | sed -n '1,40p'
```
::: warning Les preuves d'abord
Ne corrigez pas les prompts, les paramètres du fournisseur ou le nettoyage des processus en vous basant uniquement sur un badge bloqué. Corrélez d'abord l'interface avec les fichiers persistés, les artefacts de lancement et les preuves du runtime.
:::
## L'équipe ne se lance pas
Vérifiez chaque élément dans l'ordre :
1. **Runtime disponible** — la CLI sélectionnée (`claude`, `codex`, `opencode`) est installée
2. **PATH accessible** — le binaire est disponible dans le `PATH` de l'environnement
3. **Accès au modèle** — le fournisseur a accès à la chaîne de modèle demandée (en particulier pour OpenCode, les noms exacts de fournisseur/modèle ont leur importance)
4. **Chemin du projet** — le répertoire du projet existe et est lisible
5. **Réseau / VPN** — certains fournisseurs bloquent le trafic lorsqu'un VPN est actif
::: tip
Exécutez le binaire du runtime dans un terminal pour vérifier le `PATH` et l'authentification. Exemple : `claude --version` ou `opencode --version`.
:::
### OpenCode : enregistré mais bootstrap non confirmé
Si OpenCode affiche `registered` mais que le bootstrap n'est pas confirmé, inspectez d'abord les artefacts avant de modifier les prompts de l'équipe.
Les détails pour les contributeurs et le débogage se trouvent dans [Architecture pour les contributeurs](/fr/reference/contributor-architecture), qui renvoie au runbook canonique de débogage des équipes d'agents.
Examinez l'artefact d'échec de lancement le plus récent :
```bash
LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
MANIFEST_PATH="$(jq -r '.manifestPath' "$LATEST_FAILURE")"
jq '.classification, .bootstrapTransportBreadcrumb, .memberSpawnStatuses' "$MANIFEST_PATH"
```
`latest.json` pointe vers le répertoire d'artefacts empaquetés le plus récent et son `manifest.json`. Le manifeste inclut :
- `classification` — pourquoi le lancement a été considéré comme un échec
- `bootstrapTransportBreadcrumb` — le chemin de livraison utilisé
- Les statuts de spawn des membres
- Les journaux et traces expurgés
Vérifiez aussi le manifeste de lane :
```bash
jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime/lanes" -maxdepth 2 -name manifest.json -print -exec jq '.activeRunId, .entries' {} \; 2>/dev/null
```
::: tip Ne devinez pas à partir de l'interface
Corrélez toujours les diagnostics de l'interface avec les fichiers persistés (`launch-state.json`, `bootstrap-journal.jsonl`) et les preuves spécifiques au runtime.
:::
## Diagnostics généraux
Commencez par les fichiers persistés sur le disque plutôt que par l'interface seule.
### Racine de l'équipe
```bash
printf '%s\n' "$TEAM_DIR"
```
Fichiers clés et ce qu'ils vous indiquent :
- `launch-state.json` — état de lancement/vivacité des membres (`.teamLaunchState`, `.summary`, `.members`)
- `bootstrap-journal.jsonl` — événements de bootstrap ordonnés depuis la CLI/le runtime (`tail -80`)
- `bootstrap-state.json` — résumé de la phase de bootstrap
- `config.json` — configuration du fournisseur, du modèle et du projet
- `inboxes/*.json` et `sentMessages.json` — état de livraison des messages
```bash
jq '.teamLaunchState, .summary, .members' "$TEAM_DIR/launch-state.json"
tail -80 "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
```
### Preuves du runtime OpenCode
Pour les coéquipiers OpenCode, la preuve de session se trouve dans le magasin runtime de lane :
- `.opencode-runtime/lanes.json` — index des lanes avec leur état
- `.opencode-runtime/lanes/<lane>/manifest.json` — `activeRunId` et entrées de preuve
- `.opencode-runtime/lanes/<lane>/opencode-sessions.json` — enregistrements de session validés
État sain attendu : état de lane `active`, le manifeste a un `activeRunId` avec au moins une entrée de preuve, le membre a `bootstrapConfirmed: true`.
```bash
jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime" -maxdepth 3 -type f | sort
```
### Artefacts d'échec de lancement
Lorsqu'un lancement est marqué comme un échec, inspectez `latest.json` :
```bash
LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
jq '.' "$LATEST_FAILURE"
jq '.' "$(jq -r '.manifestPath' "$LATEST_FAILURE")"
```
Le manifeste inclut :
- `classification` — pourquoi le lancement a été considéré comme un échec
- `bootstrapTransportBreadcrumb` — le chemin de livraison utilisé
- Les statuts de spawn des membres et les journaux/traces expurgés
## Les réponses des agents sont manquantes
Ouvrez les journaux de tâches et les messages des coéquipiers. Les réponses manquantes proviennent souvent de :
- **Nouvelle tentative de livraison du runtime** — l'agent a peut-être répondu, mais le message n'a pas été livré à l'application. Vérifiez le registre de livraison.
- **Analyse ou filtrage** — la sortie de l'agent ne comportait pas les marqueurs attendus ou les références de tâches.
- **Attribution de tâche** — le travail a eu lieu pendant la session mais n'a pas été lié à la tâche car l'identifiant de tâche correct était absent de la sortie.
::: warning Ne présumez pas que le silence signifie ignorer
Ne présumez pas que le modèle a ignoré le message tant que les journaux ne le confirment pas.
:::
Utilisez l'état persisté des messages pour distinguer « non envoyé » de « envoyé mais non rendu » :
```bash
jq '.' "$TEAM_DIR/inboxes/user.json" 2>/dev/null
jq '.' "$TEAM_DIR/sentMessages.json" 2>/dev/null
```
Vérifiez `from`, `to`, `messageId`, `relayOfMessageId` et `taskRefs`. Pour les coéquipiers OpenCode, inspectez aussi les preuves de livraison du runtime avant de présumer que le modèle a ignoré le prompt.
## Les tâches ne sont pas liées aux modifications
Utilisez les journaux propres à chaque tâche et les liens de revue de code. Si un diff semble détaché :
- Vérifiez si l'identifiant de tâche ou la référence de tâche figurait dans la sortie de l'agent.
- Vérifiez que l'agent a appelé `task_add_comment` avant d'effectuer des modifications.
- Assurez-vous que l'agent a appelé `task_start` pour que le tableau sache que le travail a commencé.
Pour les coéquipiers OpenCode, la preuve faisant autorité qu'une session appartient à une tâche se trouve dans `opencode-sessions.json` et l'entrée du manifeste de lane, et pas uniquement dans le flux de messages de l'interface.
### Triage des journaux de tâches
Lorsqu'un journal de tâche semble incomplet, recherchez par identifiant de tâche dans le JSON des tâches, les boîtes de réception et les événements de bootstrap :
```bash
TASK="<short-or-full-task-id>"
rg -n "$TASK" "$TASKS_DIR" "$TEAM_DIR/inboxes" "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
```
Interprétez le résultat avec soin :
| Preuve | Ce qu'elle prouve | Ce qu'elle ne prouve pas |
| --- | --- | --- |
| Message livré | L'application a écrit ou relayé un prompt | L'agent a progressé |
| Commentaire de tâche | L'agent a publié du texte visible sur le tableau | Que le commentaire constitue un progrès significatif |
| Lignes d'outils natifs | Le runtime a effectué du travail dans une session | Que le travail appartient à cette tâche, sauf si l'attribution correspond |
| Entrée du registre de modifications | L'application a enregistré des modifications de fichiers | Que l'implémentation est correcte |
Pour OpenCode, un journal de tâche sain inclut généralement des lignes de runtime natives comme `read`, `bash`, `edit` ou `write` ainsi que des lignes MCP Agent Teams. Si vous ne voyez que des lignes `agent-teams_*`, confirmez l'attribution de tâche et les limites de session avant d'élargir la correspondance des journaux.
## Limites de débit
Si un fournisseur signale une heure de réinitialisation connue, Agent Teams peut inciter le lead à continuer après le délai de récupération. Si l'heure de réinitialisation est inconnue, attendez ou changez de chemin de fournisseur/runtime.
| Comportement du fournisseur | Action suggérée |
| --- | --- |
| Heure de réinitialisation connue affichée | Attendre le délai de récupération et continuer |
| Aucune heure de réinitialisation affichée | Changer de fournisseur ou de chemin de runtime |
| 429 répétés | Réduire la concurrence ou utiliser une autre lane de modèle |
## Problèmes d'authentification CLI
### `claude login` ne persiste pas
Si la CLI est authentifiée dans un terminal mais que l'application indique le contraire, vérifiez que l'authentification est enregistrée au chemin de configuration attendu et que le processus de l'application voit le même `$HOME`.
### Clé de fournisseur OpenCode rejetée
- Vérifiez deux fois que le nom du fournisseur dans `config.json` correspond au préfixe de fournisseur dans la chaîne de modèle
- Assurez-vous que la clé n'est pas expirée ou révoquée dans le tableau de bord du fournisseur
### Journal de diagnostic d'authentification
Chaque appel à `CliInstallerService.getStatus()` ajoute une ligne à `claude-cli-auth-diag.ndjson` dans le dossier de journaux Electron (généralement `~/Library/Logs/<product-name>/` sur macOS). Si le fichier dépasse **512 KiB**, il est tronqué à vide avant la prochaine écriture.
Consultez ce fichier si vous voyez « Not logged in » ou des erreurs d'authentification dans l'application empaquetée.
## Bootstrap de lane bloqué
Pour les lanes secondaires OpenCode :
- Un fichier `inboxes/<member>.json` manquant n'est pas automatiquement un bug. Les lanes OpenCode n'ont pas besoin d'être créées via la boîte de réception primaire avant de démarrer.
- Si l'interface indique que l'équipe est encore en cours de lancement alors que les membres primaires sont déjà utilisables, « tous les coéquipiers ont rejoint » attend les lanes secondaires.
- Si `Prepared communication channels for X/Y members` reste bloqué, vérifiez si `Y` inclut à tort des membres OpenCode secondaires.
### Entrées vides du manifeste de lane
Si le pont (bridge) indique que le bootstrap a réussi mais que `manifest.json` affiche `entries: []`, le problème vient de la **validation des preuves**, et non du comportement du modèle. Le membre ne doit pas être considéré comme livrable tant que `opencode-sessions.json` et son entrée de manifeste n'existent pas.
## États courants des membres
| État | Signification |
| --- | --- |
| `confirmed_alive` + `bootstrapConfirmed` | Sain et prêt |
| `registered` / `runtime_pending_bootstrap` | Le processus ou la lane existe, mais la preuve de bootstrap n'a pas encore été validée |
| `failed_to_start` + `runtime_process` | Le processus existe, mais la porte de lancement a échoué. Vérifiez les diagnostics |
| `failed_to_start` + `stale_metadata` | Le pid/la session enregistrés sont périmés ou morts |
::: warning
`member_briefing` à lui seul N'EST PAS une preuve de runtime. Pour OpenCode, la preuve faisant autorité est une preuve de runtime validée telle que `opencode-sessions.json` et l'entrée du manifeste.
:::
## Mode débogage du runtime
Pour le débogage local, vous pouvez forcer les coéquipiers à s'exécuter dans des panneaux tmux :
```bash
# Launch from a terminal
CLAUDE_TEAM_TEAMMATE_MODE=tmux pnpm dev
# Or add to custom CLI args
--teammate-mode tmux
```
Utilisez ceci pour inspecter le comportement interactif de la CLI. Ne considérez pas cela comme entièrement équivalent au backend de processus.
## Vérifications de fumée
Utilisez l'application de bureau Electron pour la validation normale. Le mode de développement navigateur/web n'inclut pas le runtime de bureau complet, l'IPC, l'authentification des fournisseurs, le terminal ni le comportement du cycle de vie de l'équipe.
### Modifications de documentation uniquement
Depuis la racine du dépôt :
```bash
pnpm --dir landing docs:build
git diff --check -- landing/product-docs
```
### Modifications du cycle de vie de l'équipe
Commencez de façon ciblée, puis élargissez :
```bash
pnpm test -- test/main/services/team/TeamProvisioningService.test.ts
pnpm test -- test/main/services/team/TeamAgentLaunchMatrix.safe-e2e.test.ts
pnpm typecheck
git diff --check
```
### Test de fumée d'équipe en direct
Utilisez une petite équipe et un projet jetable suivi par Git :
1. Démarrez l'application de bureau avec `pnpm dev`.
2. Créez un lead et un builder.
3. Demandez une petite modification avec une commande de vérification explicite.
4. Confirmez que la tâche passe de `pending` -> `in_progress` -> `completed`.
5. Ouvrez les journaux de tâche et vérifiez que les lignes d'outils, les commentaires de tâche et les modifications de fichiers concordent.
6. N'arrêtez que l'équipe/les processus appartenant au test de fumée lors du nettoyage.
::: warning Nettoyage ciblé uniquement
Ne tuez pas tous les hôtes OpenCode, les panneaux tmux non liés ou les équipes utilisateur lors du nettoyage d'un test de fumée.
:::
## Nettoyage sûr
Lors du nettoyage de processus périmés :
1. Identifiez le pid et confirmez qu'il appartient à l'équipe / la lane en cours.
2. N'arrêtez que les processus appartenant explicitement à un test de fumée ou au lancement que vous déboguez.
3. **Ne tuez pas** tous les processus OpenCode ou les processus hôtes partagés par facilité.
## Quand collecter des preuves
Avant de demander de l'aide, collectez :
- L'identifiant de tâche (court ou complet)
- Le nom de l'équipe
- Le chemin de runtime (`claude`, `codex` ou `opencode`)
- Un extrait du journal de lancement (depuis `latest.json` ou `bootstrap-journal.jsonl`)
- La chaîne de fournisseur / modèle
- La fenêtre temporelle exacte où le problème s'est produit
Ces données suffisent généralement à déboguer les problèmes de lancement et de cycle de vie des tâches.
::: tip
Si le problème persiste, ouvrez les fichiers persistés de l'équipe sous `~/.claude/teams/<teamName>/` et corrélez les diagnostics de l'interface avec l'état des processus en direct avant de modifier le code.
:::

81
landing/product-docs/fr/index.md Normal file
View file

@ -0,0 +1,81 @@
---
title: Documentation Agent Teams – Lancez des équipes d'agents IA depuis une application de bureau locale
description: Documentation d'Agent Teams, une application de bureau gratuite pour l'orchestration d'agents IA. Créez des équipes, suivez le travail sur un tableau kanban, examinez les modifications de code et coordonnez les flux de travail Claude, Codex, OpenCode et multimodèles.
lang: fr-FR
layout: home
hero:
name: Documentation Agent Teams
text: Lancez des équipes d'agents IA depuis une application de bureau locale
tagline: Créez des équipes, suivez le travail se déplacer sur un tableau kanban, examinez les modifications de code et coordonnez les flux de travail Claude, Codex, OpenCode et multimodèles sans renoncer au contrôle local.
actions:
- theme: brand
text: Démarrage rapide
link: /fr/guide/quickstart
- theme: alt
text: Installation
link: /fr/guide/installation
- theme: alt
text: Concepts
link: /fr/reference/concepts
features:
- icon: "01"
title: Flux de travail axé sur l'équipe
details: Définissez des rôles, lancez un lead et laissez les agents répartir, revendiquer et coordonner les tâches.
link: /fr/guide/create-team
linkText: Créer une équipe
- icon: "02"
title: Tableau kanban en direct
details: Suivez les tâches passer par todo, in progress, review, done et approved au fil du travail des agents.
link: /fr/guide/agent-workflow
linkText: Comprendre le flux de travail
- icon: "03"
title: Revue de code intégrée
details: Inspectez les diffs au périmètre des tâches, acceptez ou rejetez des hunks et commentez là où les agents ont besoin d'orientation.
link: /fr/guide/code-review
linkText: Examiner les modifications
- icon: "04"
title: Configuration adaptée au runtime
details: Utilisez Claude, Codex, OpenCode ou des fournisseurs multimodèles via l'accès dont vous disposez déjà.
link: /fr/guide/runtime-setup
linkText: Configurer les runtimes
- icon: "05"
title: Contrôle local d'abord
details: L'application de bureau lit l'état local des projets et des runtimes. Votre code reste sur votre machine, sauf si un fournisseur sélectionné reçoit le contexte du prompt.
link: /fr/reference/privacy-local-data
linkText: Modèle de confidentialité
- icon: "06"
title: Équipes débogables
details: Tracez les journaux de tâches, la sortie du runtime, les messages des coéquipiers et les processus en direct lorsqu'un lancement ou une tâche se bloque.
link: /fr/guide/troubleshooting
linkText: Dépanner
---
<InstallBlock label="Copier" copied-label="Copié" />
## Commencer ici
Agent Teams est une application de bureau gratuite pour orchestrer des équipes d'agents IA. Vous n'envoyez pas seulement des prompts isolés à un seul agent : vous créez une équipe, attribuez des rôles et regardez les agents coordonner leur travail à travers un tableau de tâches.
<DocsCardGrid />
## Étapes suivantes après le lancement
Après avoir créé votre première équipe, explorez ces guides pour aller plus loin :
- **Configuration du runtime** - configurez Claude, Codex, OpenCode ou des fournisseurs multimodèles : [Configurer les runtimes](/fr/guide/runtime-setup)
- **Flux de travail des agents** - comprenez comment les agents se coordonnent à travers le tableau de tâches : [Comprendre le flux de travail](/fr/guide/agent-workflow)
- **Exemples de briefs d'équipe** - apprenez des modèles de prompt à partir de briefs concrets : [Voir les exemples](/fr/guide/team-brief-examples)
- **Revue de code** - inspectez les diffs, acceptez ou rejetez les modifications : [Examiner les modifications](/fr/guide/code-review)
- **Dépannage** - diagnostiquez les lancements bloqués, les coéquipiers manquants et les échecs de tâches : [Dépanner](/fr/guide/troubleshooting)
- **Stratégie Git et worktree** - utilisez l'isolation par worktree lorsque plusieurs coéquipiers modifient le même dépôt en parallèle : [En savoir plus sur les worktrees](/fr/guide/git-worktree-strategy)
- **Notes de version** - découvrez les nouveautés de chaque version : [Voir les versions](/fr/reference/release-notes)
## Référence
Utilisez les pages de référence lorsque vous avez besoin de la terminologie exacte, du comportement des fournisseurs, de l'architecture pour les contributeurs ou des frontières de confidentialité.
<DocsCardGrid type="reference" />
## Aperçu du produit
<ZoomImage src="/screenshots/1.jpg" alt="Tableau kanban d'Agent Teams" caption="Le statut des tâches, l'activité des coéquipiers et le flux de revue restent visibles dans un seul espace de travail." />

85
landing/product-docs/fr/reference/concepts.md Normal file
View file

@ -0,0 +1,85 @@
---
title: Concepts – Documentation Agent Teams
description: Vocabulaire de base d'Agent Teams — équipes, leads, coéquipiers, tâches, kanban, boîtes de réception, runtimes et revue.
lang: fr-FR
---
# Concepts
Cette page définit les termes de base utilisés dans Agent Teams. Servez-vous-en comme vocabulaire commun pour l'application, le tableau des tâches, les messages et le flux de revue.
## Équipe
Une équipe est un groupe nommé d'agents rattaché à un chemin de projet. Elle possède un lead, des coéquipiers optionnels, des paramètres de runtime/fournisseur, des prompts, des boîtes de réception, des tâches et un état de lancement local.
## Lead {#lead}
Le lead est le coordinateur de l'équipe. Il transforme un objectif utilisateur en tâches, assigne ou réoriente les coéquipiers, suit les blocages, demande des revues et fait avancer le travail sur le tableau.
[Coéquipier →](#teammate)
Les messages du lead empruntent un chemin de livraison différent de celui des messages des coéquipiers : l'application relaie les entrées de la boîte de réception du lead vers le runtime du lead, tandis que les coéquipiers lisent leurs propres fichiers de boîte de réception entre les tours.
## Coéquipier {#teammate}
Un coéquipier est un agent non-lead de l'équipe. Les coéquipiers occupent généralement des rôles ciblés comme builder, reviewer, chercheur ou testeur. Un coéquipier peut recevoir des messages directs, des assignations de tâches, des commentaires de tâches et des demandes de revue.
[Lead ↑](#lead)
## Tâche
Une tâche est l'unité de travail durable. Elle possède un id, un statut, un propriétaire, une description, des commentaires, des journaux, des pièces jointes, des références de tâches et des modifications revues.
Les états de tâche courants sont `todo`, `in_progress`, `done`, `review` et `approved`. En interne, le fichier de tâche stocke l'état du travail, tandis que le positionnement de revue et d'approbation peut aussi utiliser l'état d'overlay du kanban.
## Kanban
Le kanban est la vue en tableau du travail de l'équipe. Il vous permet de parcourir les tâches par état, d'ouvrir les détails d'une tâche, d'inspecter les journaux, de revoir les diffs, d'approuver le travail terminé ou de demander des modifications.
## Boîte de réception
Une boîte de réception est un fichier de messages local pour un participant de l'équipe. Agent Teams utilise les boîtes de réception pour les messages utilisateur, les messages du lead, les messages des coéquipiers, les métadonnées de livraison du runtime, les messages inter-équipes et certaines notifications système.
Les messages sont des enregistrements locaux durables. La livraison dépend toujours du fait que le runtime sélectionné soit actif et capable de traiter son tour suivant.
## Bloc d'agent
Un bloc d'agent est un texte d'instruction masqué, réservé aux agents, encadré par `<info_for_agent>...</info_for_agent>`. L'interface retire ces blocs de l'affichage normal destiné aux humains, mais les agents et la livraison runtime peuvent les utiliser pour des détails de coordination.
Le marqueur canonique actuel est `info_for_agent`. Les documents plus anciens peuvent utiliser des blocs de code délimités avec un marqueur `info_for_agent`, ou des balises de style XML `<agent_block>` — ce sont des motifs hérités qui devraient être migrés vers `info_for_agent` lorsqu'on les rencontre. (Le nom de balise original était `agent-block` ; la forme avec underscore `<agent_block>` est utilisée dans la source VitePress pour éviter l'analyse HTML.)
## Phase de contexte
Une phase de contexte est un segment d'une chronologie de contexte de session. La compaction démarre une nouvelle phase, de sorte que l'utilisation des tokens et du contexte peut être analysée avant et après la réinitialisation.
Le suivi du contexte sépare des catégories telles que les instructions de projet, les fichiers mentionnés, la sortie d'outils, le texte de réflexion, la coordination d'équipe et les messages utilisateur. Ces chiffres sont des diagnostics, pas des relevés de facturation des fournisseurs.
## Runtime
Un runtime est le chemin d'exécution local qui exécute un tour d'agent. Les chemins de runtime pris en charge incluent Claude Code, Codex et OpenCode.
Le runtime gère le comportement d'exécution du modèle, les détails d'authentification, la sémantique d'exécution des outils, les limites de débit, la disponibilité des modèles et certains formats de transcription/journaux.
## Fournisseur
Un fournisseur est le chemin d'accès au modèle situé derrière un runtime. Les ids de fournisseur actuels incluent Anthropic, Codex, Gemini et OpenCode. OpenCode peut router vers de nombreux fournisseurs de modèles via sa propre configuration.
Agent Teams orchestre les tâches et les messages, mais il ne remplace pas l'authentification du fournisseur ni la politique du fournisseur.
## Mode solo
Le mode solo exécute une équipe à un seul membre. Il est utile pour le travail rapide, une charge de coordination réduite et la validation d'un prompt avant de passer à une équipe complète.
## Communication inter-équipes
Les agents peuvent échanger des messages au sein d'une équipe et entre équipes. Utilisez cette fonctionnalité lorsque des équipes distinctes mènent des travaux liés et doivent se coordonner sans tout fusionner dans une seule grande équipe.
## Niveau d'autonomie
L'autonomie contrôle ce que les agents peuvent faire avant de demander. Une autonomie plus élevée est plus rapide ; une autonomie plus faible est plus sûre pour les chemins de code sensibles, la persistance, l'authentification des fournisseurs, les opérations Git et les releases.
## Revue
La revue est le flux d'acceptation au périmètre d'une tâche. Une tâche peut passer en review, recevoir des commentaires ou des modifications demandées, puis passer en approved lorsque le résultat est accepté.
La revue est liée aux diffs locaux et à l'historique des tâches, elle fonctionne donc mieux lorsque les tâches restent étroites et que les agents mentionnent la tâche sur laquelle ils travaillent.

55
landing/product-docs/fr/reference/contributor-architecture.md Normal file
View file

@ -0,0 +1,55 @@
---
title: Architecture pour les contributeurs – Documentation Agent Teams
description: Guide du contributeur sur l'organisation des fonctionnalités, les frontières runtime/fournisseur, les garde-fous stricts et les documents d'architecture canoniques.
lang: fr-FR
---
# Architecture pour les contributeurs
Cette page est une carte destinée aux contributeurs. Elle pointe vers les directives canoniques du dépôt plutôt que de réénoncer chaque règle d'implémentation.
## Sources canoniques
Utilisez ces fichiers comme source de vérité lorsque vous modifiez l'application :
| Besoin | Source canonique |
| --- | --- |
| Vue d'ensemble du dépôt et commandes | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) |
| Conventions de travail locales | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) |
| Garde-fous stricts | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) |
| Organisation des fonctionnalités moyennes et grandes | [docs/FEATURE_ARCHITECTURE_STANDARD.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) |
| Débogage du lancement des équipes d'agents | [docs/team-management/debugging-agent-teams.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) |
## Organisation des fonctionnalités
Les fonctionnalités moyennes et grandes doivent résider sous `src/features/<feature-name>/` et suivre le standard d'architecture des fonctionnalités. Gardez les éléments internes d'une fonctionnalité derrière des points d'entrée publics, et évitez les imports profonds qui traversent les frontières entre fonctionnalités.
Pour tout nouveau travail, partez de la slice `src/features/recent-projects` existante comme implémentation de référence locale. Les petits correctifs peuvent rester proches du chemin de code existant lorsque créer une slice de fonctionnalité ajouterait plus de structure que de valeur.
## Frontières runtime et fournisseur
Agent Teams possède l'orchestration : équipes, tâches, messages, état de lancement, interface de revue, diagnostics et persistance locale.
Le chemin runtime/fournisseur sélectionné possède l'exécution du modèle, l'authentification, la disponibilité du modèle, les limites de débit, la sémantique des outils et les preuves de transcription spécifiques au runtime. Ne faites pas en sorte que les prompts ou l'état de l'interface compensent une authentification manquante, des binaires manquants, des identifiants de modèle rejetés ou des pannes de fournisseur. Pour les détails de configuration côté utilisateur, voir [Fournisseurs et runtimes](/fr/reference/providers-runtimes).
## Débogage des équipes d'agents
En cas de blocage au lancement, d'états OpenCode `registered` / bootstrap non confirmé, de réponses de coéquipiers manquantes ou de journaux de tâches suspects, partez du runbook de débogage dédié. Inspectez l'artefact d'échec de lancement le plus récent sous `~/.claude/teams/<team>/launch-failure-artifacts/latest.json`, puis corrélez l'état de l'interface avec les fichiers persistés et les preuves spécifiques au runtime.
Évitez les nettoyages larges pendant le débogage. N'arrêtez que le processus, la lane, l'équipe ou l'exécution de smoke test que vous pouvez identifier comme appartenant au problème.
## Conventions des contributeurs
- Utilisez `pnpm dev` pour l'application de bureau Electron pendant le développement normal.
- N'utilisez pas le mode dev navigateur comme substitut au runtime de bureau, à l'IPC, au terminal, à l'authentification du fournisseur ou au comportement du cycle de vie d'une équipe.
- Gardez séparées les responsabilités d'Electron main, preload, renderer, shared et des fonctionnalités.
- Utilisez `wrapAgentBlock(text)` pour les blocs réservés aux agents au lieu de concaténer manuellement les marqueurs.
- Privilégiez une vérification ciblée. Évitez les `lint:fix` larges ou le brassage de formatage à moins que la tâche ne porte explicitement sur le formatage.
- Traitez le parsing, le cycle de vie des tâches, la détection fournisseur/runtime, la persistance, l'IPC, Git et les flux de revue comme des zones à haut risque qui nécessitent des tests ciblés ou un chemin de vérification clair.
## Pages connexes
- [Configuration du runtime](/fr/guide/runtime-setup)
- [Dépannage](/fr/guide/troubleshooting)
- [Revue de code](/fr/guide/code-review)
- [Confidentialité et données locales](/fr/reference/privacy-local-data)

95
landing/product-docs/fr/reference/faq.md Normal file
View file

@ -0,0 +1,95 @@
---
title: FAQ – Documentation Agent Teams
description: Foire aux questions sur Agent Teams — tarification, accès aux modèles, runtimes, confidentialité, revue et dépannage.
lang: fr-FR
---
# FAQ
## Agent Teams est-il gratuit ?
Oui. L'application est gratuite et open source. L'accès au fournisseur ou au runtime peut tout de même engendrer des coûts selon ce que vous utilisez.
## Agent Teams inclut-il l'accès aux modèles ?
Non. Agent Teams est la couche locale d'orchestration et d'interface utilisateur. L'accès aux modèles provient du chemin runtime/fournisseur sélectionné, tel que Claude Code, Codex ou OpenCode.
## Quels runtimes sont pris en charge ?
Les chemins de runtime pris en charge sont Claude Code, Codex et OpenCode. L'application suit également des identifiants de fournisseur tels qu'Anthropic, Codex, Gemini et OpenCode lorsque le runtime les expose.
## Dois-je d'abord installer Claude Code ou Codex ?
Pas toujours. L'application guide la détection et la configuration du runtime depuis l'interface utilisateur. Certains chemins nécessitent tout de même une authentification de runtime externe.
La configuration d'OpenCode est distincte de celle de Claude Code et Codex. Si un lancement échoue, vérifiez l'état du runtime et l'authentification du fournisseur avant de modifier le prompt de l'équipe.
## Comment vérifier si un runtime est prêt ?
Exécutez d'abord la commande du runtime dans un terminal :
```bash
claude --version
codex --version
opencode --version
```
Confirmez ensuite l'authentification du fournisseur pour le chemin que vous avez sélectionné. Si la commande ou la vérification d'authentification échoue en dehors d'Agent Teams, corrigez la configuration avant de lancer une équipe.
## Mon code est-il téléversé vers les serveurs d'Agent Teams ?
Non. Agent Teams n'est pas un service de synchronisation de code dans le cloud. Les appels de modèle adossés à un fournisseur peuvent recevoir le contexte du prompt selon le runtime que vous avez sélectionné.
## Où les fichiers d'équipe sont-ils stockés ?
Les données de coordination d'équipe sont stockées localement dans `~/.claude/teams/<team>/` (macOS/Linux) ou `%APPDATA%\Claude\teams\<team>\` (Windows), les fichiers de tâches dans `~/.claude/tasks/<team>/` ou `%APPDATA%\Claude\tasks\<team>\`, et les données de session de projet dans `~/.claude/projects/<encoded-project>/` lorsqu'elles sont disponibles.
## Qu'est-ce qui peut quitter ma machine ?
Le contexte du prompt, le contenu des fichiers sélectionnés, les résultats d'outils, la sortie des commandes, le texte des tâches, les commentaires et les pièces jointes peuvent quitter votre machine via le chemin runtime/fournisseur lorsqu'un agent utilise un modèle adossé à un fournisseur. Le comportement exact dépend du runtime et du fournisseur.
## Les agents peuvent-ils communiquer entre eux ?
Oui. Les agents peuvent envoyer des messages à leurs coéquipiers, commenter des tâches, se coordonner entre équipes et utiliser des références de tâches pour garder les conversations rattachées au travail.
## Que dois-je mettre dans le premier prompt d'équipe ?
Donnez au lead un résultat concret, des limites de fichiers ou de fonctionnalités, des limites de risque et des attentes de vérification. Par exemple :
```text
Improve the docs quickstart. Keep edits inside landing/product-docs, add practical examples, and run `pnpm --dir landing docs:build` before marking work done.
```
## Puis-je examiner le code avant de l'accepter ?
Oui. Le flux de revue s'articule autour de diffs cadrés par tâche et de décisions au niveau du hunk.
## Qu'est-ce qu'un Agent Block ?
Un Agent Block est un texte caché réservé aux agents, encadré par des marqueurs tels que `<info_for_agent>...</info_for_agent>`. L'application le retire de l'affichage normal destiné à l'utilisateur, mais le conserve disponible pour la coordination entre agents.
## Qu'est-ce que le mode solo ?
Le mode solo est une équipe à un seul agent. Il est utile pour les tâches plus petites et pour réduire la surcharge de coordination.
## Dois-je utiliser l'isolation par worktree ?
Utilisez-la lorsque plusieurs coéquipiers OpenCode peuvent modifier le même projet Git en parallèle. Elle réduit les conflits de fichiers, mais elle nécessite un projet suivi par Git et s'applique actuellement aux membres OpenCode.
## Différents coéquipiers peuvent-ils utiliser différents fournisseurs ?
Oui, les réglages de fournisseur/modèle peuvent être transportés par membre d'équipe lorsque le chemin runtime sélectionné les prend en charge. OpenCode est le principal chemin pour un routage multi-fournisseur étendu.
## Pourquoi une tâche affiche-t-elle review ou approved séparément de done ?
L'état du travail et l'état de revue sont liés mais ne sont pas identiques. Une tâche peut être done du point de vue de l'agent, puis passer par les étapes review et approval dans l'interface kanban.
## Que dois-je faire lorsqu'un lancement reste bloqué ?
Ouvrez le dépannage, collectez les diagnostics de lancement, vérifiez `~/.claude/teams/<team>/`, et vérifiez l'authentification du runtime/fournisseur avant de modifier les prompts.
Pour OpenCode, vérifiez les preuves de lane/session avant de supposer qu'un coéquipier est en ligne mais ignore les messages.
## Pourquoi les journaux diffèrent-ils selon les runtimes ?
Claude Code, Codex et OpenCode exposent des formats de transcription et des preuves de runtime différents. Agent Teams normalise ce qu'il peut, mais l'exhaustivité des journaux et l'attribution peuvent varier selon le runtime.

82
landing/product-docs/fr/reference/privacy-local-data.md Normal file
View file

@ -0,0 +1,82 @@
---
title: Confidentialité et données locales – Documentation Agent Teams
description: Ce qu'Agent Teams stocke localement, ce qui peut quitter votre machine via les appels de modèles adossés à un fournisseur, et des conseils pratiques en matière de confidentialité.
lang: fr-FR
---
# Confidentialité et données locales
Agent Teams privilégie le local, mais le chemin runtime/fournisseur sélectionné a toujours son importance. Cette page décrit ce que l'application de bureau stocke localement et ce qui peut quitter votre machine lorsque les agents appellent des modèles adossés à un fournisseur.
## Ce qui reste local
L'application de bureau s'exécute sur votre machine et lit les données locales de projet/runtime pour alimenter l'interface. Les données locales typiques comprennent :
- les fichiers de projet
- la configuration de l'équipe et les métadonnées des membres
- les métadonnées de tâches, les commentaires de tâches et les références de tâches
- les messages de la boîte de réception
- les journaux de runtime/session
- l'état de lancement et les diagnostics de bootstrap
- l'état des revues
- les paramètres locaux de l'application
Les emplacements locaux importants comprennent :
| Plateforme | Emplacement | Objet |
| --- | --- | --- |
| macOS/Linux | `~/.claude/teams/<team>/` | Configuration de l'équipe, métadonnées des membres, boîtes de réception, état de lancement, preuves de bootstrap, diagnostics de runtime, enregistrements des messages envoyés, état du kanban et fichiers d'équipe liés aux revues. |
| Windows | `%APPDATA%\Claude\teams\<team>\` | Idem — configuration de l'équipe, métadonnées des membres, boîtes de réception, état de lancement et diagnostics. |
| macOS/Linux | `~/.claude/tasks/<team>/` | Fichiers JSON de tâches durables pour le tableau de l'équipe. |
| Windows | `%APPDATA%\Claude\tasks\<team>\` | Idem — fichiers JSON de tâches durables. |
| macOS/Linux | `~/.claude/projects/<encoded-project>/` | Fichiers de session de projet de style Claude/Codex utilisés pour l'historique des sessions, l'analyse de contexte et l'interface adossée aux transcriptions. |
| Windows | `%APPDATA%\Claude\projects\<encoded-project>\` | Idem — fichiers de session de projet. |
Les fichiers exacts peuvent varier selon le runtime et la version de l'application. Pour le débogage de lancement, les preuves les plus récentes se trouvent généralement sous le dossier `~/.claude/teams/<team>/` pertinent (ou `%APPDATA%\Claude\teams\<team>\`).
## Ce qui peut quitter votre machine
Agent Teams en lui-même n'est pas un service de synchronisation de code dans le cloud pour votre dépôt. Il n'a pas besoin de téléverser l'intégralité de votre projet vers un serveur Agent Teams pour afficher le tableau, la boîte de réception, les journaux ou l'interface de revue.
Cependant, lorsqu'un agent demande à un modèle adossé à un fournisseur de travailler, le contexte du prompt, le contenu des fichiers sélectionnés, le texte des tâches, les commentaires, les résultats d'outils, la sortie de commandes et d'autres contextes fournis par le runtime peuvent être envoyés via le chemin runtime/fournisseur sélectionné. Ce qui est envoyé dépend du runtime, du modèle, des appels d'outils, du prompt et de la configuration du fournisseur.
L'authentification auprès du fournisseur, la rétention côté fournisseur, l'entraînement, la journalisation, le traitement régional et la facturation sont régis par le fournisseur/runtime que vous choisissez. Examinez ces politiques pour les projets sensibles.
Exemples courants :
| Action | Données pouvant être envoyées via le runtime/fournisseur |
| --- | --- |
| Demander à un agent de modifier un fichier | Le prompt de la tâche, le contenu pertinent du fichier, les résultats d'outils et la sortie de commandes |
| Joindre une capture d'écran | Le contenu de la pièce jointe et le texte de tâche/commentaire environnant |
| Demander une revue de code | Le contexte du diff, les fichiers sélectionnés, les commentaires et les journaux de vérification |
| Déboguer une commande en échec | La sortie d'erreur, les traces d'appel et les extraits de code source référencés |
## Ce que l'application ne garantit pas
- Elle ne peut pas garantir que les appels de modèles adossés à un fournisseur ne reçoivent jamais de code privé.
- Elle ne peut pas outrepasser les politiques de rétention ou de facturation du fournisseur.
- Elle ne peut pas faire en sorte qu'un fournisseur distant se comporte comme un modèle entièrement local.
- Elle ne peut pas protéger les secrets qu'un agent reçoit l'instruction de coller dans des prompts, des commentaires de tâches, des fichiers ou des commandes.
- Elle ne peut pas faire en sorte que chaque runtime expose le même niveau de détail de transcription ou d'audit.
## Conseils pratiques
- Ne joignez pas de secrets aux tâches, commentaires ou messages directs.
- Examinez les politiques du fournisseur pour les projets sensibles.
- Utilisez un niveau d'autonomie plus faible pour les dépôts à risque.
- Gardez un périmètre de tâche étroit lorsque vous travaillez avec du code privé.
- Privilégiez les preuves et journaux locaux lors du débogage.
- Vérifiez les prompts générés, les descriptions de tâches et les fichiers joints avant de demander aux agents de travailler sur du matériel confidentiel.
- Utilisez des chemins fournisseur/modèle qui correspondent à vos exigences de confidentialité.
Avant d'utiliser Agent Teams sur un dépôt sensible :
1. Retirez les secrets de l'arbre de travail et des pièces jointes de tâches
2. Choisissez le chemin runtime/fournisseur que vous êtes autorisé à utiliser
3. Commencez avec une faible autonomie et de petites tâches
4. Examinez les prompts de tâches et les commentaires générés avant d'élargir le périmètre
5. Gardez les journaux en local sauf si vous les partagez intentionnellement pour obtenir de l'aide
## Modèle open source
L'application elle-même est open source et gratuite. Vous pouvez examiner le fonctionnement de l'orchestration locale, du suivi des tâches, des boîtes de réception, des diagnostics de runtime et des flux de revue dans le dépôt.

115
landing/product-docs/fr/reference/providers-runtimes.md Normal file
View file

@ -0,0 +1,115 @@
---
title: Fournisseurs et runtimes – Documentation Agent Teams
description: Chemins de runtime pris en charge (Claude Code, Codex, OpenCode), identifiants de fournisseur, nommage des modèles, stratégies multi-fournisseurs et vérifications de capacités.
lang: fr-FR
---
# Fournisseurs et runtimes
Agent Teams sépare l'orchestration de l'accès aux modèles. L'application gère les équipes, les tâches, les messages, l'état de lancement et l'interface de revue ; le chemin runtime/fournisseur sélectionné effectue le travail réel du modèle.
## Ce que fournit l'application
Agent Teams fournit :
- l'orchestration des équipes et des tâches
- l'interface du tableau kanban
- la messagerie entre coéquipiers
- les journaux de tâches
- l'interface de revue
- l'intégration des projets locaux
- la détection du runtime et les vérifications de capacités
- les journaux et diagnostics locaux
## Ce que fournit le runtime
Le runtime fournit :
- l'exécution du modèle
- l'authentification du fournisseur
- le comportement d'exécution des outils
- les limites de débit et les capacités spécifiques au modèle
- les transcriptions et les preuves de livraison spécifiques au runtime
## Chemins de runtime pris en charge
| Chemin de runtime | Chemin fournisseur/modèle | Idéal pour | Notes |
| --- | --- | --- | --- |
| Claude Code | Anthropic / modèles Claude | Utilisateurs de Claude Code et flux de travail adossés à Anthropic | Chemin local-first par défaut pour les équipes Claude. Nécessite que le runtime et l'accès au compte soient disponibles localement. |
| Codex | Codex / modèles adossés à OpenAI | Flux de travail natifs Codex | Utilise l'intégration du runtime Codex et l'état d'authentification/de compte Codex lorsqu'ils sont disponibles. Certains diagnostics diffèrent des transcriptions Claude. |
| OpenCode | Routage de modèles géré par OpenCode | Équipes multi-fournisseurs et large couverture de modèles | OpenCode peut router à travers de nombreux fournisseurs de modèles. Agent Teams traite les voies OpenCode comme des preuves spécifiques au runtime et évite de deviner lorsque l'identité de la voie est ambiguë. |
Gemini est disponible comme chemin de fournisseur pris en charge avec l'authentification Google ADC (gcloud auth), l'OAuth de Gemini CLI et par clé API. Il apparaît aux côtés des autres fournisseurs dans l'interface de création d'équipe et de configuration du runtime lorsque le runtime le signale comme disponible.
## Identifiants de fournisseur
L'application reconnaît actuellement ces identifiants de fournisseur dans la configuration d'équipe/runtime :
| Identifiant de fournisseur | Intention d'affichage |
| --- | --- |
| `anthropic` | Chemin Anthropic / Claude Code |
| `codex` | Chemin Codex |
| `gemini` | Chemin du fournisseur Gemini (Google ADC, Gemini CLI ou clé API) |
| `opencode` | Chemin OpenCode, y compris le routage de fournisseur géré par OpenCode |
Ne considérez pas ce tableau comme une garantie que chaque fournisseur est authentifié, installé ou disponible pour chaque modèle sur chaque machine. L'état du runtime et les vérifications de capacités font foi pour un lancement donné.
## Identifiants de modèle
Les identifiants de modèle sont transmis au runtime sélectionné. Agent Teams ne réécrit pas le catalogue de modèles d'un fournisseur dans un schéma de nommage universel.
Exemples :
| Chemin fournisseur | Exemple d'identifiant de modèle | Notes |
| --- | --- | --- |
| Claude Code | `opus`, `sonnet`, ou un identifiant de modèle Claude complet | La disponibilité dépend de Claude Code et de l'accès au compte |
| Codex | `gpt-5.4`, `gpt-5.3-codex` | La disponibilité provient de l'état du compte/runtime Codex |
| OpenCode | `openrouter/moonshotai/kimi-k2.6` | Le préfixe doit correspondre à une configuration de fournisseur OpenCode |
Si un nom de modèle est rejeté, vérifiez-le d'abord directement dans le runtime/fournisseur. Modifier un brief d'équipe ne peut pas rendre lançable un modèle indisponible.
## Stratégie multi-fournisseurs
Agent Teams maintient une orchestration consciente du fournisseur mais sans en dépendre :
- les équipes, les tâches, les boîtes de réception, les commentaires, l'état de revue et les diagnostics de lancement restent dans le stockage local d'Agent Teams
- chaque membre peut porter des paramètres de fournisseur/modèle via les métadonnées de lancement d'équipe
- la disponibilité des modèles, l'authentification, les limites de débit et le comportement des outils restent des responsabilités du runtime/fournisseur
- OpenCode est le chemin de routage le plus large lorsque vous souhaitez qu'une seule équipe utilise plusieurs voies de fournisseur/modèle
Pour les frontières destinées aux contributeurs et les conseils d'implémentation canoniques, voir [Architecture pour les contributeurs](/fr/reference/contributor-architecture).
Modèles recommandés :
| Modèle | Quand il aide | Risque |
| --- | --- | --- |
| Un seul fournisseur pour tous les membres | Premier lancement, dépôts sensibles, débogage le plus simple | Des limites de débit partagées peuvent arrêter toute l'équipe |
| Lead solide + constructeurs moins coûteux | Garder la planification/revue fiable tout en réduisant le coût d'implémentation | La sortie des constructeurs peut nécessiter une revue plus stricte |
| Modèles distincts pour le constructeur et le relecteur | Détecter les angles morts spécifiques à un modèle | Plus de configuration et d'attribution à inspecter |
## Coûts des fournisseurs
Agent Teams est gratuit et open source. Vous pouvez démarrer avec le modèle gratuit inclus sans authentification - sans inscription, clés API ni carte de crédit. L'utilisation de fournisseurs payants ou adossés à un compte est régie par le runtime/fournisseur que vous sélectionnez : limites d'abonnement, clés API, authentification de compte, limites de débit et politiques de fournisseur restent toutes externes à l'application.
## Vérifications de capacités
Lors de la configuration, l'application peut effectuer des vérifications d'accès et de capacités. Cela aide à détecter une authentification de runtime manquante avant qu'un lancement d'équipe n'échoue à mi-parcours du provisionnement.
Les vérifications de capacités peuvent signaler qu'un fournisseur existe mais n'est pas authentifié, qu'une liste de modèles est indisponible, qu'un chemin de runtime est manquant, ou qu'une capacité d'extension spécifique n'est pas prise en charge. Traitez ces résultats comme des diagnostics de configuration, pas comme des échecs de tâche.
Correctifs de configuration typiques :
| Résultat de la vérification | Que faire |
| --- | --- |
| Runtime manquant | Installer la CLI ou corriger le `PATH` |
| Fournisseur non authentifié | Lancer le flux de connexion du fournisseur ou ajouter la clé API requise |
| Modèle indisponible | Choisir un modèle visible dans la liste des modèles de ce runtime |
| Capacité non prise en charge | Utiliser un autre chemin de runtime pour ce coéquipier |
## Limites à prévoir
- La prise en charge d'un runtime ne signifie pas une parité de fonctionnalités égale entre Claude Code, Codex et OpenCode.
- La couverture des journaux et des transcriptions diffère selon le runtime.
- Les voies OpenCode ont besoin de preuves de voie/session stables avant que l'application puisse attribuer les journaux de runtime en toute sécurité.
- Les noms et la disponibilité des modèles des fournisseurs peuvent changer en dehors de l'application.
- Un prompt d'équipe ne peut pas corriger une authentification manquante, des entrées PATH manquantes, des pannes de fournisseur ou des limites de débit épuisées.

42
landing/product-docs/fr/reference/release-notes.md Normal file
View file

@ -0,0 +1,42 @@
---
title: Notes de version – Documentation Agent Teams
description: Notes de version et journal des modifications d'Agent Teams. Liens vers les fichiers canoniques RELEASE.md et CHANGELOG.md pour tous les détails.
lang: fr-FR
---
# Notes de version
Version actuelle : **v1.2.0** (2026-03-31). Le développement actif se poursuit sur la branche `main` avec des modifications non publiées concernant la synchronisation du travail des membres, le renforcement de la livraison OpenCode et la stabilisation de la CI.
## Comment fonctionnent les versions
Agent Teams suit le [versionnage sémantique](https://semver.org/). Les tags poussés sur le dépôt déclenchent un [workflow de publication](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) automatisé qui construit des paquets signés pour macOS, Windows et Linux, puis les publie sur GitHub Releases.
## Versions récentes
### v1.2.0 — Agent Graph, approbation des outils par équipe, AskUserQuestion interactif
Agent Graph avec visualisation à forces dirigées et disposition des tâches en kanban, contrôles d'approbation des outils par équipe avec des invites de permission lisibles, notifications de commentaires de tâche et boutons AskUserQuestion interactifs. Refonte du système de permissions avec préchargement de Write/Edit/NotebookEdit et intégration du catalogue d'outils MCP. Voir le [journal des modifications complet](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#120---2026-03-31).
### v1.1.0 — React 19 + Electron 40, démarrages de tâche initiés par l'utilisateur
Migration vers React 19 + Electron 40, démarrages de tâche initiés par l'utilisateur depuis le tableau kanban, guide de dépannage de l'authentification, coloration syntaxique pour R/Ruby/PHP/SQL, recherche dans les transcriptions 3x plus rapide, corrections des chemins WSL/Windows et correctif d'une vulnérabilité XSS. Voir le [journal des modifications complet](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#110---2026-03-25).
### v1.0.0 — Première version publique
Première build stable : fiabilité de la CLI et de l'authentification dans les applications packagées, renforcement de l'IPC, packaging multiplateforme avec builds macOS signées, documents de gouvernance open source (LICENSE, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY). Voir le [journal des modifications complet](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#100---2026-03-23).
## Sources canoniques
| Document | Description |
| --- | --- |
| [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) | Processus de publication, guide de versionnage, nommage des artefacts, configuration des mises à jour automatiques et modèle de notes de version. |
| [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) | Journal des modifications complet avec toutes les versions, fonctionnalités, améliorations et corrections de bugs du point de vue de l'utilisateur. |
| [GitHub Releases](https://github.com/777genius/agent-teams-ai/releases) | Installeurs téléchargeables pour toutes les plateformes. |
## Pages connexes
- [Installation](/fr/guide/installation)
- [Démarrage rapide](/fr/guide/quickstart)
- [Architecture pour les contributeurs](/fr/reference/contributor-architecture)
- [Développeurs](/fr/developers/)

69
landing/product-docs/ja/developers/index.md Normal file
View file

@ -0,0 +1,69 @@
---
title: 開発者ハブ – Agent Teams ドキュメント
description: Agent Teams のアーキテクチャ、ガードレール、デバッグ、MCP による拡張方法に関する、コントリビューターと開発者向けの入口です。
lang: ja-JP
---
# 開発者ハブ
Agent Teams 自体を変更したい場合、チームの起動をデバッグしたい場合、または MCP ツールでランタイムを拡張したい場合は、このページを参照してください。以下のリンクは正規のリポジトリドキュメントを指しており、実装ルールが一箇所にまとまるようになっています。
## はじめに
| 必要なこと | 参照先 |
| --- | --- |
| リポジトリの概要、スクリプト、ソースのセットアップ | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) |
| エージェントのナビゲーションとアーキテクチャの索引 | [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) |
| エージェントとコントリビューターのための作業規約 | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) |
| 厳格な実装ガードレール | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) |
| 中規模および大規模な機能の構成 | [機能アーキテクチャ標準](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) |
| 起動、ブートストラップ、チームメイトのメッセージングのデバッグ | [エージェントチームのデバッグ用ランブック](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) |
| コントリビューションのプロセス | [コントリビューションガイド](https://github.com/777genius/agent-teams-ai/blob/main/.github/CONTRIBUTING.md) |
| リリースノート / 変更履歴 | [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) — [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) |
## ローカル開発の手順
通常の開発では、デスクトップ版の Electron アプリを実行します。
```bash
pnpm install
pnpm dev
```
ブラウザ/Web 版はデスクトップランタイムの代替にはなりません。デスクトップモードがサポートされたローカルの手順です。これには IPC、ターミナル、プロバイダー認証、チームのライフサイクル処理、起動診断、そして実際のチームで使われるランタイムブリッジが含まれているためです。
## アーキテクチャのチェックポイント
機能を変更する前に、その境界を特定してください。
| 領域 | 想定される配置場所 |
| --- | --- |
| 中規模または大規模なプロダクト機能 | `src/features/<feature-name>/` |
| Electron メインプロセスのオーケストレーション | `src/main/` |
| preload で安全な API サーフェス | `src/preload/` |
| レンダラーの UI とアプリの状態 | `src/renderer/` |
| 共有の型と純粋なヘルパー | `src/shared/` |
| Agent Teams ボードの MCP サーバー | `mcp-server/` |
| ボードのデータコントローラー | `agent-teams-controller/` |
機能の構成については、`src/features/recent-projects` をリファレンスとなるスライスとして使用してください。プロセス間のコントラクトは明示的に保ち、機能の境界をまたいだ深いインポートは避けてください。
## デバッグの手順
起動のハング、OpenCode の `registered` / bootstrap-unconfirmed 状態、チームメイトの返信の欠落、または不審なタスクログが発生した場合は、次の手順に従ってください。
1. [デバッグ用ランブック](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) から始めます。
2. `~/.claude/teams/<team>/launch-failure-artifacts/latest.json` にある最新のアーティファクトパックを確認します。
3. アーティファクトの `manifest.json` を開き、`classification`、ブートストラップのブレッドクラム、起動診断、メンバーのスポーン状態、伏字処理されたログの末尾を確認します。
4. スモークテストまたは失敗した起動が所有していると特定できるチーム、実行、ペイン、プロセスのみをクリーンアップします。
## MCP 開発の手順
Agent Teams は、ボード操作のために `agent-teams` という名前の組み込み MCP サーバーを使用します。ユーザーおよびプロジェクトの MCP サーバーは、ランタイムに外部機能を追加できます。セットアップの例、`.mcp.json` の構造、ツール登録のガイダンスについては、[MCP 連携](/ja/guide/mcp-integration) を参照してください。
## 関連ドキュメント
- [コントリビューター向けアーキテクチャ](/ja/reference/contributor-architecture)
- [ランタイムの設定](/ja/guide/runtime-setup)
- [MCP 連携](/ja/guide/mcp-integration)
- [トラブルシューティング](/ja/guide/troubleshooting)

121
landing/product-docs/ja/guide/agent-workflow.md Normal file
View file

@ -0,0 +1,121 @@
---
title: エージェントのワークフロー – Agent Teams ドキュメント
description: タスクのライフサイクル、かんばんボード、メッセージ、タスクログ、並列作業、ライブプロセス、チーム間コミュニケーションについて理解します。
lang: ja-JP
---
# エージェントのワークフロー
Agent Teams は、エージェントの作業をタスクの状態、メッセージ、ログ、レビュー可能なコード変更として可視化します。
## モード
| モード | 説明 |
| --- | --- |
| ソロ | 自己管理タスクを持つ 1 人のチームメイト |
| チーム | 並列で作業し、互いにレビューし合う複数のチームメイト |
どちらのモードも、同じかんばん、タスクログ、コードレビューの画面を共有します。
## タスクのライフサイクル
Agent Teams は、各タスクを 2 つの独立した次元で追跡します。それは作業ステータスとレビュー状態です。
| 次元 | 状態 | 説明 |
| --- | --- | --- |
| 作業ステータス | `pending`、`in_progress`、`completed` | タスクが待機中か、実際に作業中か、オーナーによって完了されたかを追跡します |
| レビュー状態 | `none`、`review`、`needsFix`、`approved` | 完了後のレビューフローのどの段階にタスクがあるかを追跡します |
かんばんボードはこれらを組み合わせたビューを表示しますが、2 つの次元は独立して動きます。
### 作業ステータスのフロー
| 段階 | 何が起こるか | オーナー |
| --- | --- | --- |
| Pending | タスクが作成されて準備完了だが、まだ誰も作業を開始していない | リードまたはユーザー |
| In progress | エージェントが作業し、ボードの MCP ツールでタスクの状態を更新する | チームメイト |
| Completed | オーナーが結果コメントを投稿し、タスクを done としてマークする | チームメイト |
### レビュー状態のフロー
| 段階 | 何が起こるか | オーナー |
| --- | --- | --- |
| None | タスクはまだレビュー中ではない（pending、in progress、または新しく completed の可能性がある） | — |
| Review | レビューが依頼され、レビュアーが差分と結果を確認する | レビュアー |
| Needs fix | レビュー中に変更が依頼され、オーナーが更新する必要がある | チームメイト（オーナー） |
| Approved | レビューに合格し、タスクが確定する | レビュアー |
### 計画 → In progress
チームメイトがタスクを開始すると、作業ステータスは `in_progress` になります。エージェントは自身の計画を記したタスクコメントを作成し、作業を続けます。すべてのネイティブツールのアクション（read、bash、edit、write）はタスクログにストリーミングされます。
### Completed → Review
チームメイトが作業を終えると、結果コメントを投稿し、作業ステータスを `completed` としてマークします。その後、リードまたはレビュアーがレビューを依頼してレビューフローを開始できます。
### Review → Approved
レビュー画面に表示された変更が問題なければ、レビューを承認します。タスクは確定され、その差分にひも付けられます。
::: warning 修正優先のレビュー
レビュー中にチームメイトへ変更が依頼された場合、チームメイトは修正内容を記したフォローアップコメントを投稿し、その後リードが承認できるようにすべきです。
:::
## かんばんボード
ボードは主要な操作画面です。次のことができます。
- オープン中、ブロック中、レビュー中の作業を一覧で確認する
- タスク詳細を開いてランタイムログを確認する
- 生のセッションファイルを読まずに変更をレビューする
- オーナーを割り当てる、または再割り当てする
::: tip
カードのクイックアクションボタンを使えば、詳細パネルを開かずにタスクの開始、完了、レビュー依頼ができます。
:::
## メッセージとコメント
| チャネル | 使うタイミング |
| --- | --- |
| ダイレクトメッセージ | エージェントの方向を修正する、簡単な質問をする |
| タスクコメント | 特定のタスクに属するメモ |
コメントは後のレビューのためにコンテキストを保持し、タスクのタイムラインに表示されます。
::: tip タスクコメントを優先する
特定のタスクに関する指摘であれば、ダイレクトメッセージを送るのではなく、そのタスクへのコメントとして追加してください。履歴を作業にひも付けたまま保てます。
:::
## タスクログ
タスク固有のログは、1 つの割り当てに関するランタイム出力、アクション、メッセージを切り分けます。次のことを把握するために使います。
- このエージェントは何を実行したか？
- なぜこのファイルを変更したのか？
- 別のチームメイトに助けを求めたか？
- どのタスクがこの差分を生み出したか？
### 検証チェックリスト
タスクが行き詰まっているように見えたり、その差分が切り離されているように見えたりするときは、次の順序でライフサイクルを確認します。
1. タスクに想定どおりのオーナーがいて、`in_progress` に移っている。
2. オーナーが計画または最初の進捗更新を記したタスクコメントを投稿している。
3. タスクログにタスクのウィンドウ内のランタイムアクティビティが表示されている。
4. ファイルの変更が同じタスク、オーナー、セッションにひも付いている。
5. 最終のタスクコメントに検証コマンドとその結果が含まれている。
より深いデバッグについては、[トラブルシューティング](/ja/guide/troubleshooting#task-log-triage)にある永続化された証跡のコマンドを使ってください。UI は作業用の画面ですが、永続化されたタスクファイル、受信トレイ、ランタイムの証跡が、起動や帰属に関する深刻なバグを解明するための情報源です。
## 並列作業のパターン
チームメイトは独立したタスクを同時に進められます。依存関係のリンク（`blocked-by`）を作成して、あるタスクが別のタスクの完了まで待つようにすることもできます。ボードでブロック中のレーンを監視し、一方のチームメイトがアイドル状態でもう一方が過負荷になっている場合はオーナーを再割り当てしてください。
## ライブプロセス
ライブプロセスのセクションは、エージェントがローカルサーバーやツールを起動したときに、URL と実行中のプロセスを表示します。アプリから直接 URL を開いて結果を確認できます。プロセスは、明示的に停止されるかランタイムが終了するまで登録されたままになります。
## チーム間コミュニケーション
チームがリンクされていると、エージェントは他のチームへメッセージを送れます。これはハンドオフ、共有ライブラリ、またはチーム間のステータス確認に使います。

119
landing/product-docs/ja/guide/code-review.md Normal file
View file

@ -0,0 +1,119 @@
---
title: コードレビュー – Agent Teams ドキュメント
description: タスク単位の差分を確認し、ハンクを承認または却下し、インラインコメントを残し、none から approved までのレビュー状態を管理します。
lang: ja-JP
---
# コードレビュー
Agent Teams のコードレビューはタスク中心です。大きな構造化されていない差分を探し回るのではなく、特定のタスクで何が変更されたかを確認します。
## レビュー画面
ファイルに変更があった完了済みタスクごとに、レビュー UI では次のことができます。
- 変更前後のコンテキスト付きで変更されたファイルを確認する
- 個々のハンクを承認または却下する
- インラインコメントを残す
- 差分をタスクの説明やエージェントのログと結びつける
## ハンク単位の判断
正しい小さな変更は承認し、孤立したミスはタスク全体を捨てることなく却下できます。これは、エージェントがおおむねタスクを解決したものの、1 つのファイルでやりすぎてしまった場合に便利です。
::: tip 段階的に承認する
差分がおおむね正しい場合は、まず良いハンクを承認し、修正が必要な部分についてのみ変更をリクエストしてください。これによってボードが滞りなく進みます。
:::
ハンク単位の判断は次の場面で使います。
| 状況 | アクション |
| --- | --- |
| 正しく範囲が絞られた変更 | ハンクを承認する |
| 考え方は正しいが、ファイルが違うか広範なリファクタリング | ハンクを却下し、より範囲を絞った修正をリクエストする |
| 不明瞭な挙動の変更 | コメントして検証を求める |
| 生成されたフォーマットのノイズ | フォーマットがタスクの一部でない限り却下する |
## レビューの開始
1. 完了済みのタスクを開く
2. **Changes** タブを見る
3. 差分が妥当に見えたら、**Request Review** をクリックしてタスクを review 列に移動する
レビュー中、タスクはまだ done とはみなされないため、他のチームメイトやリードはまだコメントできます。
## レビューループ
健全なレビューループは次のようになります。
1. オーナーが変更範囲と検証内容を記載した結果コメントを投稿する
2. レビュアーがタスクの差分を開き、タスクの説明と照らし合わせてハンクを確認する
3. レビュアーが良いハンクを承認し、悪いハンクを却下するか、変更をリクエストする
4. オーナーがリクエストされた範囲のみを修正し、フォローアップのコメントを投稿する
5. タスクの結果と差分が一致したら、レビュアーが承認する
変更リクエストのコメント例:
```text
Please keep the copy improvements, but revert the unrelated runtime wording in the provider table. Add the `pnpm --dir landing docs:build` result before resubmitting.
```
## レビュー状態
| 状態 | 意味 |
| --- | --- |
| `none` | タスクが新規、in progress、または完了済みだがまだレビュー中ではない |
| `review` | タスクがアクティブにレビュー中である |
| `needsFix` | 変更がリクエストされた。オーナーは再承認の前に更新する必要がある |
| `approved` | レビューが承認され、タスクが確定した |
## エージェントによるレビューのワークフロー
チームは、あなたが最終判断を下す前にお互いの作業をレビューできます。これによって明らかなリグレッションを検出し、ボードを健全に保てますが、リスクの高い領域は依然として自分自身でレビューすべきです。
エージェントによるレビューは、レビュアーが明確な基準を持っているときに最も役立ちます。たとえば、ドキュメントの明瞭さのみ、IPC の安全性のみ、あるいはテストカバレッジのみを確認するようレビュアーに指示します。漠然とした「すべてをレビューして」というリクエストは、弱いフィードバックになりがちです。
### MCP 駆動のレビュー状態
レビュー状態の変更（レビューのリクエスト、変更のリクエスト、承認）はツール駆動です。タスクに「変更をリクエスト」のコメントを残しても、かんばんの列は `needsFix` に移動**しません**。リードまたはエージェントが適切な MCP ツールを呼び出す必要があります。
- `review_request_changes` — タスクを `needsFix` に移動し、オーナーに通知する
- `review_approve` — タスクを `approved` に移動し、レビューを確定する
コメントだけでは状態遷移には不十分です。レビュー用 MCP ツールの完全な一覧とそのパラメーターについては、[MCP 連携](/ja/guide/mcp-integration)を参照してください。
## レビューの参加者
チームリードがデフォルトのレビュアーです。仲間同士でお互いの作業をレビューさせたい場合は、かんばん設定で追加のレビュアーを設定できます。
## 手動で確認すべきこと
レビューの際は次の領域を優先してください。
- **プロバイダー認証とランタイム検出** — エージェントは他のパスを壊すような形でランタイムのセットアップを変更していないか？
- **IPC、preload、ファイルシステムの境界** — Electron の責務を分離したままにする
- **Git と worktree の挙動** - ブランチの命名、コミット、プッシュを検証する。分離のパターンについては [Git と worktree の戦略](/ja/guide/git-worktree-strategy)を参照してください。
- **パースとタスクライフサイクルのロジック** — タスク参照、チャンク化、フィルタリングへの変更はメッセージ配信を壊す可能性がある
- **永続化とコードレビューのフロー** — タスクストレージやレビュー状態への変更は IPC レイヤー全体で一貫している必要がある
正規の機能レイアウトとハードガードレールへのリンクについては、[コントリビューター向けアーキテクチャ](/ja/reference/contributor-architecture)を使用してください。
## 検証
範囲を絞った検証コマンドを優先してください。広範なフォーマットや lint-fix コマンドは、タスクが明示的に広範なフォーマットの変更を意図している場合を除き、使用すべきではありません。
良い検証コメントにはコマンドと結果が含まれます。
```text
Verified with `pnpm --dir landing docs:build`. Build passed.
```
検証を省略する場合は、その理由をタスクのコメントに記載すべきです。
```text
Docs-only wording change. Build not run because the existing dev server was busy; checked Markdown links manually.
```
::: warning プロジェクト全体に対する自動フォーマットは行わない
タスクが特にフォーマットに関するものでない限り、無関係なファイルに対して `pnpm lint:fix` を実行するのは避けてください。レビュー画面にノイズを生み出します。
:::

106
landing/product-docs/ja/guide/create-team.md Normal file
View file

@ -0,0 +1,106 @@
---
title: チームの作成 – Agent Teams ドキュメント
description: ロールを定義し、プロバイダーとモデルを割り当て、チームブリーフを作成し、worktree の分離と自律性のレベルを設定します。
lang: ja-JP
---
# チームの作成
チームとは、ロール、リード、対象プロジェクト、そして調整用プロンプトを備えた、名前付きのエージェントのグループです。
## 推奨する最初のチーム
小規模なチームから始めましょう。
| ロール | 目的 |
| -------- | --------------------------------------------------- |
| Lead | 作業を分割し、タスクを作成し、チームメイトを調整します |
| Builder | 範囲を絞ったタスクを実装します |
| Reviewer | 出力をレビューし、リグレッションを検出し、修正を求めます |
この構成は、最初の起動を騒がしくすることなく、プロダクトの価値を確認できるだけの調整能力をもたらします。
::: tip
メンバーは後から追加できます。小さく始めてワークフローを検証し、それからスケールアップしましょう。
:::
## プロバイダーとモデルの割り当て
各チームメンバーはプロバイダーのバックエンド上で動作します。チームエディターで、すべてのメンバーについてプロバイダー（Claude、Codex、または OpenCode）とモデルを選択します。アプリには、すでに認証済みのプロバイダーのみが表示されます。
1 つのチーム内でプロバイダーを混在させることもサポートされています。たとえば、Claude のリードに OpenCode のビルダーを組み合わせることができます。
::: info
Gemini はサポートされているプロバイダーのパスとして利用できます。認証オプションと現在のプロバイダーの状況については、[プロバイダーとランタイム](/ja/reference/providers-runtimes) を参照してください。
:::
## 優れたチームブリーフを書く
チームブリーフには次の内容を含めるべきです。
- 望む成果
- 重要なファイルまたは機能領域
- 「関係のないモジュールをリファクタリングしない」といったリスクの境界
- レビューに関する期待
- 把握している場合は検証用のコマンド
例：
```text
Build a focused improvement to the download flow. Keep changes inside the landing app unless a shared helper is clearly needed. Create tasks before implementation, review each task diff, and run landing lint/build checks.
```
## worktree の分離
OpenCode のメンバーは、**worktree の分離**を使用して、メインの作業ディレクトリではなく別の Git worktree で作業できます。これにより、複数のエージェントが同じプロジェクトを編集する際のファイル競合を防ぎます。
::: warning
worktree の分離には Git で追跡されているプロジェクトが必要であり、現在は OpenCode のメンバーに限定されています。
:::
有効にするには、OpenCode のチームメンバーを追加または編集する際に **Worktree isolation** オプションを切り替えます。
## 自律性の選択
Agent Teams はさまざまなレベルの制御をサポートしています。ルーチンな変更にはより高い自律性を、プロバイダー認証、IPC、永続化、Git ワークフロー、リリースツールといったリスクの高い領域にはより厳格なレビューを使用してください。
### エフォートレベル
各チームメンバーには、プロバイダーが応答する前にどれだけの推論を投じるかを制御する**エフォート**設定があります。エフォートを高くすると、時間とトークンを消費する代わりに、より徹底した出力が得られます。
| レベル | 使いどころ |
| ------ | ---------------------------------------------------------- |
| Low | 簡単な調査、小さな書式変更、ルーチンな編集 |
| Medium | ほとんどの実装タスクのデフォルト |
| High | 複雑なリファクタリング、横断的な変更、リスクの高いコードパス |
アプリは、対応しているプロバイダー向けに追加のレベル（minimal、xhigh、max）も提供します。モデルが設定可能なエフォートをサポートしていない場合、セレクターは無効化され、プロバイダーのデフォルトが使用されます。
### ファストモード
メンバーごとに **Fast mode** を切り替えると、深さよりも速度を優先します。これは、利用可能な場合にプロバイダーのネイティブな fast/speed モードに対応します。ルーチンなタスクには **On**、慎重な作業には **Off**、チームレベルのデフォルトに従う場合は **Inherit** に設定します。
### コンテキストの制限
**Limit context** を有効にすると、メンバーのコンテキストウィンドウを縮小できます。これは拡張コンテキスト（たとえば 1M トークン）をサポートする Claude モデルで役立ちます。コンテキストを制限することで、不要なトークン使用を回避でき、大きなコンテキストを必要としないタスクのレイテンシを改善できます。
## コンテキストの追加
タスクを実質的に変える場合は、ファイル、スクリーンショット、または具体的なメモを添付します。エージェントは、タスクの説明、コメント、添付ファイルを永続的なコンテキストとして利用できます。
## タスクの品質に注意する
優れたチームは、次のようなタスクを作成します。
- レビューできる程度に具体的である
- 完了できる程度に小さい
- 目に見える出力にひも付いている
- 検証パスに裏付けられている
リードが曖昧なタスクを作成する場合は、より小さくテスト可能なタスクを求めるダイレクトメッセージを送りましょう。
## 次のステップ
- [ランタイムの設定](/ja/guide/runtime-setup) — プロバイダー認証とモデルを設定します
- [コードレビュー](/ja/guide/code-review) — エージェントの変更を承認、却下、またはコメントします
- [トラブルシューティング](/ja/guide/troubleshooting) — よくある問題と修正

102
landing/product-docs/ja/guide/git-worktree-strategy.md Normal file
View file

@ -0,0 +1,102 @@
---
title: Git と worktree の戦略 – Agent Teams ドキュメント
description: 並列でのエージェント作業において、メインの worktree、機能ブランチ、OpenCode の worktree 分離のどれを使うべきかを判断します。
lang: ja-JP
---
# Git と worktree の戦略
Git は Agent Teams に最も強力なレビュー経路をもたらします。差分が狭く、ブランチを把握でき、変更がタスク単位にスコープされ、並列作業をより安全に行えます。
## 戦略を選ぶ
| 戦略 | 使うべき場面 | トレードオフ |
| --- | --- | --- |
| メイン worktree | 単独での作業、ドキュメントのみの編集、または一度に 1 人のチームメイトのみ | シンプルだが、並列編集が衝突する可能性がある |
| 機能ブランチ | 1 つのチームが 1 つのまとまった変更に取り組んでいる | レビュー対象がクリーンになるが、チームメイトは依然としてファイルを共有する |
| worktree 分離 | 複数の OpenCode のチームメイトが同じリポジトリを並列で編集する可能性がある | 分離は向上するが、マージ/レビューにより多くの規律が必要になる |
シンプルに始めましょう。worktree 分離は、すべてのタスクに別々のチェックアウトが必要だからではなく、並列編集が起こりそうなときに追加します。
## worktree 分離を有効にするタイミング
OpenCode のチームメイトに対して、次の場合に有効にします。
- 2 人以上のチームメイトが同じリポジトリを同時に編集する可能性がある
- タスクがフォーマッター、コードジェネレーター、または広範なテストを実行する可能性がある
- 各チームメイトのブランチと差分を分離した状態に保ちたい
- リードのワークスペースがダーティであり、直接の編集を受け取るべきでない
次の場合はオフのままにします。
- タスクが読み取り専用である
- 1 人のチームメイトがすべての編集を担当する
- リポジトリが Git で追跡されていない
- この分離モードをサポートしないランタイム経路が必要である
::: warning
worktree 分離は現在 OpenCode のメンバーに適用され、Git で追跡されたプロジェクトが必要です。
:::
## ブランチの衛生
並列作業を始める前に行います。
```bash
git status --short
git branch --show-current
```
可能な場合はクリーンなブランチを使いましょう。メイン worktree にすでにユーザーの変更がある場合は、無関係なファイルを元に戻さないようエージェントに伝え、タスクの範囲を狭く保ちます。
推奨されるブランチのスタイル:
```text
agent/<team-or-task>/<short-purpose>
```
例:
```text
agent/docs/mcp-guide
agent/review/task-log-filtering
agent/ui/code-review-polish
```
## レビューの流れ
分離された worktree については、マージしたり変更をメインのワークスペースに適用し直したりする前に、チームメイトの差分をレビューします。
1. タスクの結果コメントが、変更されたスコープと検証内容を明示していることを確認します。
2. レビュー UI でタスクの差分を確認します。
3. 差分が無関係なファイルに触れている場合は、そのタスクに対して変更を依頼します。
4. テストまたは手動チェックがタスクのリスクに見合った場合にのみ承認します。
5. 慎重にマージまたは変更を適用します。
タスクが完了したというだけで worktree の出力を自動マージしないでください。完了とは、エージェントがその作業をレビューする準備が整ったと考えていることを意味します。
## コンフリクトのポリシー
並列チームには次のポリシーを使います。
| 状況 | 対応 |
| --- | --- |
| 2 人のチームメイトが同じファイルを編集する | 一方のタスクを一時停止するか、1 人を統合の責任者にする |
| 生成ファイルが広範に変更された | ジェネレーターとコマンドを説明するコメントを必須にする |
| メイン worktree に無関係な変更がある | それらを保持し、タスクが所有する変更のみをレビューする |
| worktree のブランチが分岐している | レビューの後に手動でリベースまたはマージし、あいまいなエージェントタスクの中では行わない |
## タスクプロンプトの例
```text
Implement the settings validation fix in your assigned worktree. Keep edits inside src/features/settings and focused tests. Do not touch provider auth or task storage. Post the test command and result before completing the task.
```
このプロンプトがうまく機能するのは、許可された領域、機微な境界、完了の証拠を明示しているからです。
## 関連ガイド
- [チームの作成](/ja/guide/create-team)
- [コードレビュー](/ja/guide/code-review)
- [チームブリーフの例](/ja/guide/team-brief-examples)
- [ランタイムの設定](/ja/guide/runtime-setup)

129
landing/product-docs/ja/guide/installation.md Normal file
View file

@ -0,0 +1,129 @@
---
title: インストール – Agent Teams ドキュメント
description: macOS、Windows、Linux 向けの Agent Teams をダウンロードしてインストールします。パッケージ済みビルド、ソースからのセットアップ、自動更新、必要要件について説明します。
lang: ja-JP
---
# インストール
Agent Teams は、macOS、Windows、Linux 向けのデスクトップアプリとして配布されています。
::: tip 最短の手順
1. 以下からお使いのプラットフォーム向けのビルドをダウンロードします
2. アプリを起動します。認証不要の無料モデルから始めるか、UI からプロバイダー認証を接続します
3. [クイックスタート](/ja/guide/quickstart) を開始して、最初のチームを作成します
デスクトップアプリの起動: Electron アプリは `pnpm dev` で実行します。通常の利用ではブラウザ/Web の開発モードを起動しないでください。
:::
## ビルドのダウンロード
パッケージ済みアプリが必要な場合は、<a href="/ja/download/" target="_self">ダウンロードページ</a> または最新の [GitHub リリース](https://github.com/777genius/agent-teams-ai/releases) をご利用ください。
- macOS Apple Silicon: `.dmg`
- macOS Intel: `.dmg`
- Windows: `.exe`
- Linux: `.AppImage`、`.deb`、`.rpm`、または `.pacman`
::: warning Windows SmartScreen
署名されていない、または公開されたばかりのオープンソースアプリは、SmartScreen をトリガーすることがあります。リリース元を信頼できる場合は、**More info** を選択し、続いて **Run anyway** を選択してください。
:::
## 必要要件
パッケージ済みアプリは、セットアップ不要のオンボーディングを目的として設計されています。認証不要の無料モデルから始められます。登録、API キー、クレジットカードは不要です。さらに多くのモデルを利用したい場合は、アプリが UI からランタイム検出とプロバイダー認証をガイドします。
有料またはアカウント連携のモデルを利用するには、少なくとも 1 つのプロバイダーを接続してください。
| プロバイダー | アクセス方法 |
| ------------------ | ------------------------------------------------- |
| Claude (Anthropic) | Claude Code CLI ログインまたは API キー |
| Codex (OpenAI) | Codex CLI ログインまたは API キー |
| Gemini (Google) | Google ADC、Gemini CLI、または API キー |
| OpenCode | 認証不要で同梱されている無料モデル、または対応するバックエンド（例: OpenRouter）向けの API キー |
::: info
Gemini は対応プロバイダーの一つとして利用できます。すべてのプロバイダーにわたる認証オプションと現在のステータスについては、[プロバイダーとランタイム](/ja/reference/providers-runtimes) を参照してください。
:::
ソースからの開発には、さらに以下が必要です。
| ツール | バージョン |
| ------- | ------- |
| Node.js | 24.16.0 LTS |
| pnpm | 10+ |
macOS では、公式の Node.js 24 プリビルドバイナリには macOS 13.5+ が必要です。
## ソースから実行する
<InstallBlock command="git clone https://github.com/777genius/agent-teams-ai.git && cd agent-teams-ai && pnpm install && pnpm dev" label="コピー" copied-label="コピーしました" />
```bash
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
pnpm dev
```
`pnpm dev` は、ホットリロード付きのデスクトップ Electron アプリを起動します。これがデフォルトの開発ターゲットです。通常の開発ではブラウザ Web 開発サーバーを起動しないでください。ブラウザ経路には、完全なデスクトップ IPC、ターミナル、プロバイダー認証、チームライフサイクルの挙動がありません。
`main` ブランチには、最新の安定した開発成果が含まれています。特定の未リリースの変更が必要な場合にのみ、フィーチャーブランチに切り替えてください。
## セットアップの確認
インストール後、ビルドが健全であることを確認します。
```bash
# デスクトップアプリがコンパイルされ、起動することを確認します
pnpm typecheck
# VitePress ドキュメントサイトがビルドされることを確認します
pnpm --dir landing docs:build
```
`pnpm typecheck` が型エラーを報告する場合は、依存関係やピン留めされた TypeScript の新しいバージョンを確認してください。`pnpm --dir landing docs:build` が失敗する場合は、`landing/product-docs/` を調べて、markdown や設定の構文エラーを確認してください。
これらのドキュメントを編集している場合は、ビルドを実行して変更を確認してください。
```bash
pnpm --dir landing docs:build
```
## 自動更新
パッケージ済みアプリは、起動時および実行中に定期的に、更新を自動でチェックします。更新が利用可能になると、アプリがダウンロードとインストールを促します。アプリメニューから手動でチェックすることもできます。
::: tip
ソースから実行している場合、自動更新は利用できません。依存関係が変更されたときは、最新の変更をプルして `pnpm install` を再実行してください。
:::
## ソースからの更新
ソースから実行している場合は、`main` ブランチをプルし、依存関係が変更されたときはインストールを再実行してください。
```bash
git pull
pnpm install
```
更新後、ビルドとドキュメントを確認してください。
```bash
pnpm typecheck
pnpm --dir landing docs:build
```
通常の開発では、ブラウザ開発サーバーではなく、常に `pnpm dev`（Electron）を使用してください。
## 次のステップ
- [クイックスタート](/ja/guide/quickstart) — インストールから最初に稼働するチームまで
- [ランタイムの設定](/ja/guide/runtime-setup) — ランタイムごとのプロバイダー認証とモデル選択
- [チームの作成](/ja/guide/create-team) — 推奨されるチーム構成とブリーフの書き方
### コントリビューター向け
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — リポジトリのナビゲーションとアーキテクチャのポインタ
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — 作業上の慣例とプロジェクトのルール
- [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) — 厳格な実装ガードレール

225
landing/product-docs/ja/guide/mcp-integration.md Normal file
View file

@ -0,0 +1,225 @@
---
title: MCP 連携 – Agent Teams ドキュメント
description: ボード操作、チームメイトの連携、外部ツールサーバー、カスタムツール開発のために Agent Teams で MCP を設定します。
lang: ja-JP
---
# MCP 連携
Agent Teams は MCP を 2 つの実践的なレイヤーで利用します。
| レイヤー | 役割 | 利用者 |
| --- | --- | --- |
| 組み込みボードサーバー | Agent Teams のタスク、メッセージ、レビュー、プロセス、ランタイム、クロスチームのツールを公開します | アプリが起動したリードとチームメイト |
| 外部 MCP サーバー | ブラウザ自動化、デザインコンテキスト、ドキュメント検索、社内システムなどの任意のツールを追加します | ユーザーと設定済みのランタイム |
これらのレイヤーは分けて考えてください。組み込みの `agent-teams` MCP サーバーは、エージェントが Agent Teams 内で連携するための仕組みです。外部 MCP サーバーは任意のランタイムツールです。
## Agent Teams が MCP を注入する仕組み
デスクトップアプリが Claude ベースのチームメンバーを起動すると、組み込みの `agent-teams` サーバーを含む一時的な `--mcp-config` JSON ファイルが書き出されます。
```json
{
"mcpServers": {
"agent-teams": {
"command": "node",
"args": ["/path/to/agent-teams-mcp/index.js"],
"env": {
"AGENT_TEAMS_MCP_CLAUDE_DIR": "/Users/you/.claude"
}
}
}
}
```
開発環境では、このコマンドは `tsx` を介して `mcp-server/src/index.ts` を指す場合があります。パッケージ化されたビルドでは、アプリがバンドルされた MCP サーバーを安定したアプリデータパスにコピーし、Node で実行します。生成されるファイルはアプリが所有し、ベストエフォートでクリーンアップされます。
ユーザーおよびプロジェクトの MCP サーバーは引き続き分離されます。アプリはインストール済みのサーバーを次の場所から読み込みます。
| スコープ | 場所 |
| --- | --- |
| ユーザー | `~/.claude.json` の `mcpServers` 配下 |
| Claude 設定内のローカルプロジェクトエントリ | `~/.claude.json` の `projects[projectPath].mcpServers` 配下 |
| プロジェクト | `<project>/.mcp.json` の `mcpServers` 配下 |
1 つのリポジトリに属するツールにはプロジェクトスコープを優先してください。無関係な複数のプロジェクトで再利用するツールにはユーザースコープを優先してください。
## プロジェクトの `.mcp.json` の例
チームが同じプロジェクトスコープのサーバーを参照すべき場合は、このファイルをプロジェクトのルートに配置します。
```json
{
"mcpServers": {
"docs-search": {
"command": "npx",
"args": ["-y", "@acme/docs-search-mcp"],
"env": {
"DOCS_INDEX_PATH": "./docs-index"
}
},
"local-browser": {
"command": "node",
"args": ["./tools/mcp/browser-server.js"]
}
}
}
```
コミットされる `.mcp.json` ファイルにシークレットを含めないでください。値をローカルに保持する必要がある場合は、認証情報をシェル、ユーザースコープの設定、またはアプリのカスタム MCP インストールフローに保存してください。
## ボード MCP のワークフロー
作業がタスクに属する場合、エージェントはボード MCP ツールを使用すべきです。
1. 最新のタスクコンテキストを読み取ります。
2. 実際に作業を始めるときにのみタスクを開始します。
3. ブロッカー、計画、最終結果についてタスクコメントを追加します。
4. 結果コメントを投稿した後にタスクを完了としてマークします。
5. リードやチームメイトが結果を知る必要があるときは、短いメッセージを送ります。
エージェントのフローの例:
```text
task_get -> task_start -> edit/test -> task_add_comment -> task_complete -> message_send
```
連携にはダイレクトメッセージを使用してください。永続的なタスク履歴にはタスクコメントを使用してください。
::: tip
そのメモがレビュー、検証、範囲の変更、ブロッカーに関わる場合は、タスクに記載してください。
:::
## 組み込みの Agent Teams ツール
MCP サーバーは `agent-teams-controller/src/mcpToolCatalog.js` からツールを登録します。登録ループは `mcp-server/src/tools/index.ts` にあり、各グループは `mcp-server/src/tools/` 配下に独自のファイルを持ちます。
一般的な運用ツール:
| ツール | 用途 |
| --- | --- |
| `task_get` | タスクの最新のコンテキスト、コメント、添付ファイル、ステータス、関連を読み取ります |
| `task_start` | 作業が実際に始まったときにタスクを in progress としてマークします |
| `task_add_comment` | ブロッカーのメモ、検証メモ、計画、最終結果の要約を追加します |
| `task_complete` | 最終結果コメントを投稿した後にタスクを完了します |
| `message_send` | リード、チームメイト、ユーザーに表示されるインボックスメッセージを送ります |
| `review_request`、`review_start`、`review_approve`、`review_request_changes` | タスクスコープのレビューワークフローを進めます |
| `process_register`、`process_list`、`process_stop`、`process_unregister` | チームメイトが所有する開発サーバー、ウォッチャー、その他のバックグラウンドサービスを追跡します |
ツール名は、ランタイムには `mcp__agent-teams__task_get` のように MCP 名前空間のプレフィックス付きで表示される場合があります。MCP サーバー内の正規のツール名は引き続き `task_get` です。
## 新しい組み込みツールの登録
Agent Teams リポジトリでの作業では、既存の FastMCP 構造を通じて組み込みのボードツールを追加します。
1. ツールの実装を `mcp-server/src/tools/` 内の該当ファイルに追加するか、ドメインが本当に新しい場合は新しいグループファイルを作成します。
2. ツール名を `agent-teams-controller/src/mcpToolCatalog.js` 内の適切なグループに追加します。
3. 新しいドメイングループが必要な場合にのみ、新しいグループを `mcp-server/src/tools/index.ts` を通じて配線します。
4. `zod` で入力を検証し、ボードファイルを直接読み取る代わりにコントローラー API を呼び出します。
5. `mcp-server/test/tools.test.ts` に焦点を絞ったテストを追加するか、トランスポートが重要な場合は e2e ケースを追加します。
最小限の形:
```ts
server.addTool({
name: 'task_example',
description: 'Explain what this tool does for agents.',
parameters: z.object({
teamName: z.string().min(1),
claudeDir: z.string().min(1).optional(),
taskId: z.string().min(1)
}),
execute: async ({ teamName, claudeDir, taskId }) => {
assertConfiguredTeam(teamName, claudeDir);
const controller = getController(teamName, claudeDir);
return jsonTextContent(controller.tasks.getTask(taskId));
}
});
```
コントローラーの検証を回避するツール、無関係なチームファイルを変更するツール、狭いタスク上の必要性なしに広範なファイルシステム/プロセスアクセスを公開するツールは作成しないでください。
## 外部 MCP サーバー
チームメイトが、コンテキストを貼り付けた単発のプロンプトだけでなく、永続的なツール接続を必要とする場合は、外部 MCP サーバーを使用してください。
適している用途:
- ブラウザまたはウェブサイトのテストツール
- デザインまたはプロダクトデータのツール
- 社内ドキュメントおよび検索システム
- 課題トラッカーまたはサポートシステム
- 読み取り専用の認証情報を使ったデータベース検査ツール
適さない用途:
- プロンプトに貼り付けられたシークレット
- 直接添付できる単発のファイル
- レビューなしに本番システムを変更するツール
- より狭いプロジェクトスコープで十分な場合の広範なローカルファイルシステムアクセス
## スコープ
Agent Teams は、共有スコープとプロジェクト指向の MCP スコープを認識します。
| スコープ | 使用する場面 |
| --- | --- |
| User または Global | 同じサーバーを複数のプロジェクト間で利用できるようにすべき場合 |
| Project または Local | サーバーが 1 つのリポジトリ、ワークスペース、またはチームコンテキストに属する場合 |
ワークフローが引き続き利用可能でありながら、最も狭いスコープを優先してください。プロジェクトスコープのサーバーは、ツールが変更対象のプロジェクトに属するため、レビュー時に把握しやすくなります。
## セットアップのチェックリスト
MCP サーバーに依存するタスクを割り当てる前に:
1. サーバーをインストールまたは設定します。
2. 意図したスコープで、アプリのインストール済み MCP リストに表示されることを確認します。
3. 利用可能な場合は、MCP レジストリまたは拡張機能 UI から診断を実行します。
4. 低リスクの読み取り専用タスクから始めます。
5. 想定される MCP ツールの使用を、タスクの説明またはチームブリーフに記載します。
サーバーが診断に失敗した場合は、まずそれを修正してください。タスクプロンプトを改善しても、欠落したコマンド、誤った設定パス、拒否された認証情報は修復できません。
## アプリからカスタムサーバーをインストールする
デスクトップアプリは、検索、ブラウズ、インストール、カスタムインストール、アンインストール、インストール状態の読み取り、診断のために、Electron IPC を通じて MCP レジストリ API を公開します。カスタムインストールは、ランタイムのインストールパスを呼び出す前に、サーバー名、スコープ、プロジェクトパス、環境変数名、HTTP ヘッダーを検証します。
レジストリにまだ存在しない MCP パッケージがある場合は、カスタムインストールを使用してください。
| フィールド | 例 |
| --- | --- |
| サーバー名 | `docs-search` |
| スコープ | このリポジトリには `project`、すべてのプロジェクトには `user` |
| タイプ | ローカルコマンドには `stdio`、リモートサーバーには `http` または `sse` |
| パッケージ | `@acme/docs-search-mcp` |
| 環境変数 | `DOCS_INDEX_PATH=./docs-index` |
インストール後は診断を実行し、より大きな作業を割り当てる前に、小さな読み取り専用タスクを作成してツールの表面を検証してください。
## タスクの例
```text
Audit the docs home page with the browser MCP. Check desktop and mobile widths, capture any layout issue as a task comment, and only edit landing/product-docs files. Run `pnpm --dir landing docs:build` before completion.
```
これが機能するのは、ツール、対象範囲、書き込みの境界、検証ステップを明示しているからです。
## 安全のためのルール
- デフォルトですべてのチームメイトにすべての MCP サーバーを与えないでください。
- レビューで必要とされない限り、書き込み可能なツールを広範なチームから除外してください。
- 検査タスクには読み取り専用の認証情報を優先してください。
- 本番に影響するツールの使用は、明示的なタスクコメントとレビューの背後に置いてください。
- MCP の診断失敗は、エージェントの失敗ではなくセットアップの失敗として扱ってください。
- `.mcp.json` やプロンプトにシークレットをコミットしないでください。
- アプリを通じてプロジェクトスコープのサーバーをインストールする際は、絶対パスの `projectPath` の値を使用してください。
- アプリが生成する `agent-teams-mcp-*.json` ファイルは編集しないでください。これらは一時的な起動アーティファクトです。
## 関連ガイド
- [ランタイムの設定](/ja/guide/runtime-setup)
- [チームブリーフの例](/ja/guide/team-brief-examples)
- [エージェントのワークフロー](/ja/guide/agent-workflow)
- [開発者向け](/ja/developers/)

193
landing/product-docs/ja/guide/quickstart.md Normal file
View file

@ -0,0 +1,193 @@
---
title: クイックスタート – Agent Teams ドキュメント
description: 新規インストールから稼働中の AI エージェントチームまでを数分で立ち上げます。インストール、ランタイムの選択、チームの作成、最初のコードレビューを扱います。
lang: ja-JP
---
# クイックスタート
このガイドでは、新規インストールから稼働中のチームまでを数分で立ち上げます。
## 最短ルート
```bash
# 1. Install prerequisites
node --version # need 20+
pnpm --version # need 10+
# 2. Clone and install
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
# 3. Start the desktop app (default workflow)
pnpm dev
# 4. Verify a docs-only change
pnpm --dir landing docs:build
```
デスクトップ版の Electron アプリ（`pnpm dev`）が主要なターゲットです。通常の開発ではブラウザ/Web 開発サーバーを使用しないでください。ブラウザ経由のパスには、デスクトップ IPC、ターミナル、プロバイダー認証、チームのライフサイクル動作がありません。
## はじめる前に
必要なもの:
- **コンピューター** — macOS、Windows、または Linux で動作するもの
- **（推奨）Git で追跡されているプロジェクト** — worktree の分離や差分レビューは Git に依存します
- **（任意）プロバイダーアクセス** — ランタイムの設定では UI から利用可能なプロバイダーを検出しますが、一部のパスには既存の認証（Anthropic、OpenAI など）が必要です
以下の手順がうまくいかない場合は、[トラブルシューティングガイド](/ja/guide/troubleshooting#team-does-not-launch)で一般的な対処法を確認してください。
プロジェクトの規約やアーキテクチャに関するガイダンスについては、変更を加える前にこれらの正規ファイルを参照してください:
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — リポジトリのナビゲーションとアーキテクチャの指針
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — 作業上の規約とプロジェクトのルール
- [機能アーキテクチャ標準](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) — 新機能の構成
- [デバッグ用ランブック](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) — 起動とチームメイトの診断
## 1. ソースから実行する、またはダウンロードする
**パッケージ済みアプリをダウンロード**して、macOS、Windows、または Linux 向けに<a href="/ja/download/" target="_self">ダウンロードページ</a>から入手できます。前提条件は不要です。認証なしの無料モデルから始めることも、より多くのモデルを使いたいときに UI からプロバイダー認証を接続することもできます。
**または開発用にソースから実行**します:
Node.js 24.16.0 LTS と pnpm 10+ が必要です。macOS では、公式の Node.js 24 のプレビルドバイナリは macOS 13.5+ を必要とします。
```bash
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
pnpm dev
```
`pnpm dev` は、ホットリロード付きのデスクトップ版 Electron アプリを起動します。これがデフォルトの開発ターゲットです。通常の開発ではブラウザ Web 開発サーバーを起動しないでください。ブラウザ経由のパスには、完全なデスクトップ IPC、ターミナル、プロバイダー認証、チームのライフサイクル動作がありません。
## 2. プロジェクトを開く、または作成する
アプリを起動し、エージェントに作業させたいプロジェクトディレクトリを選択します。Agent Teams はローカルのプロジェクトファイルとランタイム/セッションの状態を読み取り、UI 上でタスク、ログ、差分、チームメイトのアクティビティを表示できるようにします。
::: tip
最良の体験を得るには、Git で追跡されているプロジェクトを選んでください。worktree の分離と差分ベースのレビューはどちらも Git に依存します。
:::
チームを起動する前に、プロジェクトが十分にクリーンなベースラインを持っているか確認してください:
```bash
git status --short
```
完全にクリーンなツリーである必要はありませんが、エージェントが編集を始める前に、どの変更が自分のものかを把握しておくべきです。これにより、タスクの差分やハンク単位のレビューがはるかに信頼しやすくなります。
## 3. ランタイムのパスを選ぶ
セットアップフローは、マシンにインストールされているランタイムを自動検出します。最初によく使われるセットアップは次のとおりです:
| ランタイム | 適した用途 |
| -------- | ----------------------------------------------- |
| Claude | Claude Code ユーザーや既存の Anthropic アクセス |
| Codex | Codex ネイティブのワークフローや OpenAI アクセス |
| OpenCode | 認証なしの無料モデル、マルチモデルチーム、多数のプロバイダーバックエンド |
::: info
Gemini はサポートされているプロバイダーパスとして利用できます。認証オプションと現在のプロバイダーの状況については、[プロバイダーとランタイム](/ja/reference/providers-runtimes)を参照してください。
:::
各プロバイダーの詳細な設定については、[ランタイムの設定](/ja/guide/runtime-setup)を参照してください。
有料またはアカウントに紐づくランタイムをアプリの外で検証するには、バイナリを確認し、認証をテストします:
```bash
# Check that the runtime is installed and on PATH
command -v claude && claude --version
command -v codex && codex --version
command -v opencode && opencode --version
```
コマンドが失敗する場合は、まずランタイムのインストールまたは `PATH` を修正してください。バイナリが見つからない場合や、それを必要とするモデルのプロバイダー認証が欠けている場合、チームのプロンプトでは回避できません。
::: tip
バイナリは見つかるのにアプリが「not logged in」と報告する場合、ターミナルとアプリで環境が異なっている可能性があります。両者を比較するには、[認証診断ログ](/ja/guide/troubleshooting#auth-diagnostic-log)を参照してください。
:::
## 4. 最初のチームを作成する
リードと 1 名以上のスペシャリストでチームを作成します。最初のチームは小さく保ってください。リード 1 名、実装エージェント 1 名、レビュー担当エージェント 1 名で、ワークフローを検証するには十分です。
推奨される構成とヒントについては、[チームの作成](/ja/guide/create-team)を参照してください。
最初の起動では、次のようなチーム構成が望ましいです:
| メンバー | 担当 | 備考 |
| --- | --- | --- |
| Lead | ゴールをタスクに分割し、ステータスを調整する | 手持ちの最も信頼できるプロバイダーに割り当てる |
| Builder | スコープが定まったタスクを実装する | ファイルや機能の明確な境界を与える |
| Reviewer | 完了した作業をレビューする | リグレッションと不足しているテストに注目するよう依頼する |
最初から 5 名以上のチームメイトで始めるのは避けてください。エージェントが増えると、セットアップが健全だと確認できる前に、並行処理、ログ、プロバイダー使用量、競合のリスクが増大します。
## 5. リードに具体的なゴールを与える
エンジニアリングリードに指示を出すのと同じようにゴールを書きます:
```text
Improve the onboarding flow. Split the work into tasks, keep changes small, and ask for review before broad refactors.
```
優れた最初のプロンプトには、具体的なスコープ、安全のための境界、検証が含まれます:
```text
Improve the docs quickstart. Keep edits inside landing/product-docs. Add practical examples, preserve existing VitePress syntax, and run `pnpm --dir landing docs:build` before marking tasks done.
```
最初の実行では、「アプリをもっと良くして」のような曖昧なプロンプトは避けてください。リードは大きなゴールを分解できますが、より良い入力ほど、より小さなタスクとよりクリーンなレビューを生み出します。
::: tip
チームは起動するのにタスクが表示されない場合は、リードがあなたのプロンプトを受け取ったかどうかを確認してください。診断については、[エージェントの返信が見当たらない](/ja/guide/troubleshooting#agent-replies-are-missing)を参照してください。
:::
リードはタスクを作成し、作業を割り当て、チームメイトを調整します。進捗はかんばんボードで確認でき、いつでもコメントやダイレクトメッセージで介入できます。
## 6. 結果をレビューする
完了したタスクやレビュー可能なタスクを開き、差分を確認して、個々の変更を承認、却下、またはコメントします。エージェントがなぜその選択をしたのかを理解する必要がある場合は、タスクログを使用してください。
レビューの完全なワークフローについては、[コードレビュー](/ja/guide/code-review)を参照してください。
最初のタスクを承認する前に、次の 3 点を確認してください:
1. タスクコメントが何を変更したかを説明している
2. 変更されたファイルがタスクのスコープと一致している
3. 検証結果がタスクコメントまたはログで確認できる
## よくある落とし穴
| 症状 | 考えられる原因 | 確認すること |
| --- | --- | --- |
| アプリがランタイムを検出しない | バイナリが `PATH` 上にない、またはアプリとターミナルで異なる環境が見えている | ターミナルで `command -v <runtime>` を実行し、同じターミナル環境を使ってアプリを起動する |
| チームの起動が止まる | 有料/アカウントモデルのプロバイダー認証が欠けている、モデル文字列が間違っている、またはランタイムバイナリが見つからない | [トラブルシューティング](/ja/guide/troubleshooting#team-does-not-launch)を参照 |
| OpenCode レーンが `registered` のまま止まる | レーンのエビデンスがまだコミットされていない、またはモデル文字列の不一致 | `~/.claude/teams/<team>/.opencode-runtime/lanes/` を確認する |
| エージェントの返信が見当たらない | ランタイム配信のリトライ、パース、またはタスク帰属の問題 | タスクログを開き、配信台帳を確認する |
| プロバイダーが 429 を返す | レート制限に達した | リセットを待つか、モデル/プロバイダーを切り替える |
## 次のステップ
- [チームの作成](/ja/guide/create-team) — 推奨されるチーム構成とブリーフの書き方
- [ランタイムの設定](/ja/guide/runtime-setup) — プロバイダー認証とモデルの選択
- [コードレビュー](/ja/guide/code-review) — レビュー、承認、または変更のリクエスト
### コントリビューター向け
Agent Teams またはこのドキュメントを変更する場合は、リポジトリのルートにある正規のプロジェクトファイルから始めてください:
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — 作業上の規約とプロジェクトのルール
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — アーキテクチャと実装ガイダンスのためのナビゲーション層
- [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) — 実装の厳格なガードレール
- [機能アーキテクチャ標準](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) — 新機能の構成
- [エージェントチームのデバッグ用ランブック](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) — 起動、ブートストラップ、チームメイトの診断
このドキュメントサイトが正しくビルドされることを確認するには:
```bash
pnpm --dir landing docs:build
```

179
landing/product-docs/ja/guide/runtime-setup.md Normal file
View file

@ -0,0 +1,179 @@
---
title: ランタイムの設定 – Agent Teams ドキュメント
description: Claude Code、Codex、または OpenCode ランタイムを設定します。認証、プロバイダーアクセス、マルチモデルモード、起動前チェックについて解説します。
lang: ja-JP
---
# ランタイムの設定
Agent Teams は調整レイヤーです。実際のモデル処理は、サポートされているローカルランタイムとプロバイダーを通じて実行されます。
::: tip クイックスタート - 最初のランタイムを選ぶ
| 次のような場合 | 最初に使うもの |
| --- | --- |
| すでに Claude Code を使っている、または Anthropic のアクセスがある | **Claude** - 慣れた認証で、最小限のセットアップ |
| Codex または OpenAI ベースのワークフローを使っている | **Codex** - ネイティブ連携 |
| サインアップや API キーなしで Agent Teams を試したい | **OpenCode** - 認証不要で同梱の無料モデルを使う |
| マルチモデルのルーティングや幅広いプロバイダー対応が欲しい | **OpenCode** - 最も柔軟で、1 つの設定で多くのバックエンドに対応 |
| どのランタイムが合うか分からない | **OpenCode** - 最も多くのプロバイダーの選択肢をカバーし、後から切り替えられる |
1 つのランタイムと 1 人のチームメイトから始めましょう。マルチモデルに拡張する前に、まずは 1 回の起動が動作することを確認してください。
:::
## 前提条件
チームを起動する前に、次の点を確認してください。
- ランタイムバイナリがインストールされ、`PATH` に含まれていること。
- 認証不要で同梱の無料 OpenCode モデルから始める場合を除き、プロバイダーアカウントが使用予定のモデルへの有効なアクセス権を持っていること。
- プロジェクトのパスが存在し、読み取り可能であること。
- 認証を手動でテストする際に、アプリとターミナルが同じホーム/設定環境を使用していること。
::: tip
1 人のチームメイトと 1 つのプロバイダーから始めましょう。マルチモデルレーンを追加する前に、まずは 1 回の起動が動作することを確認してください。
:::
ターミナルでの簡単なチェック:
```bash
command -v claude
command -v codex
command -v opencode
```
使用予定のランタイムに対応するコマンドを実行してください。何も出力されない場合は、チームを起動する前にランタイムをインストールするか `PATH` を修正してください。
## サポートされている経路
| 経路 | デフォルト CLI | 代表的なプロバイダー | 使用する場面 |
| --- | --- | --- | --- |
| Claude | `claude` | Anthropic | すでに Claude Code または Anthropic ベースのワークフローを使っている |
| Codex | `codex` | OpenAI | Codex ネイティブのランタイム連携が欲しい |
| OpenCode | `opencode` | OpenRouter および多数のバックエンド | マルチモデルのルーティングと幅広いプロバイダー対応が欲しい |
アプリはサポートされているランタイムを検出し、可能な場合は UI からセットアップをガイドします。
Gemini は、Google ADC（`gcloud auth`）、Gemini CLI の OAuth、API キー認証に対応した、サポート対象のプロバイダー経路として利用できます。Gemini バックエンドが検出されたら、ランタイム設定の UI から構成してください。
## プロバイダーアクセス
Agent Teams には独自の有料プランはありません。認証不要で同梱の無料 OpenCode モデルから始められます - 登録、API キー、クレジットカードは不要です。追加のモデルについては、すでにお持ちのプロバイダーアクセスを利用してください。選択する経路に応じて、サブスクリプション、ローカルランタイムの認証、または API キーを使います。
- **Claude** および **Codex** の経路は、それぞれの CLI 認証ツールに依存します。
- **OpenCode** は、まず認証不要で同梱の無料モデルを実行できます。その他の OpenCode モデルでは、設定ファイルにプロバイダー固有の API キーが必要になる場合があります（例: `openrouter`、`openai`、`anthropic`）。
## 認証の設定
### Claude Code
ターミナルで標準の認証フローを実行します。
```bash
claude login
```
次に、CLI に到達できることを確認します。
```bash
claude --version
```
ターミナルでは動作するのにパッケージ版アプリが「ログインしていません」と報告する場合は、アプリが認識している `$HOME` と `PATH` を、ログインに使用したターミナルのものと比較してください。[トラブルシューティング](/ja/guide/troubleshooting#auth-diagnostic-log) で説明している認証診断ログが、最良の出発点です。
### Codex
OpenAI の CLI フローでインストールと認証を行います。
```bash
codex login
```
次に、ランタイムに到達できることを確認します。
```bash
codex --version
```
Codex ネイティブの起動では、利用可能な場合に Codex アカウントの状態とモデルカタログのデータを使用します。UI にモデルが表示されない場合は、チームプロンプトを編集する前にプロバイダーのステータスを更新してください。
### OpenCode
認証不要で同梱の無料モデルを使うには、アプリ内で選択し、プロバイダーへのサインアップなしで起動します。その他の OpenCode バックエンドを使うには、`~/.opencode/config.json`（またはお使いのプラットフォームでの相当パス）を作成または編集し、使用したいプロバイダーキーを記述します。
```json
{
"providers": {
"openrouter": {
"apiKey": "sk-or-..."
}
}
}
```
OpenCode が想定する正確なプロバイダー名を使用してください。カスタムのプロバイダー名を設定した場合は、モデル文字列で使用するプロバイダー ID と照らし合わせて再確認してください（例えば `openrouter/moonshotai/kimi-k2.6` は `openrouter` ブロックを使用します）。
モデル文字列の例:
| モデル文字列 | 存在している必要があるプロバイダーブロック |
| --- | --- |
| `openrouter/moonshotai/kimi-k2.6` | `openrouter` |
| `openai/gpt-5.4` | `openai` |
| `anthropic/claude-sonnet-4-6` | `anthropic` |
OpenCode は起動するのにチームメイトが配信可能にならない場合は、モデルがプロンプトを無視したと判断する前にレーンの証跡を調べてください。[トラブルシューティング](/ja/guide/troubleshooting#opencode-registered-but-bootstrap-unconfirmed) を参照してください。
### Gemini
Gemini は 3 つの認証方法をサポートしています。
- **Google ADC** — `gcloud auth application-default login` を実行して、Google Application Default Credentials 経由で認証します。
- **Gemini CLI** — Gemini CLI がインストールされている場合は `gemini login` を実行します。
- **API キー** — 環境に `GEMINI_API_KEY` を設定するか、アプリの Manage Providers UI から構成します。
アプリは利用可能な認証方法を自動検出し、バックエンドに到達できる場合はランタイム設定とチーム作成の UI に Gemini プロバイダーを表示します。
## マルチモデルモード
マルチモデルモードでは、OpenCode 互換の設定を通じて、多数のプロバイダーバックエンドに処理をルーティングできます。プロバイダーの柔軟性が必要な場合や、チームメイトごとに異なるモデルレーンを使わせたい場合に利用します。
::: info モデルレーン
各チームメイトは、それぞれ異なる `providerId` + `model` の組み合わせを使用できます。チーム編集 UI でメンバーのオプションを展開すると、グローバルなデフォルト設定を上書きできます。
:::
控えめなマルチモデル構成:
| ロール | プロバイダー | 理由 |
| --- | --- | --- |
| Lead | Claude または Codex | 最も信頼しているプロバイダーで調整を維持する |
| Builder | OpenCode | 実装作業に幅広いモデルルーティングを使う |
| Reviewer | Claude、Codex、または 2 つ目の OpenCode モデル | レビューの判断を Builder のレーンから分離する |
最初の起動で、慣れていない多数のプロバイダーを混在させるのは避けましょう。幅広い作業を割り当てる前に、各レーンで 1 つの小さなタスクを確認してください。
## 起動前チェックリスト
チームを起動する前に:
1. 選択したランタイムがインストールされている
2. ランタイムバイナリが環境の `PATH` に含まれている
3. 選択したバックエンドのプロバイダー認証が設定されている
4. プロバイダーが、指定する正確なモデル文字列へのアクセス権を持っている
5. プロジェクトのパスが存在し、読み取り可能である
## ランタイム経路を切り替えるタイミング
現在の経路が、モデルの可用性、レート制限、プロバイダーの機能、またはチームのロールの必要性によって妨げられている場合は切り替えてください。同じプロジェクトとチームのワークフローは維持しつつ、切り替え後に 1 つの小さなタスクを検証してください。
::: warning セットアップのエラーはセットアップの問題として扱う
認証に失敗する、モデル名が拒否される、またはランタイムバイナリが見つからない場合は、まずセットアップを修正してください。ランタイム構成の問題を回避するために、チームプロンプトやプロジェクトコードを変更しないでください。
:::
次の判断テーブルを使用してください。
| 症状 | より適切な最初の対応 |
| --- | --- |
| バイナリが見つからない | インストールまたは `PATH` を修正する |
| ターミナルではログインできるがアプリではできない | Electron の認証診断ログと環境を確認する |
| モデルが拒否される | プロバイダーランタイムで正確なモデル ID を確認する |
| 429 が繰り返される | 並列度を下げるか、モデル/プロバイダーを切り替える |
| OpenCode レーンが停滞する | レーンのマニフェストと `opencode-sessions.json` を調べる |

131
landing/product-docs/ja/guide/team-brief-examples.md Normal file
View file

@ -0,0 +1,131 @@
---
title: チームブリーフの例 – Agent Teams ドキュメント
description: 小さな修正、ドキュメント作業、実装タスク、レビュー、高リスク領域向けの実用的なチームブリーフテンプレートです。
lang: ja-JP
---
# チームブリーフの例
優れたチームブリーフは、すべての実装の詳細を前もって強制することなく、リードが小さなタスクを作成するのに十分な構造を与えます。
次の形を使ってください。
```text
Outcome:
Scope:
Boundaries:
Coordination:
Verification:
Review:
```
## 最小限のブリーフ
小さくてリスクの低い作業に使用します。
```text
Outcome: Improve the quickstart so a new user can launch one team successfully.
Scope: Keep edits inside landing/product-docs.
Boundaries: Do not rewrite the whole docs structure.
Coordination: Create one or two tasks, keep comments on the task.
Verification: Run `pnpm --dir landing docs:build`.
Review: Summarize changed pages and any remaining gaps.
```
## 実装のブリーフ
コードの変更が 1 つの機能領域に及ぶ場合に使用します。
```text
Outcome: Add a focused improvement to task comment filtering.
Scope: Work inside the task/comment feature files unless a shared helper is clearly needed.
Boundaries: Do not change task storage format or review state semantics.
Coordination: Split parser, UI, and tests into separate tasks if they can be reviewed independently.
Verification: Run the focused unit tests first, then the feature typecheck if touched.
Review: Call out parsing edge cases and any behavior that affects existing task comments.
```
## ドキュメントのブリーフ
ドキュメントやガイドの作業に使用します。
```text
Outcome: Draft practical workflow guides from the docs audit.
Scope: Add concise VitePress pages under landing/product-docs/guide.
Boundaries: Avoid moving existing navigation hubs owned by other tasks.
Coordination: Check related docs tasks before editing nav.
Verification: Run `pnpm --dir landing docs:build`.
Review: Include links added to sidebar and any pages intentionally left as drafts.
```
## レビュー重視のブリーフ
IPC、プロバイダー認証、永続化、Git、タスクライフサイクルのロジックなど、リスクの高い領域に使用します。
```text
Outcome: Fix the launch failure without changing successful launch behavior.
Scope: Start from the newest launch-failure artifact and the affected runtime adapter.
Boundaries: Do not change provider prompts until setup and runtime evidence are inspected.
Coordination: Make one diagnostic task and one fix task if the cause is confirmed.
Verification: Run focused tests and one desktop smoke check when practical.
Review: Lead must inspect the diff before approval.
```
## 複数プロバイダーのブリーフ
チームメイトが異なるプロバイダー/モデルのレーンで動作する場合に使用します。
```text
Outcome: Implement and review a small feature using separate builder and reviewer lanes.
Scope: Builder edits the feature. Reviewer inspects only the task diff and tests.
Boundaries: Do not switch model ids mid-task unless launch fails before work begins.
Coordination: Builder posts result comment first. Reviewer posts findings as task comments.
Verification: Builder runs focused tests. Reviewer checks failure output and changed scope.
Review: Lead approves only after reviewer comments are resolved.
```
## ブリーフ内のエージェントブロック
エージェントブロックとは、`<info_for_agent>...</info_for_agent>` のようなマーカーで囲まれた、エージェント専用の非表示テキストです。アプリは通常の表示からこれらを取り除きますが、エージェントの連携のために利用できる状態を保ちます。人間の読み手にとってはノイズになるが、エージェントに何かを伝える必要がある場合にブリーフで使用してください。
例 - 連携の指示をユーザーに見せることなく、リードに作業の分割方法を伝えるブリーフ:
```text
Outcome: Add a dark mode toggle to the application settings.
Scope: Settings UI, theme context, and CSS variables.
Boundaries: Do not change existing light theme values or provider auth screens.
<info_for_agent>
Split this into three tasks: (1) theme context and CSS vars, (2) toggle component and settings wiring, (3) dark mode preview in existing docs screenshots if practical.
</info_for_agent>
```
このブロックは、人間向けのブリーフをすっきりと保ちつつ、リードに構造化されたタスク分割のガイダンスを与えます。
## 避けるべきこと
| 弱いブリーフ | より良い代替案 |
| --- | --- |
| "Improve the app" | ワークフロー、ファイル、成功の確認方法を明記する |
| "Fix all docs" | 1 つのガイドグループと 1 つのビルドコマンドを選ぶ |
| "Use the best model" | プロバイダー/モデルの選択を明記するか、アプリのデフォルトに任せる |
| "Refactor as needed" | 変更を許可するモジュールを明記する |
| "Make it production ready" | レビュー、テスト、ロールアウトの確認を定義する |
## 起動前に
チームを開始する前に、次の点を確認してください。
1. ブリーフが具体的な成果を明記している。
2. リスクの境界が明示されている。
3. リードが作業をレビュー可能なタスクに分割できる。
4. 分かっている場合は検証コマンドが含まれている。
5. 機微な領域は承認前にレビューを必要とする。
ブリーフがまだ漠然としている場合は、まずソロまたは小規模なチームを起動し、実装ではなくタスク計画を作成するよう依頼してください。
## 関連ガイド
- [チームの作成](/ja/guide/create-team)
- [MCP 連携](/ja/guide/mcp-integration)
- [Git と worktree の戦略](/ja/guide/git-worktree-strategy)

310
landing/product-docs/ja/guide/troubleshooting.md Normal file
View file

@ -0,0 +1,310 @@
---
title: トラブルシューティング – Agent Teams ドキュメント
description: ローカルの診断情報を使って、チームの起動の問題、エージェントの返信の欠落、レート制限、CLI 認証の問題、レーンのブートストラップの停滞を解決します。
lang: ja-JP
---
# トラブルシューティング
ほとんどのチームの問題は、ランタイムの設定、起動の確認、タスクの解析、プロバイダーの制限という 4 つのカテゴリーのいずれかに分類されます。
## 証拠の素早い準備
チームのライフサイクルに関するあらゆる問題について、まず以下の変数を定義し、同じシェルを再利用してください。
```bash
TEAM="<team-name>"
TEAM_DIR="$HOME/.claude/teams/$TEAM"
TASKS_DIR="$HOME/.claude/tasks/$TEAM"
```
次に、UI の状態を解釈する前に、想定されるファイルが存在することを確認します。
```bash
test -d "$TEAM_DIR" && find "$TEAM_DIR" -maxdepth 2 -type f | sort | sed -n '1,80p'
test -d "$TASKS_DIR" && find "$TASKS_DIR" -maxdepth 1 -name '*.json' | sort | sed -n '1,40p'
```
::: warning 証拠を最優先に
動かなくなったバッジだけを根拠に、プロンプト、プロバイダー設定、プロセスのクリーンアップを修正しないでください。まず UI を、永続化されたファイル、起動アーティファクト、ランタイムの証拠と突き合わせてください。
:::
## チームが起動しない
各項目を順番に確認します。
1. **ランタイムが利用可能** — 選択した CLI（`claude`、`codex`、`opencode`）がインストールされている
2. **PATH から到達可能** — そのバイナリが環境の `PATH` で利用できる
3. **モデルへのアクセス** — プロバイダーが、要求したモデル文字列にアクセスできる（特に OpenCode では、正確なプロバイダー名/モデル名が重要です）
4. **プロジェクトパス** — プロジェクトディレクトリが存在し、読み取り可能である
5. **ネットワーク / VPN** — 一部のプロバイダーは VPN が有効なときにトラフィックを遮断します
::: tip
ランタイムのバイナリをターミナルで実行して、`PATH` と認証を確認してください。例: `claude --version` または `opencode --version`。
:::
### OpenCode: registered だがブートストラップが未確認
OpenCode が `registered` を示しているのにブートストラップが未確認の場合は、チームのプロンプトを変更する前に、まずアーティファクトを調査してください。
コントリビューター向け/デバッグの詳細は [コントリビューター向けアーキテクチャ](/ja/reference/contributor-architecture) にあり、正規のエージェントチームデバッグ runbook へのリンクが含まれています。
最新の起動失敗アーティファクトを確認します。
```bash
LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
MANIFEST_PATH="$(jq -r '.manifestPath' "$LATEST_FAILURE")"
jq '.classification, .bootstrapTransportBreadcrumb, .memberSpawnStatuses' "$MANIFEST_PATH"
```
`latest.json` は、最新のパックされたアーティファクトディレクトリとその `manifest.json` を指します。このマニフェストには次のものが含まれます。
- `classification` — その起動が失敗とみなされた理由
- `bootstrapTransportBreadcrumb` — 使用された配信経路
- メンバーのスポーン状態
- 編集（マスク）済みのログとトレース
レーンのマニフェストも確認します。
```bash
jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime/lanes" -maxdepth 2 -name manifest.json -print -exec jq '.activeRunId, .entries' {} \; 2>/dev/null
```
::: tip UI から推測しないこと
UI の診断情報は、必ず永続化されたファイル（`launch-state.json`、`bootstrap-journal.jsonl`）およびランタイム固有の証拠と突き合わせてください。
:::
## 一般的な診断
UI だけではなく、ディスク上に永続化されたファイルから始めてください。
### チームルート
```bash
printf '%s\n' "$TEAM_DIR"
```
主要なファイルと、それぞれが示す内容は次のとおりです。
- `launch-state.json` — メンバーの起動/生存状態（`.teamLaunchState`、`.summary`、`.members`）
- `bootstrap-journal.jsonl` — CLI/ランタイムからの順序付きブートストラップイベント（`tail -80`）
- `bootstrap-state.json` — ブートストラップフェーズの概要
- `config.json` — プロバイダー、モデル、プロジェクトの設定
- `inboxes/*.json` と `sentMessages.json` — メッセージ配信の状態
```bash
jq '.teamLaunchState, .summary, .members' "$TEAM_DIR/launch-state.json"
tail -80 "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
```
### OpenCode のランタイム証拠
OpenCode のチームメイトについては、セッションの証拠はレーンランタイムストアにあります。
- `.opencode-runtime/lanes.json` — 状態を含むレーンのインデックス
- `.opencode-runtime/lanes/<lane>/manifest.json` — `activeRunId` と証拠エントリ
- `.opencode-runtime/lanes/<lane>/opencode-sessions.json` — コミット済みのセッションレコード
想定される正常な状態: レーンの状態が `active`、マニフェストに少なくとも 1 件の証拠エントリを持つ `activeRunId` がある、メンバーが `bootstrapConfirmed: true` である。
```bash
jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime" -maxdepth 3 -type f | sort
```
### 起動失敗アーティファクト
起動が失敗としてマークされた場合は、`latest.json` を調査します。
```bash
LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
jq '.' "$LATEST_FAILURE"
jq '.' "$(jq -r '.manifestPath' "$LATEST_FAILURE")"
```
このマニフェストには次のものが含まれます。
- `classification` — その起動が失敗とみなされた理由
- `bootstrapTransportBreadcrumb` — 使用された配信経路
- メンバーのスポーン状態と、編集（マスク）済みのログ/トレース
## エージェントの返信が欠落している
タスクログとチームメイトのメッセージを開いてください。返信の欠落は、多くの場合次の原因によるものです。
- **ランタイム配信のリトライ** — エージェントは回答したものの、メッセージがアプリに配信されなかった可能性があります。配信台帳を確認してください。
- **解析またはフィルタリング** — エージェントの出力に、想定されるマーカーやタスク参照が含まれていなかった。
- **タスクへの帰属** — セッション中に作業は行われたものの、正しいタスク id が出力に含まれていなかったため、タスクに紐付けられなかった。
::: warning 沈黙＝無視と思い込まないこと
ログで確認できるまで、モデルがメッセージを無視したと思い込まないでください。
:::
永続化されたメッセージの状態を使って、「未送信」と「送信済みだが表示されていない」を切り分けます。
```bash
jq '.' "$TEAM_DIR/inboxes/user.json" 2>/dev/null
jq '.' "$TEAM_DIR/sentMessages.json" 2>/dev/null
```
`from`、`to`、`messageId`、`relayOfMessageId`、`taskRefs` を確認します。OpenCode のチームメイトについては、モデルがプロンプトを無視したと思い込む前に、ランタイム配信の証拠も調査してください。
## タスクが変更に紐付けられていない
タスク固有のログとコードレビューのリンクを使用します。差分が切り離されているように見える場合は、次を確認します。
- タスク id またはタスク参照がエージェントの出力に含まれていたかどうかを確認する。
- エージェントが編集を行う前に `task_add_comment` を呼び出したかどうかを検証する。
- ボードが作業開始を認識できるよう、エージェントが `task_start` を呼び出したことを確認する。
OpenCode のチームメイトについては、セッションがタスクに属するという確実な証拠は、UI のメッセージストリームだけではなく、`opencode-sessions.json` とレーンのマニフェストエントリにあります。
### タスクログのトリアージ
タスクログが不完全に見える場合は、タスク JSON、受信トレイ、ブートストラップイベントにまたがってタスク id で検索します。
```bash
TASK="<short-or-full-task-id>"
rg -n "$TASK" "$TASKS_DIR" "$TEAM_DIR/inboxes" "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
```
結果は慎重に解釈してください。
| 証拠 | 証明できること | 証明できないこと |
| --- | --- | --- |
| メッセージが配信された | アプリがプロンプトを書き込んだか中継した | エージェントが進捗を出した |
| タスクコメント | エージェントがボードに表示されるテキストを投稿した | そのコメントが意味のある進捗である |
| ネイティブツールの行 | ランタイムがセッション内で作業を行った | 帰属が一致しない限り、その作業がこのタスクに属する |
| 変更台帳のエントリ | アプリがファイルの変更を記録した | 実装が正しい |
OpenCode では、正常なタスクログには通常、`read`、`bash`、`edit`、`write` といったネイティブランタイムの行に加えて、Agent Teams の MCP の行が含まれます。`agent-teams_*` の行しか見当たらない場合は、ログのマッチング範囲を広げる前に、タスクへの帰属とセッションの境界を確認してください。
## レート制限
プロバイダーが既知のリセット時刻を報告する場合、Agent Teams はクールダウン後にリードへ続行を促すことができます。リセット時刻が不明な場合は、待機するか、プロバイダー/ランタイムの経路を切り替えてください。
| プロバイダーの挙動 | 推奨される対応 |
| --- | --- |
| 既知のリセット時刻が表示される | クールダウンを待ってから続行する |
| リセット時刻が表示されない | プロバイダーまたはランタイムの経路を切り替える |
| 429 が繰り返される | 並行数を下げるか、別のモデルレーンを使用する |
## CLI 認証の問題
### `claude login` が保持されない
CLI が 1 つのターミナルでは認証されているのに、アプリでは未認証と表示される場合は、認証が想定される設定パスに保存されていること、およびアプリのプロセスが同じ `$HOME` を参照していることを確認してください。
### OpenCode のプロバイダーキーが拒否される
- `config.json` 内のプロバイダー名が、モデル文字列のプロバイダープレフィックスと一致しているか再確認する
- そのキーが、プロバイダーのダッシュボードで失効または取り消されていないことを確認する
### 認証診断ログ
`CliInstallerService.getStatus()` が呼び出されるたびに、Electron のログフォルダー（macOS では通常 `~/Library/Logs/<product-name>/`）内の `claude-cli-auth-diag.ndjson` に 1 行が追記されます。このファイルが **512 KiB** を超えると、次の書き込みの前に空に切り詰められます。
パッケージ化されたアプリで「Not logged in」や認証エラーが表示される場合は、このファイルを確認してください。
## レーンのブートストラップが停滞している
OpenCode のセカンダリレーンについて:
- `inboxes/<member>.json` が存在しないことが、自動的にバグであるとは限りません。OpenCode のレーンは、開始前にプライマリ受信トレイによって作成されている必要はありません。
- プライマリメンバーがすでに使用可能なのに UI でチームがまだ起動中と表示される場合、「all teammates joined」はセカンダリレーンを待っています。
- `Prepared communication channels for X/Y members` が止まる場合は、`Y` に OpenCode のセカンダリメンバーが誤って含まれていないかを確認してください。
### レーンのマニフェストのエントリが空
ブリッジがブートストラップ成功と報告しているのに `manifest.json` が `entries: []` を示している場合、問題はモデルの挙動ではなく **証拠のコミット** にあります。`opencode-sessions.json` とそのマニフェストエントリが存在するまで、メンバーを配信可能とみなしてはなりません。
## メンバーのよくある状態
| 状態 | 意味 |
| --- | --- |
| `confirmed_alive` + `bootstrapConfirmed` | 正常で準備完了 |
| `registered` / `runtime_pending_bootstrap` | プロセスまたはレーンは存在するが、ブートストラップの証拠がまだコミットされていない |
| `failed_to_start` + `runtime_process` | プロセスは存在するが、起動ゲートが失敗した。診断情報を確認してください |
| `failed_to_start` + `stale_metadata` | 保存された pid/セッションが古いか、すでに停止している |
::: warning
`member_briefing` だけではランタイムの証拠には**なりません**。OpenCode では、確実な証拠は `opencode-sessions.json` とマニフェストエントリのような、コミット済みのランタイム証拠です。
:::
## ランタイムのデバッグモード
ローカルでのデバッグのために、チームメイトを tmux ペインで実行するよう強制できます。
```bash
# Launch from a terminal
CLAUDE_TEAM_TEAMMATE_MODE=tmux pnpm dev
# Or add to custom CLI args
--teammate-mode tmux
```
これは対話的な CLI の挙動を調べるために使用します。これがプロセスバックエンドと完全に等価であるとは考えないでください。
## スモークチェック
通常の検証にはデスクトップの Electron アプリを使用してください。ブラウザ/Web の開発モードには、完全なデスクトップランタイム、IPC、プロバイダー認証、ターミナル、チームのライフサイクル挙動は含まれていません。
### ドキュメントのみの変更
リポジトリのルートから:
```bash
pnpm --dir landing docs:build
git diff --check -- landing/product-docs
```
### チームライフサイクルの変更
狭い範囲から始めて、徐々に広げます。
```bash
pnpm test -- test/main/services/team/TeamProvisioningService.test.ts
pnpm test -- test/main/services/team/TeamAgentLaunchMatrix.safe-e2e.test.ts
pnpm typecheck
git diff --check
```
### ライブチームのスモーク
小規模なチームと、Git で追跡している使い捨てのプロジェクトを使用します。
1. `pnpm dev` でデスクトップアプリを起動します。
2. リード 1 名とビルダー 1 名を作成します。
3. 明示的な検証コマンドを添えて、ごく小さな変更を依頼します。
4. タスクが `pending` -> `in_progress` -> `completed` と移動することを確認します。
5. タスクログを開き、ツールの行、タスクコメント、ファイルの変更が整合していることを確認します。
6. クリーンアップの際は、スモーク専用のチーム/プロセスのみを停止します。
::: warning 狭い範囲のクリーンアップのみ
スモーク実行のクリーンアップ中に、すべての OpenCode ホスト、無関係な tmux ペイン、ユーザーのチームを終了しないでください。
:::
## 安全なクリーンアップ
古くなったプロセスをクリーンアップする際は:
1. pid を特定し、それが現在のチーム/レーンに属していることを確認します。
2. スモークテストやデバッグ中の起動に明示的に属するプロセスのみを停止します。
3. 近道として、すべての OpenCode プロセスや共有ホストのプロセスを**終了しない**でください。
## 証拠を収集すべきタイミング
サポートを求める前に、次を収集してください。
- タスク id（短縮形または完全形）
- チーム名
- ランタイムの経路（`claude`、`codex`、`opencode`）
- 起動ログの抜粋（`latest.json` または `bootstrap-journal.jsonl` から）
- プロバイダー / モデル文字列
- 問題が発生した正確な時間帯
通常、このデータがあれば、起動やタスクのライフサイクルの問題をデバッグするのに十分です。
::: tip
問題が解決しない場合は、`~/.claude/teams/<teamName>/` 配下のチームの永続化ファイルを開き、コードを変更する前に UI の診断情報をライブプロセスの状態と突き合わせてください。
:::

81
landing/product-docs/ja/index.md Normal file
View file

@ -0,0 +1,81 @@
---
title: Agent Teams ドキュメント – ローカル デスクトップアプリで AI エージェントのチームを動かす
description: AI エージェントのオーケストレーションを行う無料のデスクトップアプリ Agent Teams のドキュメントです。チームを作成し、カンバンボードで作業を見守り、コード変更をレビューし、Claude、Codex、OpenCode、マルチモデルのワークフローを連携させます。
lang: ja-JP
layout: home
hero:
name: Agent Teams ドキュメント
text: ローカル デスクトップアプリで AI エージェントのチームを動かす
tagline: チームを作成し、タスクがカンバンボード上を移動していく様子を見守り、コード変更をレビューし、ローカルでの制御を手放すことなく Claude、Codex、OpenCode、マルチモデルのワークフローを連携させます。
actions:
- theme: brand
text: クイックスタート
link: /ja/guide/quickstart
- theme: alt
text: インストール
link: /ja/guide/installation
- theme: alt
text: コンセプト
link: /ja/reference/concepts
features:
- icon: "01"
title: チームファーストのワークフロー
details: ロールを定義し、リードを起動して、エージェントがタスクを分割・取得・調整できるようにします。
link: /ja/guide/create-team
linkText: チームを作成する
- icon: "02"
title: ライブ カンバンボード
details: エージェントが作業する中で、タスクが todo、in progress、review、done、approved を移動していく様子を見守ります。
link: /ja/guide/agent-workflow
linkText: ワークフローを理解する
- icon: "03"
title: 組み込みのコードレビュー
details: タスク単位の差分を確認し、ハンクを承認または却下し、エージェントに方向性が必要な箇所にコメントします。
link: /ja/guide/code-review
linkText: 変更をレビューする
- icon: "04"
title: ランタイムを意識したセットアップ
details: すでにお持ちのアクセス権を通じて、Claude、Codex、OpenCode、またはマルチモデルのプロバイダーを利用します。
link: /ja/guide/runtime-setup
linkText: ランタイムを設定する
- icon: "05"
title: ローカルファーストの制御
details: デスクトップアプリはローカルのプロジェクトとランタイムの状態を読み取ります。選択したプロバイダーがプロンプトのコンテキストを受け取らない限り、コードはお使いのマシンに留まります。
link: /ja/reference/privacy-local-data
linkText: プライバシーモデル
- icon: "06"
title: デバッグ可能なチーム
details: 起動やタスクが行き詰まったときに、タスクログ、ランタイム出力、チームメイトのメッセージ、ライブプロセスをトレースします。
link: /ja/guide/troubleshooting
linkText: トラブルシューティング
---
<InstallBlock label="コピー" copied-label="コピーしました" />
## はじめに
Agent Teams は、AI エージェントのチームをオーケストレーションするための無料のデスクトップアプリです。単一のエージェントに孤立したプロンプトを送るだけではありません。チームを作成し、ロールを割り当て、エージェントがタスクボードを通じて作業を調整する様子を見守ります。
<DocsCardGrid />
## 起動後の次のステップ
最初のチームを作成したら、さらに先へ進むために次のガイドを参照してください。
- **ランタイムの設定** - Claude、Codex、OpenCode、またはマルチモデルのプロバイダーを設定します: [ランタイムを設定する](/ja/guide/runtime-setup)
- **エージェントのワークフロー** - エージェントがタスクボードを通じてどのように調整するかを理解します: [ワークフローを理解する](/ja/guide/agent-workflow)
- **チームブリーフの例** - 実際のブリーフからプロンプトのパターンを学びます: [例を見る](/ja/guide/team-brief-examples)
- **コードレビュー** - 差分を確認し、変更を承認または却下します: [変更をレビューする](/ja/guide/code-review)
- **トラブルシューティング** - 行き詰まった起動、不在のチームメイト、タスクの失敗を診断します: [トラブルシューティング](/ja/guide/troubleshooting)
- **Git と worktree の戦略** - 複数のチームメイトが同じリポジトリを並行して編集する場合に worktree による分離を利用します: [worktree について学ぶ](/ja/guide/git-worktree-strategy)
- **リリースノート** - 各バージョンの新機能を確認します: [リリースを見る](/ja/reference/release-notes)
## リファレンス
正確な用語、プロバイダーの動作、コントリビューター向けアーキテクチャ、プライバシーの境界が必要なときは、リファレンスページを参照してください。
<DocsCardGrid type="reference" />
## 製品プレビュー
<ZoomImage src="/screenshots/1.jpg" alt="Agent Teams のカンバンボード" caption="タスクのステータス、チームメイトのアクティビティ、レビューのワークフローが、ひとつのワークスペースで常に見える状態に保たれます。" />

85
landing/product-docs/ja/reference/concepts.md Normal file
View file

@ -0,0 +1,85 @@
---
title: コンセプト – Agent Teams ドキュメント
description: Agent Teams 全体で使われる中核的な用語集 — チーム、リード、チームメイト、タスク、カンバン、インボックス、ランタイム、レビューについて。
lang: ja-JP
---
# コンセプト
このページでは、Agent Teams 全体で使われる中核的な用語を定義します。アプリ、タスクボード、メッセージ、レビューフローで共有される語彙としてご利用ください。
## チーム
チームとは、1 つのプロジェクトパスに紐付けられた、名前付きのエージェントのグループです。リード、任意のチームメイト、ランタイム/プロバイダー設定、プロンプト、インボックス、タスク、ローカルの起動状態を持ちます。
## リード {#lead}
リードはチームのコーディネーターです。ユーザーの目標をタスクへと変換し、チームメイトを割り当てたり再配置したりし、ブロッカーを追跡し、レビューを依頼し、ボード上で作業を前進させ続けます。
[チームメイト →](#teammate)
リードのメッセージは、チームメイトのメッセージとは異なる配信経路を使います。アプリはリードのインボックスのエントリをリードのランタイムにリレーしますが、チームメイトはターンの合間に自身のインボックスファイルを読み取ります。
## チームメイト {#teammate}
チームメイトとは、チーム内のリード以外のエージェントです。チームメイトは通常、builder、reviewer、researcher、tester といった特定のロールを担います。チームメイトはダイレクトメッセージ、タスクの割り当て、タスクコメント、レビュー依頼を受け取れます。
[リード ↑](#lead)
## タスク
タスクとは、作業の永続的な単位です。id、ステータス、オーナー、説明、コメント、ログ、添付ファイル、タスク参照、レビュー可能な変更を持ちます。
一般的なタスクの状態は `todo`、`in_progress`、`done`、`review`、`approved` です。内部的には、タスクファイルが作業状態を保存する一方で、review と approved の配置にはカンバンのオーバーレイ状態も使われることがあります。
## カンバン
カンバンとは、チーム作業のボードビューです。状態ごとにタスクを一覧したり、タスクの詳細を開いたり、ログを確認したり、差分をレビューしたり、完了した作業を承認したり、変更を依頼したりできます。
## インボックス
インボックスとは、チーム参加者向けのローカルなメッセージファイルです。Agent Teams は、ユーザーメッセージ、リードメッセージ、チームメイトメッセージ、ランタイム配信のメタデータ、クロスチームメッセージ、一部のシステム通知にインボックスを使用します。
メッセージは永続的なローカルレコードです。配信は依然として、選択したランタイムが生存していて次のターンを処理できることに依存します。
## エージェントブロック
エージェントブロックとは、`<info_for_agent>...</info_for_agent>` でラップされた、エージェント専用の非表示の指示テキストです。UI は通常の人間向け表示からこれらのブロックを取り除きますが、エージェントとランタイム配信はそれらを調整の詳細として利用できます。
現在の正規のマーカーは `info_for_agent` です。古いドキュメントでは `info_for_agent` マーカー付きのフェンス付きコードブロックや、XML スタイルの `<agent_block>` タグを使っている場合があります。これらはレガシーなパターンであり、見つけたら `info_for_agent` へ移行すべきです。(元のタグ名は `agent-block` でした。アンダースコア形式の `<agent_block>` は、HTML としてのパースを避けるために VitePress のソースで使用されています。)
## コンテキストフェーズ
コンテキストフェーズとは、セッションのコンテキストタイムラインを構成する 1 つのセグメントです。コンパクションが新しいフェーズを開始するため、リセットの前後でトークンとコンテキストの使用状況を分析できます。
コンテキストの追跡では、プロジェクトの指示、メンションされたファイル、ツール出力、思考テキスト、チームの調整、ユーザーメッセージといったカテゴリを区別します。これらの数値は診断用であり、プロバイダーの請求明細ではありません。
## ランタイム
ランタイムとは、エージェントのターンを実行するローカルの実行経路です。サポートされるランタイム経路には Claude Code、Codex、OpenCode が含まれます。
ランタイムは、モデルの実行挙動、認証の詳細、ツール実行のセマンティクス、レート制限、モデルの可用性、一部のトランスクリプト/ログ形式を担います。
## プロバイダー
プロバイダーとは、ランタイムの背後にあるモデルアクセス経路です。現在のプロバイダー id には Anthropic、Codex、Gemini、OpenCode が含まれます。OpenCode は、独自の設定を通じて多くのモデルプロバイダーへルーティングできます。
Agent Teams はタスクとメッセージをオーケストレーションしますが、プロバイダーの認証やプロバイダーのポリシーを置き換えるものではありません。
## ソロモード
ソロモードは、1 メンバーのチームを実行します。手早い作業、調整オーバーヘッドの削減、フルチームへ拡張する前のプロンプト検証に役立ちます。
## クロスチームコミュニケーション
エージェントはチーム内およびチーム間でメッセージを送信できます。別々のチームが関連する作業を担当しており、すべてを 1 つの大きなチームにまとめることなく調整する必要がある場合に使用します。
## 自律性のレベル
自律性は、エージェントが確認を求める前にどこまで実行できるかを制御します。自律性が高いほど速く、低いほど、機微なコードパス、永続化、プロバイダー認証、Git 操作、リリースに対して安全です。
## レビュー
レビューとは、タスクスコープの受け入れフローです。タスクは review に移動し、コメントや変更依頼を受け取り、結果が受け入れられると approved に移動できます。
レビューはローカルの差分とタスク履歴に結び付いているため、タスクが狭い範囲に保たれ、エージェントが作業中のタスクをメンションするときに最も効果を発揮します。

55
landing/product-docs/ja/reference/contributor-architecture.md Normal file
View file

@ -0,0 +1,55 @@
---
title: コントリビューター向けアーキテクチャ – Agent Teams ドキュメント
description: 機能のレイアウト、ランタイム/プロバイダーの境界、ハードガードレール、および正規のアーキテクチャドキュメントについてのコントリビューターガイド。
lang: ja-JP
---
# コントリビューター向けアーキテクチャ
このページはコントリビューター向けのマップです。すべての実装ルールを再掲するのではなく、正規のリポジトリガイダンスへの道しるべを示します。
## 正規の情報源
アプリを変更する際は、これらのファイルを信頼できる情報源（source of truth）として使用してください。
| 必要なもの | 正規の情報源 |
| --- | --- |
| リポジトリの概要とコマンド | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) |
| ローカルでの作業規約 | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) |
| ハードガードレール | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) |
| 中規模・大規模機能のレイアウト | [docs/FEATURE_ARCHITECTURE_STANDARD.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) |
| エージェントチームの起動デバッグ | [docs/team-management/debugging-agent-teams.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) |
## 機能のレイアウト
中規模・大規模の機能は `src/features/<feature-name>/` の配下に置き、機能アーキテクチャ標準に従ってください。機能の内部実装はパブリックなエントリーポイントの背後に隠し、機能境界をまたぐディープインポートは避けてください。
新規作業では、ローカルのリファレンス実装として既存の `src/features/recent-projects` スライスから始めてください。機能スライスを作成すると価値以上に構造が増えてしまう場合、小さな修正は既存のコードパスの近くに留めても構いません。
## ランタイムとプロバイダーの境界
Agent Teams はオーケストレーションを担います。すなわち、チーム、タスク、メッセージ、起動状態、レビュー UI、診断、およびローカルでの永続化です。
選択されたランタイム/プロバイダーのパスは、モデルの実行、認証、モデルの可用性、レート制限、ツールのセマンティクス、およびランタイム固有のトランスクリプト証跡を担います。認証の欠落、バイナリの欠落、拒否されたモデル ID、またはプロバイダーの障害を、プロンプトや UI の状態で補おうとしないでください。ユーザー向けのセットアップ詳細については、[プロバイダーとランタイム](/ja/reference/providers-runtimes)を参照してください。
## エージェントチームのデバッグ
起動のハング、OpenCode の `registered` / bootstrap-unconfirmed 状態、チームメイトの返信の欠落、または不審なタスクログについては、専用のデバッグ用ランブックから始めてください。`~/.claude/teams/<team>/launch-failure-artifacts/latest.json` 配下にある最新の起動失敗アーティファクトを調べ、次に UI の状態を永続化されたファイルおよびランタイム固有の証跡と突き合わせてください。
デバッグ中の広範囲なクリーンアップは避けてください。問題に属すると特定できるプロセス、レーン、チーム、またはスモークランのみを停止してください。
## コントリビューターの規約
- 通常の開発では、デスクトップ版 Electron アプリに `pnpm dev` を使用してください。
- デスクトップランタイム、IPC、ターミナル、プロバイダー認証、またはチームのライフサイクル挙動の代替として、ブラウザの開発モードを使用しないでください。
- Electron の main、preload、renderer、shared、および機能の責務を分離して保ってください。
- マーカーを手動で連結する代わりに、エージェント専用ブロックには `wrapAgentBlock(text)` を使用してください。
- 焦点を絞った検証を優先してください。タスクが明示的にフォーマットに関するものでない限り、広範囲な `lint:fix` やフォーマットの変更は避けてください。
- パース、タスクのライフサイクル、プロバイダー/ランタイムの検出、永続化、IPC、Git、およびレビューフローは、的を絞ったテストまたは明確な検証パスを必要とする高リスク領域として扱ってください。
## 関連ページ
- [ランタイムの設定](/ja/guide/runtime-setup)
- [トラブルシューティング](/ja/guide/troubleshooting)
- [コードレビュー](/ja/guide/code-review)
- [プライバシーとローカルデータ](/ja/reference/privacy-local-data)

95
landing/product-docs/ja/reference/faq.md Normal file
View file

@ -0,0 +1,95 @@
---
title: FAQ – Agent Teams ドキュメント
description: Agent Teams に関するよくある質問 — 料金、モデルアクセス、ランタイム、プライバシー、レビュー、トラブルシューティングについて。
lang: ja-JP
---
# FAQ
## Agent Teams は無料ですか？
はい。アプリは無料でオープンソースです。使用する内容によっては、プロバイダーやランタイムのアクセスに費用がかかる場合があります。
## Agent Teams にモデルアクセスは含まれていますか？
いいえ。Agent Teams はローカルのオーケストレーションおよび UI レイヤーです。モデルアクセスは、選択したランタイム/プロバイダーの経路（Claude Code、Codex、OpenCode など）から提供されます。
## どのランタイムがサポートされていますか？
サポートされているランタイムの経路は Claude Code、Codex、OpenCode です。また、ランタイムが公開している場合、アプリは Anthropic、Codex、Gemini、OpenCode などのプロバイダー id も追跡します。
## 先に Claude Code や Codex をインストールする必要がありますか？
必ずしも必要ではありません。アプリは UI からランタイムの検出とセットアップをガイドします。一部の経路では、外部ランタイムの認証が依然として必要です。
OpenCode のセットアップは、Claude Code や Codex のセットアップとは別です。起動に失敗した場合は、チームプロンプトを変更する前に、ランタイムのステータスとプロバイダー認証を確認してください。
## ランタイムが準備できているかどうかを確認するには？
まずターミナルでランタイムのコマンドを実行します:
```bash
claude --version
codex --version
opencode --version
```
次に、選択した経路のプロバイダー認証を確認します。コマンドや認証チェックが Agent Teams の外で失敗する場合は、チームを起動する前にセットアップを修正してください。
## 私のコードを Agent Teams のサーバーにアップロードしますか？
いいえ。Agent Teams はクラウドのコード同期サービスではありません。選択したランタイムによっては、プロバイダーを介したモデル呼び出しがプロンプトのコンテキストを受け取る場合があります。
## チームファイルはどこに保存されますか？
チームの調整データはローカルの `~/.claude/teams/<team>/`（macOS/Linux）または `%APPDATA%\Claude\teams\<team>\`（Windows）に保存され、タスクファイルは `~/.claude/tasks/<team>/` または `%APPDATA%\Claude\tasks\<team>\` に、プロジェクトのセッションデータは利用可能な場合 `~/.claude/projects/<encoded-project>/` に保存されます。
## 私のマシンから何が外部に出ていく可能性がありますか？
エージェントがプロバイダーを介したモデルを使用するとき、プロンプトのコンテキスト、選択したファイルの内容、ツールの結果、コマンドの出力、タスクのテキスト、コメント、添付ファイルが、ランタイム/プロバイダーの経路を通じてマシンから外部に出ていく可能性があります。正確な挙動はランタイムとプロバイダーによって異なります。
## エージェント同士は会話できますか？
はい。エージェントはチームメイトにメッセージを送ったり、タスクにコメントしたり、チームをまたいで調整したり、タスク参照を使って会話を作業に紐づけたままにしたりできます。
## 最初のチームプロンプトには何を入れるべきですか？
リードに対して、具体的な成果、ファイルや機能の境界、リスクの制限、検証の期待値を与えてください。例えば:
```text
Improve the docs quickstart. Keep edits inside landing/product-docs, add practical examples, and run `pnpm --dir landing docs:build` before marking work done.
```
## 受け入れる前にコードをレビューできますか？
はい。レビューフローは、タスク単位の差分とハンク単位の判断を中心に設計されています。
## Agent Block とは何ですか？
Agent Block は、`<info_for_agent>...</info_for_agent>` などのマーカーで囲まれた、エージェント専用の非表示テキストです。アプリは通常のユーザー向け表示からそれを取り除きますが、エージェントの調整のために利用できる状態を保ちます。
## ソロモードとは何ですか？
ソロモードは 1 エージェントのチームです。小規模なタスクや、調整のオーバーヘッドを抑えたい場合に役立ちます。
## worktree の分離を使うべきですか？
複数の OpenCode チームメイトが同じ Git プロジェクトを並行して編集する可能性がある場合に使用してください。ファイルの競合を減らしますが、Git で追跡されているプロジェクトが必要であり、現時点では OpenCode のメンバーに適用されます。
## チームメイトごとに異なるプロバイダーを使えますか？
はい。選択したランタイムの経路が対応している場合、プロバイダー/モデルの設定をチームメンバーごとに引き継げます。OpenCode は、幅広いマルチプロバイダーのルーティングを行うための主要な経路です。
## なぜタスクが done とは別に review や approved を表示するのですか？
作業の状態とレビューの状態は関連していますが、同一ではありません。タスクはエージェントの観点では done になっても、その後かんばん UI で review と approval の段階を進んでいくことがあります。
## 起動がハングしたときはどうすればよいですか？
トラブルシューティングを開き、起動の診断情報を収集し、`~/.claude/teams/<team>/` を確認し、プロンプトを変更する前にランタイム/プロバイダーの認証を確認してください。
OpenCode の場合は、チームメイトがオンラインなのにメッセージを無視していると判断する前に、レーン/セッションの証跡を確認してください。
## なぜランタイムによってログが異なるのですか？
Claude Code、Codex、OpenCode は、それぞれ異なるトランスクリプト形式とランタイムの証跡を公開します。Agent Teams は可能な範囲で正規化しますが、ログの完全性や帰属はランタイムによって異なる場合があります。

82
landing/product-docs/ja/reference/privacy-local-data.md Normal file
View file

@ -0,0 +1,82 @@
---
title: プライバシーとローカルデータ – Agent Teams ドキュメント
description: Agent Teams がローカルに保存するもの、プロバイダー経由のモデル呼び出しによってマシンの外に出る可能性があるもの、そして実践的なプライバシーガイダンスについて。
lang: ja-JP
---
# プライバシーとローカルデータ
Agent Teams はローカルファーストですが、選択したランタイム/プロバイダーの経路は依然として重要です。このページでは、デスクトップアプリがローカルに保存するものと、エージェントがプロバイダー経由のモデルを呼び出す際にマシンの外に出る可能性があるものについて説明します。
## ローカルに留まるもの
デスクトップアプリはあなたのマシン上で動作し、ローカルのプロジェクト/ランタイムデータを読み取って UI を動かします。一般的なローカルデータには次のものが含まれます。
- プロジェクトファイル
- チーム構成とメンバーのメタデータ
- タスクのメタデータ、タスクコメント、タスク参照
- インボックスメッセージ
- ランタイム/セッションのログ
- 起動状態とブートストラップ診断
- レビュー状態
- ローカルのアプリ設定
重要なローカルの場所には次のものが含まれます。
| プラットフォーム | 場所 | 用途 |
| --- | --- | --- |
| macOS/Linux | `~/.claude/teams/<team>/` | チーム構成、メンバーのメタデータ、インボックス、起動状態、ブートストラップの証跡、ランタイム診断、送信メッセージの記録、kanban の状態、レビュー関連のチームファイル。 |
| Windows | `%APPDATA%\Claude\teams\<team>\` | 同じ — チーム構成、メンバーのメタデータ、インボックス、起動状態、診断。 |
| macOS/Linux | `~/.claude/tasks/<team>/` | チームボード用の永続的なタスク JSON ファイル。 |
| Windows | `%APPDATA%\Claude\tasks\<team>\` | 同じ — 永続的なタスク JSON ファイル。 |
| macOS/Linux | `~/.claude/projects/<encoded-project>/` | セッション履歴、コンテキスト分析、トランスクリプトに基づく UI に使用される Claude/Codex 形式のプロジェクトセッションファイル。 |
| Windows | `%APPDATA%\Claude\projects\<encoded-project>\` | 同じ — プロジェクトセッションファイル。 |
正確なファイルはランタイムやアプリのバージョンによって異なる場合があります。起動のデバッグでは、最新の証跡は通常、該当する `~/.claude/teams/<team>/`（または `%APPDATA%\Claude\teams\<team>\`）フォルダー以下にあります。
## マシンの外に出る可能性があるもの
Agent Teams 自体は、あなたのリポジトリ向けのクラウドコード同期サービスではありません。ボード、インボックス、ログ、レビュー UI を表示するために、プロジェクト全体を Agent Teams のサーバーへアップロードする必要はありません。
ただし、エージェントがプロバイダー経由のモデルに作業を依頼する際には、プロンプトのコンテキスト、選択したファイルの内容、タスクのテキスト、コメント、ツールの結果、コマンドの出力、その他のランタイムが提供するコンテキストが、選択したランタイム/プロバイダーの経路を通じて送信される可能性があります。何が送信されるかは、ランタイム、モデル、ツール呼び出し、プロンプト、そしてプロバイダーの構成によって異なります。
プロバイダー認証、プロバイダー側の保持、トレーニング、ロギング、地域ごとの処理、課金は、あなたが選択したプロバイダー/ランタイムによって管理されます。機密性の高いプロジェクトについては、それらのポリシーを確認してください。
一般的な例:
| アクション | ランタイム/プロバイダー経由で送信される可能性があるデータ |
| --- | --- |
| エージェントにファイルの編集を依頼する | タスクのプロンプト、関連するファイルの内容、ツールの結果、コマンドの出力 |
| スクリーンショットを添付する | 添付内容と、その周辺のタスク/コメントのテキスト |
| コードレビューを依頼する | 差分のコンテキスト、選択したファイル、コメント、検証ログ |
| 失敗したコマンドをデバッグする | エラー出力、スタックトレース、参照されたソーススニペット |
## アプリが保証しないこと
- プロバイダー経由のモデル呼び出しがプライベートなコードを決して受け取らないことを保証できません。
- プロバイダーの保持ポリシーや課金ポリシーを上書きすることはできません。
- リモートのプロバイダーを完全にローカルなモデルのように振る舞わせることはできません。
- プロンプト、タスクコメント、ファイル、コマンドへ貼り付けるようエージェントに指示された秘密情報を保護することはできません。
- すべてのランタイムが同じトランスクリプトや監査の詳細を公開するようにすることはできません。
## 実践的なガイダンス
- 秘密情報をタスク、コメント、ダイレクトメッセージに添付しないでください。
- 機密性の高いプロジェクトについては、プロバイダーのポリシーを確認してください。
- リスクのあるリポジトリでは、より低い自律性を使用してください。
- プライベートなコードを扱う際は、タスクの範囲を狭く保ってください。
- デバッグの際は、ローカルの証跡とログを優先してください。
- 機密性の高い素材についてエージェントに作業を依頼する前に、生成されたプロンプト、タスクの説明、添付ファイルを確認してください。
- あなたのプライバシー要件に合ったプロバイダー/モデルの経路を使用してください。
機密性の高いリポジトリで Agent Teams を使用する前に:
1. ワーキングツリーとタスクの添付ファイルから秘密情報を削除する
2. 使用が許可されているランタイム/プロバイダーの経路を選択する
3. 低い自律性と小さなタスクから始める
4. 範囲を広げる前に、タスクのプロンプトと生成されたコメントを確認する
5. サポートのために意図的に共有する場合を除き、ログをローカルに保つ
## オープンソースモデル
アプリ自体はオープンソースかつ無料です。ローカルのオーケストレーション、タスク追跡、インボックス、ランタイム診断、レビューフローがどのように動作するかを、リポジトリで確認できます。

115
landing/product-docs/ja/reference/providers-runtimes.md Normal file
View file

@ -0,0 +1,115 @@
---
title: プロバイダーとランタイム – Agent Teams ドキュメント
description: 対応するランタイムパス（Claude Code、Codex、OpenCode）、プロバイダー ID、モデルの命名、マルチプロバイダー戦略、機能チェックについて。
lang: ja-JP
---
# プロバイダーとランタイム
Agent Teams はオーケストレーションとモデルアクセスを分離します。アプリはチーム、タスク、メッセージ、起動状態、レビュー UI を管理し、選択したランタイム／プロバイダーパスが実際のモデル処理を実行します。
## アプリが提供するもの
Agent Teams が提供するもの:
- チームとタスクのオーケストレーション
- かんばんボード UI
- チームメイトのメッセージング
- タスクログ
- レビュー UI
- ローカルプロジェクト連携
- ランタイム検出と機能チェック
- ローカルログと診断
## ランタイムが提供するもの
ランタイムが提供するもの:
- モデルの実行
- プロバイダー認証
- ツール実行の挙動
- モデル固有のレート制限と機能
- ランタイム固有のトランスクリプトと配信の証跡
## 対応するランタイムパス
| ランタイムパス | プロバイダー／モデルのパス | 最適な用途 | 備考 |
| --- | --- | --- | --- |
| Claude Code | Anthropic / Claude モデル | Claude Code ユーザーおよび Anthropic を基盤とするワークフロー | Claude チーム向けのデフォルトのローカルファーストパス。ランタイムとアカウントアクセスがローカルで利用可能である必要があります。 |
| Codex | Codex / OpenAI を基盤とするモデル | Codex ネイティブのワークフロー | Codex ランタイム連携と、利用可能な場合は Codex の認証／アカウント状態を使用します。一部の診断は Claude のトランスクリプトとは異なります。 |
| OpenCode | OpenCode が管理するモデルルーティング | マルチプロバイダーのチームと広範なモデルカバレッジ | OpenCode は多数のモデルプロバイダーを経由してルーティングできます。Agent Teams は OpenCode のレーンをランタイム固有の証跡として扱い、レーンの識別があいまいな場合は推測を行いません。 |
Gemini は、Google ADC（gcloud auth）、Gemini CLI の OAuth、API キー認証を用いた、対応プロバイダーパスとして利用できます。ランタイムが利用可能と報告した場合、チーム作成およびランタイム設定の UI で他のプロバイダーと並んで表示されます。
## プロバイダー ID
アプリは現在、チーム／ランタイム設定で次のプロバイダー ID を認識します:
| プロバイダー ID | 表示の意図 |
| --- | --- |
| `anthropic` | Anthropic / Claude Code パス |
| `codex` | Codex パス |
| `gemini` | Gemini プロバイダーパス（Google ADC、Gemini CLI、または API キー） |
| `opencode` | OpenCode パス（OpenCode が管理するプロバイダールーティングを含む） |
この表を、すべてのプロバイダーがすべてのマシン上のすべてのモデルについて認証済み・インストール済み・利用可能であることの保証として読まないでください。特定の起動については、ランタイムのステータスと機能チェックが信頼できる情報源です。
## モデル ID
モデル ID は選択したランタイムに渡されます。Agent Teams はプロバイダーのモデルカタログを汎用的な命名スキームに書き換えることはありません。
例:
| プロバイダーパス | モデル ID の例 | 備考 |
| --- | --- | --- |
| Claude Code | `opus`、`sonnet`、または Claude モデルの完全な ID | 利用可否は Claude Code とアカウントアクセスに依存します |
| Codex | `gpt-5.4`、`gpt-5.3-codex` | 利用可否は Codex のアカウント／ランタイム状態に由来します |
| OpenCode | `openrouter/moonshotai/kimi-k2.6` | プレフィックスは OpenCode のプロバイダー設定と一致している必要があります |
モデル名が拒否される場合は、まずランタイム／プロバイダーで直接確認してください。チームブリーフを変更しても、利用不可のモデルを起動できるようにはなりません。
## マルチプロバイダー戦略
Agent Teams はオーケストレーションをプロバイダーを意識したものに保ちますが、プロバイダーに所有されることはありません:
- チーム、タスク、受信トレイ、コメント、レビュー状態、起動診断はローカルの Agent Teams ストレージに保持されます
- 各メンバーはチーム起動メタデータを通じてプロバイダー／モデル設定を保持できます
- モデルの利用可否、認証、レート制限、ツールの挙動はランタイム／プロバイダーの責務のままです
- 1 つのチームで複数のプロバイダー／モデルレーンを使用したい場合、OpenCode が最も広範なルーティングパスです
コントリビューター向けの境界と正規の実装ガイダンスについては、[コントリビューター向けアーキテクチャ](/ja/reference/contributor-architecture)を参照してください。
推奨パターン:
| パターン | 役立つ場面 | リスク |
| --- | --- | --- |
| すべてのメンバーに 1 つのプロバイダー | 初回の起動、機密性の高いリポジトリ、最もシンプルなデバッグ | 共有のレート制限がチーム全体を停止させる可能性があります |
| 強力なリード + 安価なビルダー | 実装コストを抑えつつ、計画／レビューの信頼性を維持する | ビルダーの出力にはより厳格なレビューが必要になる場合があります |
| ビルダーとレビュアーでモデルを分ける | モデル固有の見落としを捕捉する | セットアップと確認すべき帰属がより多くなります |
## プロバイダーのコスト
Agent Teams は無料でオープンソースです。同梱の無料モデルを使えば、認証なしで始められます。登録も API キーもクレジットカードも不要です。有料またはアカウントを基盤とするプロバイダーの利用は、選択したランタイム／プロバイダーによって管理されます。サブスクリプションの制限、API キー、アカウント認証、レート制限、プロバイダーのポリシーはすべて、アプリの外部に残ります。
## 機能チェック
セットアップ中、アプリはアクセスおよび機能のチェックを実行する場合があります。これは、チームの起動がプロビジョニングの途中で失敗する前に、不足しているランタイム認証を検出するのに役立ちます。
機能チェックは、プロバイダーは存在するが認証されていないこと、モデルリストが利用できないこと、ランタイムパスが見つからないこと、または特定の拡張機能がサポートされていないことを報告できます。それらの結果は、タスクの失敗ではなく、セットアップの診断として扱ってください。
一般的なセットアップの修正方法:
| チェック結果 | 対処方法 |
| --- | --- |
| ランタイムが見つからない | CLI をインストールするか、`PATH` を修正します |
| プロバイダーが未認証 | プロバイダーのログインフローを実行するか、必要な API キーを追加します |
| モデルが利用不可 | そのランタイムのモデルリストに表示されているモデルを選択します |
| 機能がサポートされていない | そのチームメイトには別のランタイムパスを使用します |
## 想定すべき制限
- ランタイムがサポートされているからといって、Claude Code、Codex、OpenCode の間で同等の機能パリティがあるとは限りません。
- ログとトランスクリプトのカバレッジはランタイムによって異なります。
- OpenCode のレーンは、アプリがランタイムログを安全に帰属させられるようになる前に、安定したレーン／セッションの証跡を必要とします。
- プロバイダーのモデル名と利用可否は、アプリの外部で変わる可能性があります。
- チームのプロンプトでは、不足している認証、不足している PATH エントリ、プロバイダーの障害、枯渇したレート制限を修正することはできません。

42
landing/product-docs/ja/reference/release-notes.md Normal file
View file

@ -0,0 +1,42 @@
---
title: リリースノート – Agent Teams ドキュメント
description: Agent Teams のリリースノートと変更履歴です。詳細は正規の RELEASE.md と CHANGELOG.md へのリンクをご覧ください。
lang: ja-JP
---
# リリースノート
現在のリリース: **v1.2.0**（2026-03-31）。`main` ブランチでは引き続き活発な開発が行われており、メンバーの作業同期、OpenCode 配信の堅牢化、CI の安定化に関する未リリースの変更があります。
## リリースの仕組み
Agent Teams は [セマンティック バージョニング](https://semver.org/) に従っています。リポジトリにプッシュされたタグは、自動の [リリースワークフロー](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) をトリガーし、macOS、Windows、Linux 向けの署名済みパッケージをビルドして、GitHub Releases に公開します。
## 最近のリリース
### v1.2.0 — Agent Graph、チーム単位のツール承認、対話型 AskUserQuestion
力学的レイアウトによる可視化とかんばんタスクレイアウトを備えた Agent Graph、読みやすい権限プロンプトを備えたチーム単位のツール承認コントロール、タスクコメント通知、対話型の AskUserQuestion ボタン。Write/Edit/NotebookEdit のシードと MCP ツールカタログ連携を含む権限システムの全面刷新。詳しくは [変更履歴の全文](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#120---2026-03-31) をご覧ください。
### v1.1.0 — React 19 + Electron 40、ユーザー起点のタスク開始
React 19 + Electron 40 への移行、かんばんボードからのユーザー起点のタスク開始、認証のトラブルシューティングガイド、R/Ruby/PHP/SQL のシンタックスハイライト、3 倍高速化したトランスクリプト検索、WSL/Windows のパス修正、XSS 脆弱性の修正。詳しくは [変更履歴の全文](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#110---2026-03-25) をご覧ください。
### v1.0.0 — 初回の一般公開リリース
最初の安定版ビルド: パッケージ化されたアプリでの CLI/認証の信頼性、IPC の堅牢化、署名済みの macOS ビルドを含むクロスプラットフォームのパッケージング、オープンソースのガバナンス文書（LICENSE、CONTRIBUTING、CODE_OF_CONDUCT、SECURITY）。詳しくは [変更履歴の全文](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#100---2026-03-23) をご覧ください。
## 正規の情報源
| ドキュメント | 説明 |
| --- | --- |
| [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) | リリースプロセス、バージョニングガイド、成果物の命名、自動更新のセットアップ、リリースノートのテンプレート。 |
| [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) | すべてのバージョンの機能、改善、バグ修正をユーザー視点でまとめた変更履歴の全文。 |
| [GitHub Releases](https://github.com/777genius/agent-teams-ai/releases) | すべてのプラットフォーム向けのダウンロード可能なインストーラー。 |
## 関連ページ
- [インストール](/ja/guide/installation)
- [クイックスタート](/ja/guide/quickstart)
- [コントリビューター向けアーキテクチャ](/ja/reference/contributor-architecture)
- [開発者向け](/ja/developers/)

69
landing/product-docs/zh/developers/index.md Normal file
View file

@ -0,0 +1,69 @@
---
title: 开发者中心 – Agent Teams 文档
description: 面向贡献者和开发者的 Agent Teams 入口，涵盖架构、护栏、调试以及 MCP 扩展路径。
lang: zh-Hans
---
# 开发者中心
当你想要修改 Agent Teams 本身、调试团队启动，或用 MCP 工具扩展某个运行时，请使用本页。下面的链接指向仓库中的权威文档，使实现规则集中在一处。
## 从这里开始
| 需求 | 前往 |
| --- | --- |
| 仓库概览、脚本与源码设置 | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) |
| 智能体导航与架构索引 | [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) |
| 面向智能体与贡献者的工作约定 | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) |
| 硬性实现护栏 | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) |
| 中型与大型功能的结构 | [功能架构标准](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) |
| 启动、引导与队友消息传递的调试 | [智能体团队调试手册](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) |
| 贡献流程 | [贡献指南](https://github.com/777genius/agent-teams-ai/blob/main/.github/CONTRIBUTING.md) |
| 发布说明 / 更新日志 | [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) — [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) |
## 本地开发路径
运行桌面端 Electron 应用进行常规开发：
```bash
pnpm install
pnpm dev
```
浏览器/网页路径并不能替代桌面端运行时。桌面模式是受支持的本地路径，因为它包含 IPC、终端、提供方鉴权、团队生命周期处理、启动诊断，以及真实团队所使用的运行时桥接。
## 架构检查点
在修改某个功能之前，先确定它的边界：
| 区域 | 预期归属 |
| --- | --- |
| 中型或大型产品功能 | `src/features/<feature-name>/` |
| Electron 主进程编排 | `src/main/` |
| Preload 安全 API 层 | `src/preload/` |
| 渲染器 UI 与应用状态 | `src/renderer/` |
| 共享类型与纯工具函数 | `src/shared/` |
| Agent Teams 看板 MCP 服务器 | `mcp-server/` |
| 看板数据控制器 | `agent-teams-controller/` |
使用 `src/features/recent-projects` 作为功能组织的参考切片。保持跨进程契约的显式化，并避免跨功能边界进行深层导入。
## 调试路径
针对启动挂起、OpenCode 的 `registered` / 引导未确认状态、队友回复缺失，或可疑的任务日志：
1. 从[调试手册](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md)开始。
2. 检查 `~/.claude/teams/<team>/launch-failure-artifacts/latest.json` 下最新的产物包。
3. 打开产物中的 `manifest.json`，检查 `classification`、引导面包屑、启动诊断、成员 spawn 状态以及经过脱敏的日志末尾片段。
4. 仅清理你能确认归属于本次冒烟测试或失败启动的团队、运行、面板或进程。
## MCP 开发路径
Agent Teams 使用一个名为 `agent-teams` 的内置 MCP 服务器进行看板操作。用户级和项目级的 MCP 服务器可以为运行时添加外部能力。设置示例、`.mcp.json` 结构以及工具注册指引，参见 [MCP 集成](/zh/guide/mcp-integration)。
## 相关文档
- [贡献者架构](/zh/reference/contributor-architecture)
- [运行时设置](/zh/guide/runtime-setup)
- [MCP 集成](/zh/guide/mcp-integration)
- [故障排查](/zh/guide/troubleshooting)

121
landing/product-docs/zh/guide/agent-workflow.md Normal file
View file

@ -0,0 +1,121 @@
---
title: 智能体工作流 – Agent Teams 文档
description: 了解任务生命周期、看板、消息、任务日志、并行工作、实时进程以及跨团队通信。
lang: zh-Hans
---
# 智能体工作流
Agent Teams 通过任务状态、消息、日志以及可审查的代码变更，让智能体的工作变得可见。
## 模式
| 模式 | 说明 |
| --- | --- |
| Solo | 单个队友，自行管理任务 |
| Team | 多个队友并行工作，互相审查 |
两种模式共享相同的看板、任务日志和代码审查界面。
## 任务生命周期
Agent Teams 沿着两个独立维度跟踪每个任务：工作状态与审查状态。
| 维度 | 状态 | 说明 |
| --- | --- | --- |
| 工作状态 | `pending`、`in_progress`、`completed` | 跟踪任务是处于等待、正在被处理，还是已被负责人完成 |
| 审查状态 | `none`、`review`、`needsFix`、`approved` | 跟踪任务在完成后审查流程中所处的位置 |
看板展示的是组合后的视图，但这两个维度各自独立移动。
### 工作状态流转
| 阶段 | 发生的事情 | 负责人 |
| --- | --- | --- |
| Pending | 任务已创建并就绪，但还没有人开始处理 | Lead 或用户 |
| In progress | 智能体进行工作，并通过看板 MCP 工具更新任务状态 | 队友 |
| Completed | 负责人发布一条结果评论，并将任务标记为完成 | 队友 |
### 审查状态流转
| 阶段 | 发生的事情 | 负责人 |
| --- | --- | --- |
| None | 任务尚未进入审查（可能处于 pending、in progress 或刚刚 completed） | — |
| Review | 已请求审查；审查者检查 diff 与结果 | 审查者 |
| Needs fix | 审查期间提出了变更要求；负责人必须更新 | 队友（负责人） |
| Approved | 审查通过；任务定稿 | 审查者 |
### 规划 → In progress
当队友开始一项任务时，工作状态变为 `in_progress`。智能体创建一条包含其计划的任务评论，并继续工作。所有原生工具操作（read、bash、edit、write）都会被流式记录到任务日志中。
### Completed → Review
当队友完成工作后，它会发布一条结果评论，并将工作状态标记为 `completed`。随后 lead 或审查者可以请求审查，以启动审查流程。
### Review → Approved
如果审查界面显示变更可以接受，则批准该审查。任务随即定稿，并与其 diff 关联。
::: warning Fix-first review
如果在审查期间要求队友做出变更，它应当发布一条包含修复内容的后续评论，然后 lead 即可批准。
:::
## 看板
看板是主要的操作界面。它让你能够：
- 浏览处于打开、被阻塞和审查中的工作
- 打开任务详情并查看运行时日志
- 无需阅读原始会话文件即可审查变更
- 指派或重新指派负责人
::: tip
使用卡片上的快捷操作按钮来开始、完成或请求审查，无需打开详情面板。
:::
## 消息与评论
| 渠道 | 何时使用 |
| --- | --- |
| 私信 | 重新引导某个智能体、快速提问 |
| 任务评论 | 属于某个特定任务的备注 |
评论为后续审查保留了上下文，并出现在任务时间线中。
::: tip 优先使用任务评论
如果备注是关于某个特定任务的，请将其作为该任务的评论添加，而不是发送私信。这样能让历史记录与工作保持关联。
:::
## 任务日志
任务专属日志为单个指派隔离出运行时输出、操作和消息。用它们来回答：
- 这个智能体运行了什么？
- 它为什么更改了这个文件？
- 它是否向另一位队友求助过？
- 是哪个任务产生了这个 diff？
### 验证清单
当某个任务看起来卡住，或其 diff 看起来与任务脱节时，按以下顺序验证生命周期：
1. 任务拥有预期的负责人，并已转入 `in_progress`。
2. 负责人发布了一条包含计划或首次进度更新的任务评论。
3. 任务日志显示在任务时间窗口内有运行时活动。
4. 文件变更与同一个任务、负责人和会话相关联。
5. 最后一条任务评论包含验证命令及其结果。
如需更深入的调试，请使用[故障排查](/zh/guide/troubleshooting#task-log-triage)中的持久化证据命令。UI 是工作界面，但对于棘手的启动或归属错误，持久化的任务文件、收件箱和运行时证据才是真正的依据。
## 并行工作模式
队友可以同时处理相互独立的任务。你还可以创建依赖关系（`blocked-by`），让一个任务等待另一个任务完成。留意看板上被阻塞的泳道，如果一位队友空闲而另一位负担过重，则重新指派负责人。
## 实时进程
当智能体启动本地服务器或工具时，实时进程区域会显示 URL 和正在运行的进程。直接从应用中打开这些 URL 即可查看结果。进程会一直保持注册状态，直到被显式停止或运行时退出。
## 跨团队通信
当团队之间已建立关联时，智能体可以向其他团队发送消息。可将其用于工作交接、共享库，或各小队之间的状态检查。

119
landing/product-docs/zh/guide/code-review.md Normal file
View file

@ -0,0 +1,119 @@
---
title: 代码审查 – Agent Teams 文档
description: 检查任务范围内的差异（diff），接受或拒绝代码块（hunk），留下行内评论，并管理从 none 到 approved 的审查状态。
lang: zh-Hans
---
# 代码审查
Agent Teams 中的代码审查以任务为中心。你检查的是某个特定任务发生了哪些变更，而不是在一大堆无结构的差异中翻找。
## 审查界面
对于每个触及文件的已完成任务，审查 UI 让你能够：
- 在带有变更前/后上下文的情况下检查变更的文件
- 接受或拒绝单个代码块（hunk）
- 留下行内评论
- 将差异关联回任务描述和智能体日志
## 代码块（hunk）级别的决策
接受细小且正确的变更，并拒绝个别的错误，而无需丢弃整个任务。当某个智能体基本上解决了任务，但在某个文件上做得过头时，这种方式很有用。
::: tip 增量接受
如果一份差异大体正确，先接受好的代码块，只对需要修复的部分请求修改。这样可以让看板持续向前推进。
:::
在以下情形使用代码块（hunk）级别的决策：
| 情形 | 操作 |
| --- | --- |
| 范围正确的变更 | 接受该代码块 |
| 思路正确，但文件错误或重构范围过宽 | 拒绝该代码块并请求一个更窄的修复 |
| 行为变更不明确 | 评论并要求验证 |
| 生成的格式噪音 | 拒绝，除非格式调整本就是任务的一部分 |
## 发起审查
1. 打开一个已完成的任务
2. 查看 **Changes** 标签页
3. 如果差异看起来合理，点击 **Request Review** 将任务移入审查（review）列
在审查期间，任务尚未被视为完成，因此其他队友或 lead 仍可以对其发表评论。
## 审查循环
一个健康的审查循环看起来是这样的：
1. 任务负责人发表一条结果评论，说明变更范围和验证情况
2. 审查者打开任务差异，并对照任务描述检查各个代码块
3. 审查者接受好的代码块、拒绝差的代码块，或请求修改
4. 负责人只修复所请求的范围，并发表一条后续评论
5. 当任务结果与差异相匹配时，审查者予以批准
请求修改评论的示例：
```text
Please keep the copy improvements, but revert the unrelated runtime wording in the provider table. Add the `pnpm --dir landing docs:build` result before resubmitting.
```
## 审查状态
| 状态 | 含义 |
| --- | --- |
| `none` | 任务为新建、进行中，或已完成但尚未进入审查 |
| `review` | 任务正在被积极审查 |
| `needsFix` | 已请求修改；负责人必须先更新才能再次批准 |
| `approved` | 审查已被接受，任务已最终确定 |
## 智能体审查工作流
在你做出最终决定之前，团队之间可以相互审查彼此的工作。这能捕捉到明显的回归，并让看板保持真实，但你仍应亲自审查有风险的区域。
当审查者拥有清晰的评分标准（rubric）时，智能体审查最为有用。例如，让一个审查者只检查文档的清晰度、只检查 IPC 安全性，或只检查测试覆盖率。宽泛的“审查所有内容”请求往往会产生较弱的反馈。
### MCP 驱动的审查状态
审查状态的变更（请求审查、请求修改、批准）是由工具驱动的。在任务上留下一条“请求修改”的评论**并不会**将看板列移动到 `needsFix` —— 必须由 lead 或智能体调用相应的 MCP 工具：
- `review_request_changes` —— 将任务移动到 `needsFix` 并通知负责人
- `review_approve` —— 将任务移动到 `approved` 并最终确定审查
仅凭评论不足以触发状态转换。有关审查类 MCP 工具及其参数的完整列表，请参阅 [MCP 集成](/zh/guide/mcp-integration)。
## 审查参与者
团队 lead 是默认的审查者。如果你希望同伴之间相互审查工作，可以在 Kanban 设置中配置额外的审查者。
## 需要手动检查的内容
审查时优先关注以下区域：
- **提供方认证与运行时检测** —— 智能体是否以会破坏其他路径的方式更改了运行时设置？
- **IPC、preload 与文件系统边界** —— 保持 Electron 各项职责相互分离
- **Git 与 worktree 行为** - 验证分支命名、提交和推送；隔离模式请参阅 [Git 与 worktree 策略](/zh/guide/git-worktree-strategy)。
- **解析与任务生命周期逻辑** —— 对任务引用、分块（chunking）或过滤的更改可能破坏消息投递
- **持久化与代码审查流程** —— 对任务存储或审查状态的更改必须在各 IPC 层之间保持一致
有关规范的功能布局和硬性护栏（guardrail）链接，请使用 [贡献者架构](/zh/reference/contributor-architecture)。
## 验证
优先使用聚焦的验证命令。除非任务明确打算进行大范围的格式整理，否则不应使用宽泛的格式化或 lint-fix 命令。
好的验证评论包含命令及其结果：
```text
Verified with `pnpm --dir landing docs:build`. Build passed.
```
当跳过验证时，任务评论应说明原因：
```text
Docs-only wording change. Build not run because the existing dev server was busy; checked Markdown links manually.
```
::: warning 不要在整个项目范围内自动格式化
除非任务专门关于格式化，否则避免对无关文件运行 `pnpm lint:fix`。它会在审查界面中制造噪音。
:::

106
landing/product-docs/zh/guide/create-team.md Normal file
View file

@ -0,0 +1,106 @@
---
title: 创建团队 – Agent Teams 文档
description: 定义角色、分配提供方与模型、编写团队简报，并配置 worktree 隔离与自主级别。
lang: zh-Hans
---
# 创建团队
团队是一组具名的智能体，它们拥有各自的角色、一个 lead、一个目标项目以及一段协调提示词。
## 推荐的第一个团队
从一个小团队起步：
| 角色 | 用途 |
| -------- | --------------------------------------------------- |
| Lead | 拆分工作、创建任务、协调队友 |
| Builder | 实现范围明确的任务 |
| Reviewer | 审查产出、捕捉回归、提出修复请求 |
这样的构成提供了足够的协调能力，让你在不让首次启动过于嘈杂的情况下，就能看到产品价值。
::: tip
你可以稍后再添加更多成员。先从小处着手，验证工作流，然后再扩大规模。
:::
## 分配提供方与模型
每个团队成员都运行在某个提供方后端上。在团队编辑器中，为每个成员选择一个提供方（Claude、Codex 或 OpenCode）和一个模型。应用只会显示你已经完成身份验证的提供方。
支持在一个团队中混用多个提供方——例如，一个 Claude lead 搭配若干 OpenCode builders。
::: info
Gemini 作为受支持的提供方路径可用。有关身份验证选项和当前提供方状态，请参阅[提供方与运行时](/zh/reference/providers-runtimes)。
:::
## 编写一份好的团队简报
团队简报应包含：
- 你想要的结果
- 重要的文件或功能领域
- 风险边界，例如“不要重构无关的模块”
- 审查预期
- 在你知道的情况下提供验证命令
示例：
```text
Build a focused improvement to the download flow. Keep changes inside the landing app unless a shared helper is clearly needed. Create tasks before implementation, review each task diff, and run landing lint/build checks.
```
## worktree 隔离
OpenCode 成员可以使用 **worktree 隔离**，在一个独立的 Git worktree 中工作，而不是在主工作目录中。这可以防止多个智能体编辑同一个项目时产生文件冲突。
::: warning
worktree 隔离要求项目处于 Git 跟踪之下，并且目前仅限于 OpenCode 成员。
:::
要启用它，请在添加或编辑某个 OpenCode 团队成员时切换 **Worktree isolation** 选项。
## 选择自主级别
Agent Teams 支持不同级别的控制。对于常规改动使用更高的自主级别，而对于诸如提供方身份验证、IPC、持久化、Git 工作流以及发布工具等高风险领域，则采用更严格的审查。
### 努力级别
每个团队成员都有一个 **effort**（努力）设置，用于控制提供方在响应之前投入多少推理。更高的努力级别会产出更全面的结果，但代价是时间和 token。
| 级别 | 何时使用 |
| ------ | ---------------------------------------------------------- |
| Low | 快速查询、小幅格式调整、常规编辑 |
| Medium | 大多数实现任务的默认级别 |
| High | 复杂的重构、横切性改动、高风险的代码路径 |
应用为支持相应能力的提供方提供了额外的级别（minimal、xhigh、max）。如果某个模型不支持可配置的努力级别，则该选择器会被禁用，并使用提供方的默认值。
### 快速模式
可按成员切换 **Fast mode**（快速模式），以优先考虑速度而非深度。当可用时，它会映射到提供方原生的 fast/speed 模式。将其设为 **On** 用于常规任务，设为 **Off** 用于需要细致处理的工作，或设为 **Inherit** 以遵循团队级别的默认设置。
### 限制上下文
启用 **Limit context**（限制上下文）以缩减某个成员的上下文窗口。这对于支持扩展上下文（例如 1M token）的 Claude 模型很有用——限制上下文可以避免不必要的 token 占用，并且对于不需要大上下文的任务还能改善延迟。
## 添加上下文
当文件、截图或特定说明会实质性地改变任务时，将它们附加进去。智能体可以将任务描述、评论和附件用作持久的上下文。
## 关注任务质量
优秀的团队所创建的任务应当是：
- 足够具体以便审查
- 足够小以便完成
- 与可见的产出相关联
- 有验证路径作为支撑
如果 lead 创建了含糊的任务，请发送一条私信，要求拆分成更小、可测试的任务。
## 后续步骤
- [运行时设置](/zh/guide/runtime-setup) — 配置提供方身份验证与模型
- [代码审查](/zh/guide/code-review) — 接受、拒绝或评论智能体的改动
- [故障排查](/zh/guide/troubleshooting) — 常见问题与修复

102
landing/product-docs/zh/guide/git-worktree-strategy.md Normal file
View file

@ -0,0 +1,102 @@
---
title: Git 与 worktree 策略 – Agent Teams 文档
description: 决定何时使用主 worktree、功能分支或 OpenCode worktree 隔离来进行并行智能体工作。
lang: zh-Hans
---
# Git 与 worktree 策略
Git 为 Agent Teams 提供了最强的审查路径：精简的 diff、分支可见性、任务范围内的变更，以及更安全的并行工作。
## 选择一种策略
| 策略 | 适用场景 | 取舍 |
| --- | --- | --- |
| 主 worktree | 单人工作、仅文档编辑，或一次只有一个队友 | 简单，但并行编辑可能发生冲突 |
| 功能分支 | 一个团队正在进行一项连贯的变更 | 审查目标清晰，但队友仍共享文件 |
| Worktree 隔离 | 多个 OpenCode 队友可能并行编辑同一个仓库 | 隔离性更好，但合并/审查需要更多纪律 |
从简单开始。当可能出现并行编辑时再加入 worktree 隔离，而不是因为每个任务都需要单独的检出（checkout）。
## 何时启用 worktree 隔离
在以下情况下为 OpenCode 队友启用它：
- 两个或更多队友可能同时编辑同一个仓库
- 某个任务可能运行格式化工具、代码生成器或大范围测试
- 你希望每个队友的分支和 diff 保持彼此独立
- lead 工作区是脏的（dirty），不应接收直接编辑
在以下情况下保持关闭：
- 任务是只读的
- 一个队友负责所有编辑
- 仓库未被 Git 跟踪
- 你需要一条不支持此隔离模式的运行时路径
::: warning
Worktree 隔离目前仅适用于 OpenCode 成员，并且要求项目被 Git 跟踪。
:::
## 分支卫生
在开始并行工作之前：
```bash
git status --short
git branch --show-current
```
尽可能使用干净的分支。如果主 worktree 已经有用户的改动，请告知智能体不要还原（revert）不相关的文件，并保持任务范围精简。
推荐的分支命名风格：
```text
agent/<team-or-task>/<short-purpose>
```
示例：
```text
agent/docs/mcp-guide
agent/review/task-log-filtering
agent/ui/code-review-polish
```
## 审查流程
对于隔离的 worktree，在将变更合并或应用回主工作区之前，先审查队友的 diff。
1. 确认任务结果评论中说明了变更范围和验证情况。
2. 在审查 UI 中检查任务 diff。
3. 如果 diff 触及了不相关的文件，则对该任务请求修改（request changes）。
4. 仅在测试或手动检查与任务风险相匹配后才批准（approve）。
5. 有意识地合并或应用变更。
不要仅仅因为任务已完成就自动合并 worktree 的产出。完成只意味着智能体认为这项工作已准备好接受审查。
## 冲突处理策略
针对并行团队，使用以下策略：
| 情形 | 操作 |
| --- | --- |
| 两个队友编辑同一个文件 | 暂停其中一个任务，或指定一个负责人来负责整合 |
| 生成的文件被大范围改动 | 要求附上一条评论，说明所用的生成器和命令 |
| 主 worktree 有不相关的改动 | 保留这些改动，仅审查任务所属的变更 |
| Worktree 分支出现分叉 | 在审查后手动 rebase 或 merge，而不要在一个含糊不清的智能体任务内部进行 |
## 任务提示词示例
```text
Implement the settings validation fix in your assigned worktree. Keep edits inside src/features/settings and focused tests. Do not touch provider auth or task storage. Post the test command and result before completing the task.
```
这条提示词之所以有效，是因为它指明了允许的区域、敏感的边界以及完成的证据。
## 相关指南
- [创建团队](/zh/guide/create-team)
- [代码审查](/zh/guide/code-review)
- [团队简报示例](/zh/guide/team-brief-examples)
- [运行时设置](/zh/guide/runtime-setup)

129
landing/product-docs/zh/guide/installation.md Normal file
View file

@ -0,0 +1,129 @@
---
title: 安装 – Agent Teams 文档
description: 下载并在 macOS、Windows 或 Linux 上安装 Agent Teams。涵盖打包构建、源码设置、自动更新以及环境要求。
lang: zh-Hans
---
# 安装
Agent Teams 以桌面应用的形式分发，支持 macOS、Windows 和 Linux。
::: tip 最短路径
1. 在下方下载适合你平台的构建版本
2. 启动应用 - 先使用无需认证的免费模型，或从界面中连接提供方认证
3. 开始[快速开始](/zh/guide/quickstart)，创建你的第一个团队
桌面应用启动：运行 `pnpm dev` 来启动 Electron 应用。日常使用时请勿启动浏览器/网页开发模式。
:::
## 下载构建版本
当你需要打包好的应用时，请使用<a href="/zh/download/" target="_self">下载页面</a>或最新的 [GitHub release](https://github.com/777genius/agent-teams-ai/releases)：
- macOS Apple Silicon：`.dmg`
- macOS Intel：`.dmg`
- Windows：`.exe`
- Linux：`.AppImage`、`.deb`、`.rpm` 或 `.pacman`
::: warning Windows SmartScreen
未签名或新发布的开源应用可能会触发 SmartScreen。如果你信任该发布来源，请选择 **More info**，然后选择 **Run anyway**。
:::
## 环境要求
打包好的应用旨在实现零设置上手。你可以先使用无需认证的免费模型 - 无需注册、API 密钥或信用卡。如果你想要更多模型，应用会引导你从界面中完成运行时检测和提供方认证。
对于付费或需要账户支持的模型，请至少连接一个提供方：
| 提供方 | 接入方式 |
| ------------------ | ------------------------------------------------- |
| Claude (Anthropic) | Claude Code CLI 登录或 API 密钥 |
| Codex (OpenAI) | Codex CLI 登录或 API 密钥 |
| Gemini (Google) | Google ADC、Gemini CLI 或 API 密钥 |
| OpenCode | 内置的无需认证免费模型，或用于受支持后端（例如 OpenRouter）的 API 密钥 |
::: info
Gemini 作为受支持的提供方路径提供。关于所有提供方的认证选项和当前状态，请参阅[提供方与运行时](/zh/reference/providers-runtimes)。
:::
对于源码开发，你还需要：
| 工具 | 版本 |
| ------- | ------- |
| Node.js | 24.16.0 LTS |
| pnpm | 10+ |
在 macOS 上，官方的 Node.js 24 预编译二进制文件需要 macOS 13.5+。
## 从源码运行
<InstallBlock command="git clone https://github.com/777genius/agent-teams-ai.git && cd agent-teams-ai && pnpm install && pnpm dev" label="复制" copied-label="已复制" />
```bash
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
pnpm dev
```
`pnpm dev` 会启动带有热重载的桌面 Electron 应用。这是默认的开发目标 — 日常开发时请勿启动浏览器网页开发服务器。浏览器路径缺少完整的桌面 IPC、终端、提供方认证以及团队生命周期行为。
`main` 分支承载着最新的稳定开发版本。仅当你需要某个特定的未发布变更时，才切换到功能分支。
## 验证设置
安装完成后，确认构建状态正常：
```bash
# Check that the desktop app compiles and starts
pnpm typecheck
# Verify the VitePress documentation site builds
pnpm --dir landing docs:build
```
如果 `pnpm typecheck` 报告类型错误，请检查依赖项是否有较新版本，或者固定的 TypeScript 版本。如果 `pnpm --dir landing docs:build` 失败，请检查 `landing/product-docs/` 中 markdown 或配置文件的语法错误。
如果你正在编辑这些文档，请运行构建以验证你的更改：
```bash
pnpm --dir landing docs:build
```
## 自动更新
打包好的应用会在启动时以及运行过程中定期自动检查更新。当有可用更新时，应用会提示你下载并安装。你也可以从应用菜单手动检查。
::: tip
从源码运行时无法使用自动更新。当依赖项发生变化时，请拉取最新更改并重新运行 `pnpm install`。
:::
## 从源码更新
如果你从源码运行，当依赖项发生变化时，请拉取 `main` 分支并重新运行安装：
```bash
git pull
pnpm install
```
更新后，验证构建和文档：
```bash
pnpm typecheck
pnpm --dir landing docs:build
```
日常开发请始终使用 `pnpm dev`（Electron）— 而不是浏览器开发服务器。
## 后续步骤
- [快速开始](/zh/guide/quickstart) — 从安装到运行第一个团队
- [运行时设置](/zh/guide/runtime-setup) — 按运行时配置提供方认证和模型选择
- [创建团队](/zh/guide/create-team) — 推荐的团队形态与简报撰写
### 面向贡献者
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — 仓库导航与架构指引
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — 工作约定与项目规则
- [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) — 硬性实现护栏

225
landing/product-docs/zh/guide/mcp-integration.md Normal file
View file

@ -0,0 +1,225 @@
---
title: MCP 集成 – Agent Teams 文档
description: 在 Agent Teams 中配置 MCP，用于看板操作、队友协作、外部工具服务器以及自定义工具开发。
lang: zh-Hans
---
# MCP 集成
Agent Teams 在两个实用层级上使用 MCP：
| 层级 | 作用 | 使用者 |
| --- | --- | --- |
| 内置看板服务器 | 暴露 Agent Teams 的任务、消息、审查、进程、运行时以及跨团队工具 | 由应用启动的 lead 与队友 |
| 外部 MCP 服务器 | 添加可选工具，例如浏览器自动化、设计上下文、文档搜索或公司系统 | 用户与已配置的运行时 |
请将这两个层级分开看待。内置的 `agent-teams` MCP 服务器是智能体在 Agent Teams 内部进行协作的方式。外部 MCP 服务器则是可选的运行时工具。
## Agent Teams 如何注入 MCP
当桌面应用启动基于 Claude 的团队成员时，它会写入一个临时的 `--mcp-config` JSON 文件，其中包含内置的 `agent-teams` 服务器：
```json
{
"mcpServers": {
"agent-teams": {
"command": "node",
"args": ["/path/to/agent-teams-mcp/index.js"],
"env": {
"AGENT_TEAMS_MCP_CLAUDE_DIR": "/Users/you/.claude"
}
}
}
}
```
在开发环境中，该命令可能通过 `tsx` 指向 `mcp-server/src/index.ts`。在打包构建中，应用会将捆绑的 MCP 服务器复制到一个稳定的应用数据路径，并使用 Node 运行它。生成的文件归应用所有，并会尽力清理。
用户级和项目级的 MCP 服务器保持独立。应用从以下位置读取已安装的服务器：
| 范围 | 位置 |
| --- | --- |
| 用户 | `~/.claude.json` 中的 `mcpServers` |
| Claude 配置中的本地项目条目 | `~/.claude.json` 中的 `projects[projectPath].mcpServers` |
| 项目 | `<project>/.mcp.json` 中的 `mcpServers` |
对于属于某一个仓库的工具，优先使用项目范围。对于你要在多个不相关项目中复用的工具，优先使用用户范围。
## 项目 `.mcp.json` 示例
当一个团队应当看到相同的项目范围服务器时，将此文件放在项目根目录：
```json
{
"mcpServers": {
"docs-search": {
"command": "npx",
"args": ["-y", "@acme/docs-search-mcp"],
"env": {
"DOCS_INDEX_PATH": "./docs-index"
}
},
"local-browser": {
"command": "node",
"args": ["./tools/mcp/browser-server.js"]
}
}
}
```
不要把密钥放进已提交的 `.mcp.json` 文件。如果某个值必须保留在本地，请把凭据放在你的 shell、用户范围配置中，或应用的自定义 MCP 安装流程中。
## 看板 MCP 工作流
当工作属于某个任务时，智能体应当使用看板 MCP 工具：
1. 读取最新的任务上下文。
2. 仅在真正开始工作时才启动任务。
3. 为阻塞项、计划和最终结果添加任务评论。
4. 在发布结果评论后将任务标记为完成。
5. 当 lead 或队友需要知道结果时，发送一条简短消息。
智能体流程示例：
```text
task_get -> task_start -> edit/test -> task_add_comment -> task_complete -> message_send
```
用直接消息进行协作。用任务评论保存持久的任务历史。
::: tip
如果该备注涉及审查、验证、变更范围或某个阻塞项，请把它放在任务上。
:::
## 内置 Agent Teams 工具
MCP 服务器从 `agent-teams-controller/src/mcpToolCatalog.js` 注册工具。注册循环位于 `mcp-server/src/tools/index.ts`，每个分组在 `mcp-server/src/tools/` 下有自己的文件。
常用运维工具：
| 工具 | 用途 |
| --- | --- |
| `task_get` | 读取最新的任务上下文、评论、附件、状态以及关联关系 |
| `task_start` | 在工作真正开始时将任务标记为 in progress |
| `task_add_comment` | 添加阻塞项备注、验证备注、计划以及最终结果摘要 |
| `task_complete` | 在发布最终结果评论后完成任务 |
| `message_send` | 向 lead、队友或用户发送一条可见的收件箱消息 |
| `review_request`、`review_start`、`review_approve`、`review_request_changes` | 推进任务范围的审查工作流 |
| `process_register`、`process_list`、`process_stop`、`process_unregister` | 跟踪队友拥有的开发服务器、监听器以及其他后台服务 |
工具名称在运行时可能带有 MCP 命名空间前缀，例如 `mcp__agent-teams__task_get`。在 MCP 服务器内部，规范的工具名称仍然是 `task_get`。
## 注册一个新的内置工具
对于 Agent Teams 仓库的工作，请通过现有的 FastMCP 结构添加内置看板工具：
1. 将工具实现添加到 `mcp-server/src/tools/` 中匹配的文件，如果该领域确实是全新的，则创建一个新的分组文件。
2. 将工具名称添加到 `agent-teams-controller/src/mcpToolCatalog.js` 中相应的分组。
3. 仅在需要新的领域分组时，才通过 `mcp-server/src/tools/index.ts` 接入新分组。
4. 使用 `zod` 校验输入，并调用控制器 API，而不是直接读取看板文件。
5. 在 `mcp-server/test/tools.test.ts` 中添加针对性测试，或在传输层很重要时添加一个 e2e 用例。
最小结构：
```ts
server.addTool({
name: 'task_example',
description: 'Explain what this tool does for agents.',
parameters: z.object({
teamName: z.string().min(1),
claudeDir: z.string().min(1).optional(),
taskId: z.string().min(1)
}),
execute: async ({ teamName, claudeDir, taskId }) => {
assertConfiguredTeam(teamName, claudeDir);
const controller = getController(teamName, claudeDir);
return jsonTextContent(controller.tasks.getTask(taskId));
}
});
```
不要创建绕过控制器校验、改动无关团队文件，或在没有明确任务需要的情况下暴露宽泛文件系统/进程访问权限的工具。
## 外部 MCP 服务器
当队友需要一个持久的工具连接，而不仅仅是一次带粘贴上下文的提示时，请使用外部 MCP 服务器。
适用场景：
- 浏览器或网站测试工具
- 设计或产品数据工具
- 内部文档与搜索系统
- 问题跟踪或支持系统
- 使用只读凭据的数据库检查工具
不适用场景：
- 粘贴进提示的密钥
- 可以直接附加的一次性文件
- 未经审查就改动生产系统的工具
- 当更窄的项目范围已经足够时，却使用宽泛的本地文件系统访问
## 范围
Agent Teams 识别共享范围和面向项目的 MCP 范围。
| 范围 | 适用情形 |
| --- | --- |
| 用户或全局 | 同一个服务器应当在多个项目间可用 |
| 项目或本地 | 该服务器属于某一个仓库、工作区或团队上下文 |
优先选择仍能让工作流可用的最窄范围。项目范围的服务器在审查时更易于推理，因为该工具属于正在被修改的项目。
## 设置检查清单
在分配一个依赖某个 MCP 服务器的任务之前：
1. 安装或配置该服务器。
2. 确认它出现在应用针对目标范围的已安装 MCP 列表中。
3. 在可用时，从 MCP 注册表或扩展 UI 运行诊断。
4. 从一个低风险的只读任务开始。
5. 在任务描述或团队简报中提及预期的 MCP 工具使用方式。
如果某个服务器诊断失败，请先修复它。更好的任务提示并不能修复缺失的命令、错误的配置路径或被拒绝的凭据。
## 从应用安装自定义服务器
桌面应用通过 Electron IPC 暴露 MCP 注册表 API，用于搜索、浏览、安装、自定义安装、卸载、读取已安装状态以及诊断。自定义安装会在调用运行时安装路径之前，校验服务器名称、范围、项目路径、环境变量名以及 HTTP 标头。
当你有一个尚未进入注册表的 MCP 包时，使用自定义安装：
| 字段 | 示例 |
| --- | --- |
| 服务器名称 | `docs-search` |
| 范围 | `project` 表示此仓库，`user` 表示所有项目 |
| 类型 | `stdio` 表示本地命令，`http` 或 `sse` 表示远程服务器 |
| 包 | `@acme/docs-search-mcp` |
| 环境变量 | `DOCS_INDEX_PATH=./docs-index` |
安装后，运行诊断并创建一个小型的只读任务来验证工具界面，然后再分配更大的工作。
## 任务示例
```text
Audit the docs home page with the browser MCP. Check desktop and mobile widths, capture any layout issue as a task comment, and only edit landing/product-docs files. Run `pnpm --dir landing docs:build` before completion.
```
这之所以有效，是因为它指明了工具、操作界面、写入边界以及验证步骤。
## 安全规则
- 不要默认给每个队友都配上每一个 MCP 服务器。
- 除非审查需要，否则将具备写入能力的工具排除在宽泛团队之外。
- 检查类任务优先使用只读凭据。
- 把会影响生产的工具使用置于明确的任务评论和审查之后。
- 将 MCP 诊断失败视为设置失败，而非智能体失败。
- 避免在 `.mcp.json` 或提示中提交密钥。
- 通过应用安装项目范围服务器时，使用绝对路径的 `projectPath` 值。
- 不要编辑应用生成的 `agent-teams-mcp-*.json` 文件；它们是临时的启动产物。
## 相关指南
- [运行时设置](/zh/guide/runtime-setup)
- [团队简报示例](/zh/guide/team-brief-examples)
- [智能体工作流](/zh/guide/agent-workflow)
- [开发者](/zh/developers/)

193
landing/product-docs/zh/guide/quickstart.md Normal file
View file

@ -0,0 +1,193 @@
---
title: 快速开始 – Agent Teams 文档
description: 在几分钟内，从全新安装到运行起一个 AI 智能体团队。涵盖安装、运行时选择、团队创建以及首次代码审查。
lang: zh-Hans
---
# 快速开始
本指南帮助你在几分钟内，从全新安装到运行起一个团队。
## 最短路径
```bash
# 1. Install prerequisites
node --version # need 20+
pnpm --version # need 10+
# 2. Clone and install
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
# 3. Start the desktop app (default workflow)
pnpm dev
# 4. Verify a docs-only change
pnpm --dir landing docs:build
```
桌面端 Electron 应用（`pnpm dev`）是首要目标——常规开发中请勿使用浏览器/Web 开发服务器。浏览器路径缺少桌面端 IPC、终端、提供方认证以及团队生命周期行为。
## 开始之前
你需要：
- **一台计算机**，运行 macOS、Windows 或 Linux
- **（推荐）一个由 Git 跟踪的项目**——worktree 隔离与 diff 审查都依赖 Git
- **（可选）提供方访问权限**——运行时设置会从 UI 中检测可用的提供方，但某些路径需要已有的认证（Anthropic、OpenAI 等）
如果下面的某个步骤无法奏效，请查阅[故障排查指南](/zh/guide/troubleshooting#team-does-not-launch)以获取常见修复方法。
关于项目约定与架构指引，在做出改动之前请先参考以下规范文件：
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — 仓库导航与架构指引
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — 工作约定与项目规则
- [功能架构标准](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) — 新功能的结构
- [调试操作手册](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) — 启动与队友诊断
## 1. 从源码运行或下载
**下载已打包的应用**（适用于 macOS、Windows 或 Linux），请前往<a href="/zh/download/" target="_self">下载页面</a>——无需任何前置条件。你可以从免费模型开始、无需认证，或在需要更多模型时从 UI 连接提供方认证。
**或从源码运行**以进行开发：
需要 Node.js 24.16.0 LTS 和 pnpm 10+。在 macOS 上，官方 Node.js 24 预编译二进制文件要求 macOS 13.5+。
```bash
git clone https://github.com/777genius/agent-teams-ai.git
cd agent-teams-ai
pnpm install
pnpm dev
```
`pnpm dev` 会启动支持热重载的桌面端 Electron 应用。这是默认的开发目标。常规开发中请勿启动浏览器 Web 开发服务器——浏览器路径缺少完整的桌面端 IPC、终端、提供方认证以及团队生命周期行为。
## 2. 打开或创建一个项目
启动应用，并选择你希望智能体在其中工作的项目目录。Agent Teams 会读取本地项目文件以及运行时/会话状态，以便 UI 能够展示任务、日志、diff 以及队友活动。
::: tip
选择一个由 Git 跟踪的项目以获得最佳体验。worktree 隔离与基于 diff 的审查都依赖 Git。
:::
在启动团队之前，请检查项目是否有一个足够干净的基线：
```bash
git status --short
```
你不需要一个完全干净的工作树，但在智能体开始编辑之前，你应当清楚哪些改动是你自己的。这能让任务 diff 与代码块（hunk）级别的审查更值得信赖。
## 3. 选择运行时路径
设置流程会自动检测你机器上已安装的运行时。常见的首次设置是：
| 运行时 | 适用于 |
| -------- | ----------------------------------------------- |
| Claude | Claude Code 用户以及已有 Anthropic 访问权限的人 |
| Codex | Codex 原生工作流以及 OpenAI 访问权限 |
| OpenCode | 免费模型、无需认证，多模型团队，以及众多提供方后端 |
::: info
Gemini 作为受支持的提供方路径提供。有关认证选项以及当前提供方状态，请参阅[提供方与运行时](/zh/reference/providers-runtimes)。
:::
有关每个提供方的详细配置，请参阅[运行时设置](/zh/guide/runtime-setup)。
要在应用之外验证一个付费或基于账户的运行时，请检查二进制文件并测试认证：
```bash
# Check that the runtime is installed and on PATH
command -v claude && claude --version
command -v codex && codex --version
command -v opencode && opencode --version
```
如果命令失败，请先修复运行时安装或 `PATH`。对于需要认证的模型，团队提示无法绕过缺失的二进制文件或缺失的提供方认证。
::: tip
如果找到了二进制文件但应用报告 "not logged in"，那么你的终端与应用之间的环境可能不同。请参阅[认证诊断日志](/zh/guide/troubleshooting#auth-diagnostic-log)来对比二者。
:::
## 4. 创建你的第一个团队
创建一个包含一个 lead 和一个或多个专家的团队。第一个团队请保持精简：一个 lead、一个实现智能体以及一个偏向审查的智能体，足以验证整个工作流。
有关推荐的结构与提示，请参阅[创建团队](/zh/guide/create-team)。
对于首次启动，建议采用如下这样的团队结构：
| 成员 | 职责 | 备注 |
| --- | --- | --- |
| Lead | 将目标拆分为任务并协调状态 | 部署在你拥有的最可靠的提供方上 |
| Builder | 实现有明确边界的任务 | 给出清晰的文件或功能边界 |
| Reviewer | 审查已完成的工作 | 让它专注于回归问题以及缺失的测试 |
避免一开始就配置五个或更多队友。更多的智能体会在你确认设置是否健康之前，增加并发、日志、提供方用量以及冲突风险。
## 5. 给 lead 一个具体的目标
像给一位工程负责人做简报那样写下目标：
```text
Improve the onboarding flow. Split the work into tasks, keep changes small, and ask for review before broad refactors.
```
好的首个提示应包含具体的范围、安全边界以及验证：
```text
Improve the docs quickstart. Keep edits inside landing/product-docs. Add practical examples, preserve existing VitePress syntax, and run `pnpm --dir landing docs:build` before marking tasks done.
```
在首次运行时，请避免诸如 "make the app better" 这样含糊的提示。lead 能够拆解大型目标，但更好的输入会产生更小的任务以及更整洁的审查。
::: tip
如果团队已启动但没有任务出现，请检查 lead 是否收到了你的提示。有关诊断，请参阅[智能体回复缺失](/zh/guide/troubleshooting#agent-replies-are-missing)。
:::
lead 会创建任务、分配工作并协调队友。你可以在 kanban 看板上观察进度，并随时通过评论或直接消息进行干预。
## 6. 审查结果
打开已完成或可供审查（review）的任务，检查 diff，并对单个改动进行接受、拒绝或评论。当你需要理解智能体为何做出某个选择时，可使用任务日志。
有关完整的审查工作流，请参阅[代码审查](/zh/guide/code-review)。
在批准第一个任务之前，请检查三件事：
1. 任务评论解释了改动了什么
2. 改动的文件与任务范围相符
3. 验证结果在任务评论或日志中可见
## 常见陷阱
| 症状 | 可能的原因 | 检查 |
| --- | --- | --- |
| 应用未检测到运行时 | 二进制文件不在 `PATH` 上，或应用与终端看到的环境不同 | 在终端中运行 `command -v <runtime>`，然后使用相同的终端环境来启动应用 |
| 团队启动卡住 | 付费/账户模型缺少提供方认证、模型字符串错误，或找不到运行时二进制文件 | 参阅[故障排查](/zh/guide/troubleshooting#team-does-not-launch) |
| OpenCode lane 卡在 `registered` | lane 证据尚未提交，或模型字符串不匹配 | 检查 `~/.claude/teams/<team>/.opencode-runtime/lanes/` |
| 智能体回复缺失 | 运行时投递重试、解析或任务归属问题 | 打开任务日志并检查投递账本 |
| 提供方返回 429 | 达到速率限制 | 等待重置，或切换模型/提供方 |
## 后续步骤
- [创建团队](/zh/guide/create-team) — 推荐的团队结构与简报写法
- [运行时设置](/zh/guide/runtime-setup) — 提供方认证与模型选择
- [代码审查](/zh/guide/code-review) — 审查、批准或请求修改
### 面向贡献者
如果你正在修改 Agent Teams 或这些文档，请从仓库根目录的规范项目文件开始：
- [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) — 工作约定与项目规则
- [AGENTS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENTS.md) — 架构与实现指引的导航层
- [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) — 硬性实现护栏
- [功能架构标准](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) — 新功能的结构
- [智能体团队调试操作手册](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) — 启动、引导（bootstrap）与队友诊断
要验证此文档站点是否正确构建：
```bash
pnpm --dir landing docs:build
```

179
landing/product-docs/zh/guide/runtime-setup.md Normal file
View file

@ -0,0 +1,179 @@
---
title: 运行时设置 – Agent Teams 文档
description: 配置 Claude Code、Codex 或 OpenCode 运行时。涵盖认证、提供方访问、多模型模式以及启动前检查。
lang: zh-Hans
---
# 运行时设置
Agent Teams 是一个协调层。实际的模型工作通过受支持的本地运行时与提供方运行。
::: tip 快速开始 - 选择你的第一个运行时
| 如果你 …… | 从这里开始 |
| --- | --- |
| 已经使用 Claude Code 或拥有 Anthropic 访问权限 | **Claude** - 熟悉的认证方式，设置最少 |
| 使用 Codex 或基于 OpenAI 的工作流 | **Codex** - 原生集成 |
| 想在不注册、不使用 API key 的情况下试用 Agent Teams | **OpenCode** - 使用内置的免费模型，无需认证 |
| 想要多模型路由或广泛的提供方覆盖 | **OpenCode** - 最灵活，一份配置对应多个后端 |
| 不确定哪个运行时适合自己 | **OpenCode** - 覆盖最多的提供方选项，并允许你之后切换 |
先从一个运行时和一名队友开始。在扩展到多模型之前，先确认一次启动可以正常工作。
:::
## 前置条件
在启动团队之前，请确保：
- 运行时二进制文件已安装并位于你的 `PATH` 中。
- 你的提供方账户对你打算使用的模型拥有有效访问权限，除非你从内置的免费 OpenCode 模型开始（无需认证）。
- 项目路径存在且可读。
- 当你手动测试认证时，应用与你的终端使用相同的 home/config 环境。
::: tip
先从单个队友和一个提供方开始。在添加多模型通道之前，先确认一次启动可以正常工作。
:::
快速终端检查：
```bash
command -v claude
command -v codex
command -v opencode
```
为你计划使用的运行时运行对应的命令。如果它没有任何输出，请先安装该运行时或修复 `PATH`，然后再启动团队。
## 受支持的路径
| 路径 | 默认 CLI | 典型提供方 | 适用场景 |
| --- | --- | --- | --- |
| Claude | `claude` | Anthropic | 你已经使用 Claude Code 或基于 Anthropic 的工作流 |
| Codex | `codex` | OpenAI | 你想要 Codex 原生的运行时集成 |
| OpenCode | `opencode` | OpenRouter 以及许多后端 | 你想要多模型路由和广泛的提供方覆盖 |
应用会检测受支持的运行时，并在可能时从 UI 中引导你完成设置。
Gemini 作为受支持的提供方路径提供，支持 Google ADC（`gcloud auth`）、Gemini CLI OAuth 以及 API key 认证。当检测到 Gemini 后端时，可在运行时设置 UI 中进行配置。
## 提供方访问
Agent Teams 自身没有付费层级。你可以从内置的免费 OpenCode 模型开始，无需认证 - 无需注册、API key 或信用卡。对于额外的模型，请使用你已经拥有的提供方访问权限：订阅、本地运行时认证或 API key，具体取决于你选择的路径。
- **Claude** 和 **Codex** 路径依赖各自的 CLI 认证工具。
- **OpenCode** 可以先运行内置的免费模型，无需认证。其他 OpenCode 模型可能需要在配置文件中提供特定于提供方的 API key（例如 `openrouter`、`openai`、`anthropic`）。
## 认证配置
### Claude Code
在终端中运行标准认证流程：
```bash
claude login
```
然后验证 CLI 可访问：
```bash
claude --version
```
如果打包后的应用报告 "not logged in"，而你的终端却能正常工作，请将应用所看到的 `$HOME` 与 `PATH` 和你用于登录的终端进行对比。[故障排查](/zh/guide/troubleshooting#auth-diagnostic-log)中描述的认证诊断日志是最佳的排查起点。
### Codex
通过 OpenAI 的 CLI 流程安装并认证：
```bash
codex login
```
然后验证运行时可访问：
```bash
codex --version
```
Codex 原生启动在可用时会使用 Codex 账户状态和模型目录数据。如果某个模型未出现在 UI 中，请先刷新提供方状态，再编辑团队 prompt。
### OpenCode
要使用内置的免费模型且无需认证，请在应用中选择它，并在不进行提供方注册的情况下启动。要使用其他 OpenCode 后端，请创建或编辑 `~/.opencode/config.json`（或你所在平台上的等价路径），并填入你想要的提供方 key：
```json
{
"providers": {
"openrouter": {
"apiKey": "sk-or-..."
}
}
}
```
请使用 OpenCode 期望的确切提供方名称。如果你设置了自定义的提供方名称，请仔细核对它与你在模型字符串中使用的提供方 ID（例如 `openrouter/moonshotai/kimi-k2.6` 会使用 `openrouter` 块）。
模型字符串示例：
| 模型字符串 | 必须存在的提供方块 |
| --- | --- |
| `openrouter/moonshotai/kimi-k2.6` | `openrouter` |
| `openai/gpt-5.4` | `openai` |
| `anthropic/claude-sonnet-4-6` | `anthropic` |
如果 OpenCode 启动了，但某个队友始终无法变为可送达状态，请在假定模型忽略了 prompt 之前先检查通道证据。参见[故障排查](/zh/guide/troubleshooting#opencode-registered-but-bootstrap-unconfirmed)。
### Gemini
Gemini 支持三种认证方法：
- **Google ADC** — 运行 `gcloud auth application-default login`，通过 Google 应用默认凭据进行认证。
- **Gemini CLI** — 如果已安装 Gemini CLI，运行 `gemini login`。
- **API key** — 在环境中设置 `GEMINI_API_KEY`，或通过应用的 Manage Providers UI 进行配置。
应用会自动检测可用的认证方法，并在后端可访问时，于运行时设置和团队创建 UI 中显示 Gemini 提供方。
## 多模型模式
多模型模式可以通过兼容 OpenCode 的配置将工作路由到许多提供方后端。当你需要提供方灵活性，或希望让队友使用不同的模型通道时，请使用它。
::: info 模型通道
每个队友都可以使用不同的 `providerId` + `model` 组合。在团队编辑 UI 中，展开成员选项即可覆盖全局默认值。
:::
一个保守的多模型设置：
| 角色 | 提供方 | 原因 |
| --- | --- | --- |
| Lead | Claude 或 Codex | 把协调工作放在你最信任的提供方上 |
| Builder | OpenCode | 为实现工作使用广泛的模型路由 |
| Reviewer | Claude、Codex 或第二个 OpenCode 模型 | 将审查判断与 builder 通道分开 |
避免在首次启动时混用许多不熟悉的提供方。在分配大量工作之前，先在每个通道上确认一个小任务。
## 启动前检查清单
在启动团队之前：
1. 已安装所选运行时
2. 运行时二进制文件位于环境 `PATH` 中
3. 已为所选后端配置提供方认证
4. 提供方对你指定的确切模型字符串拥有访问权限
5. 项目路径存在且可读
## 何时切换运行时路径
当当前路径因模型可用性、速率限制、提供方能力或团队角色需求而受阻时进行切换。保持相同的项目和团队工作流，但在切换后验证一个小任务。
::: warning 把设置错误当作设置问题来处理
如果认证失败、模型名称被拒绝，或找不到运行时二进制文件，请先修复设置。不要为了绕过运行时配置问题而修改团队 prompt 或项目代码。
:::
使用此决策表：
| 症状 | 更好的首要行动 |
| --- | --- |
| 找不到二进制文件 | 修复安装或 `PATH` |
| 终端中可以登录但应用中不行 | 检查 Electron 认证诊断日志和环境 |
| 模型被拒绝 | 在提供方运行时中验证确切的模型 id |
| 反复出现 429 | 降低并发数或切换模型/提供方 |
| OpenCode 通道卡住 | 检查通道清单和 `opencode-sessions.json` |

131
landing/product-docs/zh/guide/team-brief-examples.md Normal file
View file

@ -0,0 +1,131 @@
---
title: 团队简报示例 – Agent Teams 文档
description: 适用于小修复、文档工作、实现任务、审查以及高风险区域的实用团队简报模板。
lang: zh-Hans
---
# 团队简报示例
一份好的团队简报会给 lead 提供足够的结构，使其能够创建小任务，而无需在一开始就强行规定每一个实现细节。
使用如下结构：
```text
Outcome:
Scope:
Boundaries:
Coordination:
Verification:
Review:
```
## 最小化简报
适用于小型、低风险的工作。
```text
Outcome: Improve the quickstart so a new user can launch one team successfully.
Scope: Keep edits inside landing/product-docs.
Boundaries: Do not rewrite the whole docs structure.
Coordination: Create one or two tasks, keep comments on the task.
Verification: Run `pnpm --dir landing docs:build`.
Review: Summarize changed pages and any remaining gaps.
```
## 实现简报
当代码改动只涉及某一个功能区域时使用。
```text
Outcome: Add a focused improvement to task comment filtering.
Scope: Work inside the task/comment feature files unless a shared helper is clearly needed.
Boundaries: Do not change task storage format or review state semantics.
Coordination: Split parser, UI, and tests into separate tasks if they can be reviewed independently.
Verification: Run the focused unit tests first, then the feature typecheck if touched.
Review: Call out parsing edge cases and any behavior that affects existing task comments.
```
## 文档简报
适用于文档与指南类工作。
```text
Outcome: Draft practical workflow guides from the docs audit.
Scope: Add concise VitePress pages under landing/product-docs/guide.
Boundaries: Avoid moving existing navigation hubs owned by other tasks.
Coordination: Check related docs tasks before editing nav.
Verification: Run `pnpm --dir landing docs:build`.
Review: Include links added to sidebar and any pages intentionally left as drafts.
```
## 偏重审查的简报
适用于风险较高的区域，例如 IPC、提供方鉴权、持久化、Git 或任务生命周期逻辑。
```text
Outcome: Fix the launch failure without changing successful launch behavior.
Scope: Start from the newest launch-failure artifact and the affected runtime adapter.
Boundaries: Do not change provider prompts until setup and runtime evidence are inspected.
Coordination: Make one diagnostic task and one fix task if the cause is confirmed.
Verification: Run focused tests and one desktop smoke check when practical.
Review: Lead must inspect the diff before approval.
```
## 混合提供方简报
当不同队友运行不同的提供方/模型通道时使用。
```text
Outcome: Implement and review a small feature using separate builder and reviewer lanes.
Scope: Builder edits the feature. Reviewer inspects only the task diff and tests.
Boundaries: Do not switch model ids mid-task unless launch fails before work begins.
Coordination: Builder posts result comment first. Reviewer posts findings as task comments.
Verification: Builder runs focused tests. Reviewer checks failure output and changed scope.
Review: Lead approves only after reviewer comments are resolved.
```
## 简报中的 agent block
agent block 是仅供智能体阅读的隐藏文本，使用诸如 `<info_for_agent>...</info_for_agent>` 这样的标记包裹。应用会将它们从常规显示中剥离，但仍保留下来供智能体协调使用。当简报需要向智能体传达某些对人类读者而言属于干扰信息的内容时，可以使用它们。
示例——一份简报告诉 lead 如何拆分工作，同时又不向用户暴露协调指令：
```text
Outcome: Add a dark mode toggle to the application settings.
Scope: Settings UI, theme context, and CSS variables.
Boundaries: Do not change existing light theme values or provider auth screens.
<info_for_agent>
Split this into three tasks: (1) theme context and CSS vars, (2) toggle component and settings wiring, (3) dark mode preview in existing docs screenshots if practical.
</info_for_agent>
```
该 block 让面向人类的简报保持简洁，同时为 lead 提供结构化的任务拆分指引。
## 应避免的做法
| 薄弱的简报 | 更好的替代写法 |
| --- | --- |
| “Improve the app” | 指明工作流、文件以及成功检查 |
| “Fix all docs” | 选定一个指南组和一条构建命令 |
| “Use the best model” | 指明提供方/模型选择，或让应用的默认设置保持不变 |
| “Refactor as needed” | 说明允许改动哪些模块 |
| “Make it production ready” | 定义审查、测试以及上线检查 |
## 启动前
在启动团队之前，请检查以下几点：
1. 简报指明了一个具体的成果。
2. 风险边界是明确的。
3. lead 能够把工作拆分成可审查的任务。
4. 在已知的情况下包含了验证命令。
5. 敏感区域在批准前需要经过审查。
如果简报仍然过于宽泛，可以先启动一个 solo 或小型团队，并要求它先产出一份任务计划，而不是直接实现。
## 相关指南
- [创建团队](/zh/guide/create-team)
- [MCP 集成](/zh/guide/mcp-integration)
- [Git 与 worktree 策略](/zh/guide/git-worktree-strategy)

310
landing/product-docs/zh/guide/troubleshooting.md Normal file
View file

@ -0,0 +1,310 @@
---
title: 故障排查 – Agent Teams 文档
description: 借助本地诊断手段修复团队启动问题、缺失的智能体回复、速率限制、CLI 认证问题以及通道（lane）引导停滞。
lang: zh-Hans
---
# 故障排查
大多数团队问题都可归入以下四类之一：运行时设置、启动确认、任务解析以及提供方限制。
## 快速证据准备
对于任何团队生命周期问题，请先定义以下变量，并复用同一个 shell：
```bash
TEAM="<team-name>"
TEAM_DIR="$HOME/.claude/teams/$TEAM"
TASKS_DIR="$HOME/.claude/tasks/$TEAM"
```
然后在解读 UI 状态之前，先确认预期的文件确实存在：
```bash
test -d "$TEAM_DIR" && find "$TEAM_DIR" -maxdepth 2 -type f | sort | sed -n '1,80p'
test -d "$TASKS_DIR" && find "$TASKS_DIR" -maxdepth 1 -name '*.json' | sort | sed -n '1,40p'
```
::: warning 证据优先
不要仅凭一个卡住的徽章就去修改 prompt、提供方设置或清理进程。请先将 UI 与持久化文件、启动产物以及运行时证据相互印证。
:::
## 团队无法启动
按顺序逐项检查：
1. **运行时可用** —— 所选 CLI（`claude`、`codex`、`opencode`）已安装
2. **PATH 可达** —— 二进制文件在环境 `PATH` 中可用
3. **模型访问** —— 提供方有权访问所请求的模型字符串（尤其对于 OpenCode，精确的提供方/模型名称至关重要）
4. **项目路径** —— 项目目录存在且可读
5. **网络 / VPN** —— 某些提供方会在 VPN 处于激活状态时丢弃流量
::: tip
在终端中运行运行时二进制文件以验证 `PATH` 和认证。例如：`claude --version` 或 `opencode --version`。
:::
### OpenCode：已注册但引导未确认
如果 OpenCode 显示 `registered` 但引导未确认，请先检查产物，然后再更改团队 prompt。
贡献者/调试细节见[贡献者架构](/zh/reference/contributor-architecture)，其中链接到权威的智能体团队调试操作手册。
查看最新的启动失败产物：
```bash
LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
MANIFEST_PATH="$(jq -r '.manifestPath' "$LATEST_FAILURE")"
jq '.classification, .bootstrapTransportBreadcrumb, .memberSpawnStatuses' "$MANIFEST_PATH"
```
`latest.json` 指向最新打包的产物目录及其 `manifest.json`。该 manifest 包含：
- `classification` —— 此次启动被判定为失败的原因
- `bootstrapTransportBreadcrumb` —— 所使用的投递路径
- 成员 spawn 状态
- 已脱敏的日志和追踪
同时检查通道（lane）manifest：
```bash
jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime/lanes" -maxdepth 2 -name manifest.json -print -exec jq '.activeRunId, .entries' {} \; 2>/dev/null
```
::: tip 不要凭 UI 猜测
始终将 UI 诊断与持久化文件（`launch-state.json`、`bootstrap-journal.jsonl`）以及运行时专有证据相互印证。
:::
## 通用诊断
从磁盘上的持久化文件开始，而不是仅看 UI。
### 团队根目录
```bash
printf '%s\n' "$TEAM_DIR"
```
关键文件及其所能告诉你的信息：
- `launch-state.json` —— 成员启动/存活状态（`.teamLaunchState`、`.summary`、`.members`）
- `bootstrap-journal.jsonl` —— 来自 CLI/运行时的有序引导事件（`tail -80`）
- `bootstrap-state.json` —— 引导阶段摘要
- `config.json` —— 提供方、模型和项目配置
- `inboxes/*.json` 和 `sentMessages.json` —— 消息投递状态
```bash
jq '.teamLaunchState, .summary, .members' "$TEAM_DIR/launch-state.json"
tail -80 "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
```
### OpenCode 运行时证据
对于 OpenCode 队友，会话证据位于通道（lane）运行时存储中：
- `.opencode-runtime/lanes.json` —— 带状态的通道索引
- `.opencode-runtime/lanes/<lane>/manifest.json` —— `activeRunId` 和证据条目
- `.opencode-runtime/lanes/<lane>/opencode-sessions.json` —— 已提交的会话记录
预期的健康状态：通道状态为 `active`，manifest 带有 `activeRunId` 且至少有一个证据条目，成员的 `bootstrapConfirmed: true`。
```bash
jq '.lanes' "$TEAM_DIR/.opencode-runtime/lanes.json" 2>/dev/null
find "$TEAM_DIR/.opencode-runtime" -maxdepth 3 -type f | sort
```
### 启动失败产物
当一次启动被标记为失败时，检查 `latest.json`：
```bash
LATEST_FAILURE="$TEAM_DIR/launch-failure-artifacts/latest.json"
jq '.' "$LATEST_FAILURE"
jq '.' "$(jq -r '.manifestPath' "$LATEST_FAILURE")"
```
该 manifest 包含：
- `classification` —— 此次启动被判定为失败的原因
- `bootstrapTransportBreadcrumb` —— 所使用的投递路径
- 成员 spawn 状态以及已脱敏的日志/追踪
## 智能体回复缺失
打开任务日志和队友消息。回复缺失常常源于：
- **运行时投递重试** —— 智能体可能已经作答，但消息未投递到应用。请检查投递账本（ledger）。
- **解析或过滤** —— 智能体输出未包含预期的标记或任务引用。
- **任务归属** —— 工作确实在会话期间发生，但因为输出中缺少正确的任务 id 而未与任务关联。
::: warning 不要把沉默当成忽略
在日志确认之前，不要假定模型忽略了消息。
:::
使用持久化的消息状态来区分“未发送”和“已发送但未渲染”：
```bash
jq '.' "$TEAM_DIR/inboxes/user.json" 2>/dev/null
jq '.' "$TEAM_DIR/sentMessages.json" 2>/dev/null
```
检查 `from`、`to`、`messageId`、`relayOfMessageId` 和 `taskRefs`。对于 OpenCode 队友，在假定模型忽略了 prompt 之前，还要检查运行时投递证据。
## 任务未关联到变更
使用任务专属日志和代码审查链接。如果某个 diff 看起来是脱离关联的：
- 检查智能体输出中是否包含了任务 id 或任务引用。
- 验证智能体在进行编辑之前是否调用了 `task_add_comment`。
- 确保智能体调用了 `task_start`，以便看板知道工作已开始。
对于 OpenCode 队友，证明某个会话属于某个任务的权威证据位于 `opencode-sessions.json` 和通道（lane）manifest 条目中，而不仅仅是 UI 消息流。
### 任务日志分诊
当任务日志看起来不完整时，按任务 id 在任务 JSON、收件箱（inboxes）和引导事件中进行搜索：
```bash
TASK="<short-or-full-task-id>"
rg -n "$TASK" "$TASKS_DIR" "$TEAM_DIR/inboxes" "$TEAM_DIR/bootstrap-journal.jsonl" 2>/dev/null
```
仔细解读结果：
| 证据 | 它能证明什么 | 它不能证明什么 |
| --- | --- | --- |
| 消息已投递 | 应用写入或转发了一条 prompt | 智能体取得了进展 |
| 任务评论 | 智能体发布了看板可见的文本 | 该评论是有意义的进展 |
| 原生工具行 | 运行时在某个会话中做了工作 | 除非归属匹配，否则该工作属于此任务 |
| 变更账本条目 | 应用记录了文件变更 | 实现是正确的 |
对于 OpenCode，健康的任务日志通常包含原生运行时行，如 `read`、`bash`、`edit` 或 `write`，外加 Agent Teams MCP 行。如果你只看到 `agent-teams_*` 行，请在扩大日志匹配范围之前先确认任务归属和会话边界。
## 速率限制
如果提供方报告了一个已知的重置时间，Agent Teams 可以在冷却结束后提醒 lead 继续。如果重置时间未知，则等待或切换提供方/运行时路径。
| 提供方行为 | 建议操作 |
| --- | --- |
| 显示了已知的重置时间 | 等待冷却后继续 |
| 未显示重置时间 | 切换提供方或运行时路径 |
| 反复出现 429 | 降低并发或使用不同的模型通道（lane） |
## CLI 认证问题
### `claude login` 未持久化
如果 CLI 在某个终端中已认证，但应用却说未认证，请验证认证是否已保存到预期的配置路径，以及应用进程是否看到相同的 `$HOME`。
### OpenCode 提供方密钥被拒绝
- 仔细核对 `config.json` 中的提供方名称是否与模型字符串中的提供方前缀匹配
- 确保密钥未在提供方控制台中过期或被吊销
### 认证诊断日志
每次调用 `CliInstallerService.getStatus()` 都会向 Electron 日志文件夹中的 `claude-cli-auth-diag.ndjson` 追加一行（在 macOS 上通常为 `~/Library/Logs/<product-name>/`）。如果该文件超过 **512 KiB**，则会在下一次写入之前被截断为空。
如果你在打包后的应用中看到 “Not logged in” 或认证错误，请检查此文件。
## 通道（lane）引导卡住
对于 OpenCode 次级通道（secondary lane）：
- 缺少 `inboxes/<member>.json` 并不自动意味着这是 bug。OpenCode 通道在启动之前不必先由主收件箱创建。
- 如果 UI 显示团队仍在启动，而主成员已经可用，那么“所有队友已加入”正在等待次级通道。
- 如果 `Prepared communication channels for X/Y members` 卡住，请验证 `Y` 是否错误地把次级 OpenCode 成员计算在内。
### 通道（lane）manifest 条目为空
如果桥接（bridge）声称引导成功，但 `manifest.json` 显示 `entries: []`，问题在于**证据提交**，而不是模型行为。在 `opencode-sessions.json` 及其 manifest 条目存在之前，不得将该成员视为可投递。
## 常见成员状态
| 状态 | 含义 |
| --- | --- |
| `confirmed_alive` + `bootstrapConfirmed` | 健康且就绪 |
| `registered` / `runtime_pending_bootstrap` | 进程或通道存在，但引导证据尚未提交 |
| `failed_to_start` + `runtime_process` | 进程存在，但启动门控失败。请检查诊断 |
| `failed_to_start` + `stale_metadata` | 已保存的 pid/session 已过期或已失效 |
::: warning
`member_briefing` 本身并不是运行时证据。对于 OpenCode，权威证据是已提交的运行时证据，例如 `opencode-sessions.json` 和 manifest 条目。
:::
## 运行时调试模式
对于本地调试，你可以强制队友在 tmux 窗格中运行：
```bash
# Launch from a terminal
CLAUDE_TEAM_TEAMMATE_MODE=tmux pnpm dev
# Or add to custom CLI args
--teammate-mode tmux
```
用它来检查交互式 CLI 行为。不要将其视为与进程后端完全等价。
## 冒烟检查
正常验证请使用桌面 Electron 应用。浏览器/Web 开发模式不包含完整的桌面运行时、IPC、提供方认证、终端或团队生命周期行为。
### 仅文档的变更
从仓库根目录：
```bash
pnpm --dir landing docs:build
git diff --check -- landing/product-docs
```
### 团队生命周期变更
先收窄范围，再逐步扩展：
```bash
pnpm test -- test/main/services/team/TeamProvisioningService.test.ts
pnpm test -- test/main/services/team/TeamAgentLaunchMatrix.safe-e2e.test.ts
pnpm typecheck
git diff --check
```
### 实时团队冒烟测试
使用一个小型团队和一个受 Git 跟踪的一次性项目：
1. 用 `pnpm dev` 启动桌面应用。
2. 创建一个 lead 加一个 builder。
3. 请求一个带有明确验证命令的微小变更。
4. 确认任务从 `pending` -> `in_progress` -> `completed` 移动。
5. 打开任务日志，验证工具行、任务评论和文件变更相互对应。
6. 清理时只停止冒烟测试自有的团队/进程。
::: warning 仅做收窄清理
在清理一次冒烟运行时，不要杀掉所有 OpenCode 主机、无关的 tmux 窗格或用户团队。
:::
## 安全清理
清理过期进程时：
1. 识别 pid 并确认它属于当前团队 / 通道。
2. 只停止明确属于冒烟测试或你正在调试的那次启动的进程。
3. **不要**为了图省事而杀掉所有 OpenCode 或共享主机进程。
## 何时收集证据
在寻求帮助之前，收集：
- 任务 id（短的或完整的）
- 团队名称
- 运行时路径（`claude`、`codex` 或 `opencode`）
- 启动日志摘录（来自 `latest.json` 或 `bootstrap-journal.jsonl`）
- 提供方 / 模型字符串
- 问题发生的确切时间窗口
这些数据通常足以调试启动和任务生命周期问题。
::: tip
如果问题仍然存在，打开团队位于 `~/.claude/teams/<teamName>/` 下的持久化文件，并在更改代码之前将 UI 诊断与实时进程状态相互印证。
:::

81
landing/product-docs/zh/index.md Normal file
View file

@ -0,0 +1,81 @@
---
title: Agent Teams 文档 – 从本地桌面应用运行 AI 智能体团队
description: Agent Teams 的文档，这是一款用于编排 AI 智能体的免费桌面应用。创建团队、在看板上观察工作进展、审查代码变更，并协调 Claude、Codex、OpenCode 与多模型工作流。
lang: zh-Hans
layout: home
hero:
name: Agent Teams 文档
text: 从本地桌面应用运行 AI 智能体团队
tagline: 创建团队、观察工作在看板上流转、审查代码变更，并协调 Claude、Codex、OpenCode 与多模型工作流，同时不放弃对本地的掌控。
actions:
- theme: brand
text: 快速开始
link: /zh/guide/quickstart
- theme: alt
text: 安装
link: /zh/guide/installation
- theme: alt
text: 概念
link: /zh/reference/concepts
features:
- icon: "01"
title: 团队优先的工作流
details: 定义角色，启动一名 lead，让智能体拆分、认领并协调任务。
link: /zh/guide/create-team
linkText: 创建团队
- icon: "02"
title: 实时看板
details: 在智能体工作时，观察任务在 todo、in progress、review、done 和 approved 之间流转。
link: /zh/guide/agent-workflow
linkText: 了解工作流
- icon: "03"
title: 内置代码审查
details: 检查以任务为范围的 diff，接受或拒绝代码块（hunk），并在智能体需要指引时留下评论。
link: /zh/guide/code-review
linkText: 审查变更
- icon: "04"
title: 运行时感知的设置
details: 通过你已有的访问权限，使用 Claude、Codex、OpenCode 或多模型提供方。
link: /zh/guide/runtime-setup
linkText: 配置运行时
- icon: "05"
title: 本地优先的掌控
details: 该桌面应用读取本地项目与运行时状态。除非选定的提供方接收到提示词上下文，否则你的代码始终留在你的机器上。
link: /zh/reference/privacy-local-data
linkText: 隐私模型
- icon: "06"
title: 可调试的团队
details: 当启动或任务卡住时，可追踪任务日志、运行时输出、队友消息以及运行中的进程。
link: /zh/guide/troubleshooting
linkText: 故障排查
---
<InstallBlock label="复制" copied-label="已复制" />
## 从这里开始
Agent Teams 是一款用于编排 AI 智能体团队的免费桌面应用。你不只是在向单个智能体发送孤立的提示词：你创建一个团队、分配角色，并观察智能体通过任务看板协调工作。
<DocsCardGrid />
## 启动后的下一步
创建第一个团队后，浏览这些指南以进一步深入：
- **运行时设置** - 配置 Claude、Codex、OpenCode 或多模型提供方：[配置运行时](/zh/guide/runtime-setup)
- **智能体工作流** - 了解智能体如何通过任务看板协调工作：[了解工作流](/zh/guide/agent-workflow)
- **团队简报示例** - 从真实世界的简报中学习提示词模式：[查看示例](/zh/guide/team-brief-examples)
- **代码审查** - 检查 diff，接受或拒绝变更：[审查变更](/zh/guide/code-review)
- **故障排查** - 诊断卡住的启动、缺失的队友以及任务失败：[故障排查](/zh/guide/troubleshooting)
- **Git 与 worktree 策略** - 当多名队友并行编辑同一仓库时，使用 worktree 隔离：[了解 worktree](/zh/guide/git-worktree-strategy)
- **发布说明** - 查看每个版本的新内容：[查看发布版本](/zh/reference/release-notes)
## 参考
当你需要准确的术语、提供方行为、贡献者架构或隐私边界时，请使用参考页面。
<DocsCardGrid type="reference" />
## 产品预览
<ZoomImage src="/screenshots/1.jpg" alt="Agent Teams 看板" caption="任务状态、队友活动与审查工作流，全部集中在一个工作区中可见。" />

85
landing/product-docs/zh/reference/concepts.md Normal file
View file

@ -0,0 +1,85 @@
---
title: 概念 – Agent Teams 文档
description: Agent Teams 的核心术语——团队、lead、teammate、任务、看板、收件箱、运行时与审查。
lang: zh-Hans
---
# 概念
本页定义了贯穿 Agent Teams 的核心术语。请将其作为应用、任务看板、消息与审查流程的共享词汇表。
## 团队
团队是附属于某一项目路径的一组具名智能体。它包含一个 lead、可选的 teammate、运行时/提供方设置、prompt、收件箱、任务以及本地启动状态。
## Lead {#lead}
lead 是团队的协调者。它将用户目标转化为任务，分配或重新调度 teammate，跟踪阻塞项，请求审查，并推动工作在看板上不断流转。
[Teammate →](#teammate)
lead 消息使用与 teammate 消息不同的投递路径：应用会将 lead 收件箱中的条目转发到 lead 运行时，而 teammate 则在两轮之间读取它们各自的收件箱文件。
## Teammate {#teammate}
teammate 是团队中的非 lead 智能体。teammate 通常承担聚焦的角色，例如构建者、审查者、研究者或测试者。teammate 可以接收直接消息、任务分配、任务评论和审查请求。
[Lead ↑](#lead)
## 任务
任务是持久的工作单元。它具有 id、状态、负责人、描述、评论、日志、附件、任务引用以及可审查的变更。
常见的任务状态有 `todo`、`in_progress`、`done`、`review` 和 `approved`。在内部，任务文件存储工作状态，而审查与审批的位置也可以使用看板叠加状态。
## 看板
看板是团队工作的看板视图。它让你能够按状态浏览任务、打开任务详情、检查日志、审查 diff、审批已完成的工作，或请求更改。
## 收件箱
收件箱是团队参与者的本地消息文件。Agent Teams 将收件箱用于用户消息、lead 消息、teammate 消息、运行时投递元数据、跨团队消息以及部分系统通知。
消息是持久的本地记录。投递仍然取决于所选运行时处于活动状态并能够处理其下一轮。
## Agent Block
agent block 是用 `<info_for_agent>...</info_for_agent>` 包裹的隐藏的、仅供智能体使用的指令文本。UI 会在面向人类的常规显示中剥离这些块，但智能体与运行时投递可以将它们用于协调细节。
当前的规范标记是 `info_for_agent`。较旧的文档可能使用带有 `info_for_agent` 标记的围栏代码块，或 XML 风格的 `<agent_block>` 标签——这些都是遗留模式，遇到时应迁移为 `info_for_agent`。（原始标签名为 `agent-block`；下划线形式 `<agent_block>` 在 VitePress 源文件中使用，以避免 HTML 解析。）
## 上下文阶段
上下文阶段是会话上下文时间线中的一个片段。压缩会开启一个新阶段，因此可以分析重置前后的 token 与上下文用量。
上下文跟踪会区分不同类别，例如项目指令、提及的文件、工具输出、思考文本、团队协调与用户消息。这些数字是诊断信息，而非提供方的计费账单。
## 运行时
运行时是运行某一智能体轮次的本地执行路径。受支持的运行时路径包括 Claude Code、Codex 和 OpenCode。
运行时掌控模型执行行为、认证细节、工具执行语义、速率限制、模型可用性，以及部分转录/日志格式。
## 提供方
提供方是运行时背后的模型访问路径。当前的提供方 id 包括 Anthropic、Codex、Gemini 和 OpenCode。OpenCode 可以通过其自身配置路由到许多模型提供方。
Agent Teams 编排任务与消息，但它不会取代提供方的认证或提供方的策略。
## Solo 模式
Solo 模式运行一个单成员团队。它适用于快速工作、降低协调开销，以及在扩展为完整团队之前验证某个 prompt。
## 跨团队通信
智能体可以在团队内部以及跨团队发送消息。当不同团队负责相关工作并需要在不把所有内容合并成一个庞大团队的前提下进行协调时，可以使用这一功能。
## 自主级别
自主级别控制智能体在询问之前能够做多少事情。更高的自主级别更快；更低的自主级别对于敏感的代码路径、持久化、提供方认证、Git 操作与发布更为安全。
## 审查
审查是以任务为范围的验收流程。任务可以进入 review，接收评论或请求的更改，然后在结果被接受时进入 approved。
审查与本地 diff 及任务历史绑定，因此当任务保持聚焦、且智能体提及它们正在处理的任务时，效果最佳。

55
landing/product-docs/zh/reference/contributor-architecture.md Normal file
View file

@ -0,0 +1,55 @@
---
title: 贡献者架构 – Agent Teams 文档
description: 面向贡献者的指南，介绍功能布局、运行时/提供方边界、硬性护栏以及权威架构文档。
lang: zh-Hans
---
# 贡献者架构
本页是面向贡献者的导览图。它指向权威的仓库指引，而不是重述每一条实现规则。
## 权威来源
在修改应用时，请将以下文件作为唯一可信来源：
| 需求 | 权威来源 |
| --- | --- |
| 仓库概览与命令 | [README.md](https://github.com/777genius/agent-teams-ai/blob/main/README.md) |
| 本地协作约定 | [CLAUDE.md](https://github.com/777genius/agent-teams-ai/blob/main/CLAUDE.md) |
| 硬性护栏 | [AGENT_CRITICAL_GUARDRAILS.md](https://github.com/777genius/agent-teams-ai/blob/main/AGENT_CRITICAL_GUARDRAILS.md) |
| 中型与大型功能布局 | [docs/FEATURE_ARCHITECTURE_STANDARD.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/FEATURE_ARCHITECTURE_STANDARD.md) |
| 智能体团队启动调试 | [docs/team-management/debugging-agent-teams.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/team-management/debugging-agent-teams.md) |
## 功能布局
中型与大型功能应位于 `src/features/<feature-name>/` 下，并遵循功能架构标准。将功能内部细节隐藏在公共入口点之后，避免跨越功能边界的深层导入。
对于新的工作，请以现有的 `src/features/recent-projects` 切片作为本地参考实现来起步。当创建功能切片带来的结构开销大于其价值时，小修小补可以保留在现有代码路径附近。
## 运行时与提供方边界
Agent Teams 负责编排：团队、任务、消息、启动状态、审查界面、诊断以及本地持久化。
所选的运行时/提供方路径负责模型执行、认证、模型可用性、速率限制、工具语义以及运行时特定的会话记录证据。不要让 prompt 或 UI 状态去弥补缺失的认证、缺失的二进制文件、被拒绝的 model id 或提供方故障。关于面向用户的设置细节，请参阅 [提供方与运行时](/zh/reference/providers-runtimes)。
## 智能体团队调试
对于启动挂起、OpenCode `registered` / bootstrap 未确认状态、缺失的队友回复或可疑的任务日志，请从专门的调试运行手册开始。检查 `~/.claude/teams/<team>/launch-failure-artifacts/latest.json` 下最新的启动失败产物，然后将 UI 状态与持久化文件以及运行时特定的证据相互关联。
调试时避免大范围清理。仅停止你能确认属于该问题的进程、lane、团队或冒烟运行。
## 贡献者约定
- 在常规开发中，使用 `pnpm dev` 启动桌面 Electron 应用。
- 不要将浏览器开发模式当作桌面运行时、IPC、终端、提供方认证或团队生命周期行为的替代品。
- 将 Electron 的 main、preload、renderer、shared 与功能各自的职责分开。
- 使用 `wrapAgentBlock(text)` 处理仅供智能体使用的块，而不是手动拼接标记。
- 优先进行有针对性的验证。除非任务明确与格式化相关，否则避免大范围的 `lint:fix` 或格式变动。
- 将解析、任务生命周期、提供方/运行时检测、持久化、IPC、Git 以及审查流程视为高风险区域，它们需要有针对性的测试或清晰的验证路径。
## 相关页面
- [运行时设置](/zh/guide/runtime-setup)
- [故障排查](/zh/guide/troubleshooting)
- [代码审查](/zh/guide/code-review)
- [隐私与本地数据](/zh/reference/privacy-local-data)

95
landing/product-docs/zh/reference/faq.md Normal file
View file

@ -0,0 +1,95 @@
---
title: 常见问题 – Agent Teams 文档
description: 关于 Agent Teams 的常见问题——价格、模型访问、运行时、隐私、审查与故障排查。
lang: zh-Hans
---
# 常见问题
## Agent Teams 是免费的吗？
是的。该应用免费且开源。根据你使用的内容，提供方或运行时访问仍可能产生费用。
## Agent Teams 是否包含模型访问？
不包含。Agent Teams 是本地的编排与 UI 层。模型访问来自所选的运行时/提供方路径，例如 Claude Code、Codex 或 OpenCode。
## 支持哪些运行时？
支持的运行时路径为 Claude Code、Codex 和 OpenCode。当运行时暴露相应信息时，该应用还会跟踪提供方 id，例如 Anthropic、Codex、Gemini 和 OpenCode。
## 我需要先安装 Claude Code 或 Codex 吗？
并非总是如此。该应用会从 UI 引导你完成运行时检测与设置。某些路径仍需要外部运行时认证。
OpenCode 的设置与 Claude Code 和 Codex 的设置是分开的。如果某次启动失败，请在修改团队 prompt 之前先检查运行时状态和提供方认证。
## 如何检查某个运行时是否就绪？
先在终端运行该运行时命令：
```bash
claude --version
codex --version
opencode --version
```
然后确认你所选路径的提供方认证。如果该命令或认证检查在 Agent Teams 之外失败，请先修复设置，再启动团队。
## 它会把我的代码上传到 Agent Teams 服务器吗？
不会。Agent Teams 不是云端代码同步服务。根据你所选的运行时，由提供方支持的模型调用可能会接收到 prompt 上下文。
## 团队文件存储在哪里？
团队协调数据本地存储在 `~/.claude/teams/<team>/`（macOS/Linux）或 `%APPDATA%\Claude\teams\<team>\`（Windows）下，任务文件存储在 `~/.claude/tasks/<team>/` 或 `%APPDATA%\Claude\tasks\<team>\` 下，项目会话数据在可用时存储在 `~/.claude/projects/<encoded-project>/` 下。
## 哪些内容会离开我的机器？
当某个智能体使用由提供方支持的模型时，prompt 上下文、所选文件内容、工具结果、命令输出、任务文本、评论以及附件可能会通过运行时/提供方路径离开你的机器。具体行为取决于运行时和提供方。
## 智能体之间可以互相沟通吗？
可以。智能体可以给队友发消息、在任务上评论、跨团队协调，并使用任务引用让对话与工作保持关联。
## 第一条团队 prompt 里应该写什么？
给 lead 一个具体的产出目标、文件或功能边界、风险限制以及验证预期。例如：
```text
Improve the docs quickstart. Keep edits inside landing/product-docs, add practical examples, and run `pnpm --dir landing docs:build` before marking work done.
```
## 我可以在接受代码之前先审查它吗？
可以。审查流程围绕任务范围的 diff 和代码块（hunk）级别的决策构建。
## 什么是 Agent Block？
Agent Block 是隐藏的、仅供智能体使用的文本，用诸如 `<info_for_agent>...</info_for_agent>` 这样的标记包裹。该应用会在面向用户的常规显示中将其剥离，但会保留它以供智能体协调使用。
## 什么是 solo 模式？
solo 模式是单智能体团队。它适用于较小的任务以及较低的协调开销。
## 我应该使用 worktree 隔离吗？
当多个 OpenCode 队友可能并行编辑同一个 Git 项目时，请使用它。它能减少文件冲突，但需要一个受 Git 跟踪的项目，并且目前仅适用于 OpenCode 成员。
## 不同的队友可以使用不同的提供方吗？
可以，当所选的运行时路径支持时，提供方/模型设置可以按团队成员分别携带。OpenCode 是实现广泛多提供方路由的主要路径。
## 为什么某个任务会显示 review 或 approved，而与 done 分开？
工作状态和审查状态相关但并不相同。一个任务可能从智能体的角度看已经 done，然后在 kanban UI 中经过 review 和审批流程。
## 启动卡住时我应该怎么做？
打开故障排查，收集启动诊断信息，检查 `~/.claude/teams/<team>/`，并在修改 prompt 之前验证运行时/提供方认证。
对于 OpenCode，请在认定某个队友已在线却忽略消息之前，先检查 lane/会话证据。
## 为什么不同运行时的日志各不相同？
Claude Code、Codex 和 OpenCode 暴露的转录格式和运行时证据各不相同。Agent Teams 会尽可能地将其规范化，但日志的完整性和归属可能因运行时而异。

82
landing/product-docs/zh/reference/privacy-local-data.md Normal file
View file

@ -0,0 +1,82 @@
---
title: 隐私与本地数据 – Agent Teams 文档
description: Agent Teams 在本地存储哪些数据、哪些数据可能通过提供方支持的模型调用离开你的机器，以及实用的隐私指南。
lang: zh-Hans
---
# 隐私与本地数据
Agent Teams 以本地优先为原则，但你所选择的运行时/提供方路径仍然很重要。本页介绍桌面应用在本地存储哪些数据，以及当智能体调用提供方支持的模型时，哪些数据可能离开你的机器。
## 哪些数据留在本地
桌面应用在你的机器上运行，并读取本地的项目/运行时数据来驱动 UI。典型的本地数据包括：
- 项目文件
- 团队配置与成员元数据
- 任务元数据、任务评论与任务引用
- 收件箱消息
- 运行时/会话日志
- 启动状态与引导诊断信息
- 审查状态
- 本地应用设置
重要的本地位置包括：
| 平台 | 位置 | 用途 |
| --- | --- | --- |
| macOS/Linux | `~/.claude/teams/<team>/` | 团队配置、成员元数据、收件箱、启动状态、引导证据、运行时诊断信息、已发送消息记录、kanban 状态，以及与审查相关的团队文件。 |
| Windows | `%APPDATA%\Claude\teams\<team>\` | 同上——团队配置、成员元数据、收件箱、启动状态与诊断信息。 |
| macOS/Linux | `~/.claude/tasks/<team>/` | 团队看板的持久化任务 JSON 文件。 |
| Windows | `%APPDATA%\Claude\tasks\<team>\` | 同上——持久化任务 JSON 文件。 |
| macOS/Linux | `~/.claude/projects/<encoded-project>/` | Claude/Codex 风格的项目会话文件，用于会话历史、上下文分析以及基于转录的 UI。 |
| Windows | `%APPDATA%\Claude\projects\<encoded-project>\` | 同上——项目会话文件。 |
具体文件可能因运行时和应用版本而异。在调试启动问题时，最新的证据通常位于相应的 `~/.claude/teams/<team>/`（或 `%APPDATA%\Claude\teams\<team>\`）文件夹下。
## 哪些数据可能离开你的机器
Agent Teams 本身并不是面向你代码仓库的云端代码同步服务。它无需将你的整个项目上传到 Agent Teams 服务器，即可显示看板、收件箱、日志或审查 UI。
然而，当一个智能体请求提供方支持的模型进行工作时，提示词上下文、所选文件内容、任务文本、评论、工具结果、命令输出以及其他运行时提供的上下文，可能会通过所选的运行时/提供方路径被发送出去。发送的内容取决于运行时、模型、工具调用、提示词以及提供方配置。
提供方身份认证、提供方侧的数据保留、训练、日志记录、区域处理以及计费，均受你所选择的提供方/运行时的政策约束。对于敏感项目，请查阅这些政策。
常见示例：
| 操作 | 可能通过运行时/提供方发送的数据 |
| --- | --- |
| 让智能体编辑某个文件 | 任务提示词、相关文件内容、工具结果与命令输出 |
| 附加一张截图 | 附件内容以及周围的任务/评论文本 |
| 请求代码审查 | diff 上下文、所选文件、评论与验证日志 |
| 调试失败的命令 | 错误输出、堆栈跟踪与引用的源码片段 |
## 应用不保证哪些事项
- 它无法保证提供方支持的模型调用永远不会接收到私有代码。
- 它无法覆盖提供方的数据保留或计费政策。
- 它无法让远程提供方表现得像一个完全本地的模型。
- 它无法保护那些智能体被指示粘贴到提示词、任务评论、文件或命令中的密钥。
- 它无法让每个运行时都暴露相同的转录或审计细节。
## 实用指南
- 不要将密钥附加到任务、评论或私信中。
- 对于敏感项目，请查阅提供方政策。
- 对于有风险的代码仓库，使用较低的自主级别。
- 处理私有代码时，保持任务范围狭窄。
- 调试时优先使用本地证据和日志。
- 在让智能体处理机密材料之前，检查生成的提示词、任务描述与附加文件。
- 使用符合你隐私要求的提供方/模型路径。
在敏感的代码仓库上使用 Agent Teams 之前：
1. 从工作区和任务附件中移除密钥
2. 选择你被允许使用的运行时/提供方路径
3. 从低自主级别和小任务开始
4. 在扩大范围之前，审查任务提示词与生成的评论
5. 将日志保留在本地，除非你有意为获得支持而分享它们
## 开源模式
应用本身是开源且免费的。你可以在代码仓库中查看本地编排、任务跟踪、收件箱、运行时诊断以及审查流程的工作方式。

115
landing/product-docs/zh/reference/providers-runtimes.md Normal file
View file

@ -0,0 +1,115 @@
---
title: 提供方与运行时 – Agent Teams 文档
description: 受支持的运行时路径（Claude Code、Codex、OpenCode）、提供方 ID、模型命名、多提供方策略以及能力检查。
lang: zh-Hans
---
# 提供方与运行时
Agent Teams 将编排与模型访问分离开来。应用负责管理团队、任务、消息、启动状态和审查 UI；所选的运行时/提供方路径则执行实际的模型工作。
## 应用提供什么
Agent Teams 提供：
- 团队与任务编排
- 看板 UI
- 队友消息传递
- 任务日志
- 审查 UI
- 本地项目集成
- 运行时检测与能力检查
- 本地日志与诊断
## 运行时提供什么
运行时提供：
- 模型执行
- 提供方身份验证
- 工具执行行为
- 特定于模型的速率限制与能力
- 特定于运行时的转录与投递凭证
## 受支持的运行时路径
| 运行时路径 | 提供方/模型路径 | 最佳适用场景 | 备注 |
| --- | --- | --- | --- |
| Claude Code | Anthropic / Claude 模型 | Claude Code 用户以及由 Anthropic 支持的工作流 | Claude 团队默认的本地优先路径。需要本地具备运行时及账户访问权限。 |
| Codex | Codex / 由 OpenAI 支持的模型 | Codex 原生工作流 | 在可用时使用 Codex 运行时集成以及 Codex 认证/账户状态。部分诊断与 Claude 转录不同。 |
| OpenCode | OpenCode 托管的模型路由 | 多提供方团队以及广泛的模型覆盖 | OpenCode 可以路由到许多模型提供方。Agent Teams 将 OpenCode 通道视为特定于运行时的凭证，并在通道身份不明确时避免臆测。 |
Gemini 作为一条受支持的提供方路径提供，支持 Google ADC（gcloud auth）、Gemini CLI OAuth 以及 API 密钥身份验证。当运行时报告其可用时，它会在团队创建和运行时设置 UI 中与其他提供方一同出现。
## 提供方 ID
应用目前在团队/运行时配置中识别以下提供方 ID：
| 提供方 ID | 显示意图 |
| --- | --- |
| `anthropic` | Anthropic / Claude Code 路径 |
| `codex` | Codex 路径 |
| `gemini` | Gemini 提供方路径（Google ADC、Gemini CLI 或 API 密钥） |
| `opencode` | OpenCode 路径，包括 OpenCode 托管的提供方路由 |
不要将此表解读为对每台机器上每个模型的每个提供方都已认证、已安装或可用的保证。对于某次具体启动而言，运行时状态和能力检查才是事实来源。
## 模型 ID
模型 ID 会被传递给所选的运行时。Agent Teams 不会将某个提供方的模型目录改写为统一的命名方案。
示例：
| 提供方路径 | 示例模型 ID | 备注 |
| --- | --- | --- |
| Claude Code | `opus`、`sonnet` 或完整的 Claude 模型 ID | 可用性取决于 Claude Code 与账户访问权限 |
| Codex | `gpt-5.4`、`gpt-5.3-codex` | 可用性来自 Codex 账户/运行时状态 |
| OpenCode | `openrouter/moonshotai/kimi-k2.6` | 前缀必须与某个 OpenCode 提供方配置相匹配 |
如果某个模型名称被拒绝，请先直接在运行时/提供方中进行验证。更改团队简报并不能让一个不可用的模型启动。
## 多提供方策略
Agent Teams 让编排具备提供方感知能力，但并不被提供方所拥有：
- 团队、任务、收件箱、评论、审查状态和启动诊断都保留在本地的 Agent Teams 存储中
- 每位成员都可以通过团队启动元数据携带提供方/模型设置
- 模型可用性、身份验证、速率限制和工具行为仍由运行时/提供方负责
- 当你希望让一个团队使用多条提供方/模型通道时，OpenCode 是覆盖面最广的路由路径
关于面向贡献者的边界以及规范的实现指南，请参阅[贡献者架构](/zh/reference/contributor-architecture)。
推荐模式：
| 模式 | 何时有帮助 | 风险 |
| --- | --- | --- |
| 所有成员使用同一个提供方 | 首次启动、敏感仓库、最简单的调试 | 共享的速率限制可能让整个团队停摆 |
| 强 lead + 更廉价的 builder | 在降低实现成本的同时保持规划/审查的可靠性 | builder 的产出可能需要更严格的审查 |
| 分别使用 builder 和 reviewer 模型 | 捕捉特定于模型的盲点 | 需要更多设置，并需检查更多归属信息 |
## 提供方成本
Agent Teams 免费且开源。你可以从内置的免费模型开始，无需身份验证——无需注册、API 密钥或信用卡。付费或基于账户的提供方使用由你所选择的运行时/提供方管理：订阅额度、API 密钥、账户认证、速率限制和提供方政策都仍然外置于应用之外。
## 能力检查
在设置过程中，应用可能会执行访问与能力检查。这有助于在团队启动于预配中途失败之前，检测出缺失的运行时认证。
能力检查可能会报告：某个提供方存在但未认证、模型列表不可用、缺少某条运行时路径，或某项特定的扩展能力不受支持。请将这些结果视为设置诊断，而非任务失败。
典型的设置修复：
| 检查结果 | 应采取的措施 |
| --- | --- |
| 缺少运行时 | 安装 CLI 或修复 `PATH` |
| 提供方未认证 | 运行提供方登录流程或添加所需的 API 密钥 |
| 模型不可用 | 选择该运行时模型列表中可见的模型 |
| 能力不受支持 | 为该队友改用另一条运行时路径 |
## 应预期的限制
- 受支持运行时并不意味着 Claude Code、Codex 和 OpenCode 之间具有同等的功能对等性。
- 日志和转录的覆盖范围因运行时而异。
- 在应用能够安全归属运行时日志之前，OpenCode 通道需要稳定的通道/会话凭证。
- 提供方的模型名称与可用性可能在应用之外发生变化。
- 团队提示词无法修复缺失的认证、缺失的 PATH 条目、提供方中断或耗尽的速率限制。

42
landing/product-docs/zh/reference/release-notes.md Normal file
View file

@ -0,0 +1,42 @@
---
title: 发布说明 – Agent Teams 文档
description: Agent Teams 的发布说明与变更日志。提供指向权威 RELEASE.md 与 CHANGELOG.md 的链接以获取完整细节。
lang: zh-Hans
---
# 发布说明
当前发布版本：**v1.2.0**（2026-03-31）。`main` 分支上仍在持续积极开发，包含尚未发布的成员工作同步、OpenCode 投递加固以及 CI 稳定性方面的改动。
## 发布机制
Agent Teams 遵循[语义化版本](https://semver.org/)。推送到仓库的标签会触发一个自动化的[发布工作流](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md)，该工作流会为 macOS、Windows 和 Linux 构建签名包，然后将它们发布到 GitHub Releases。
## 近期发布
### v1.2.0 — Agent Graph、按团队工具审批、交互式 AskUserQuestion
Agent Graph 提供力导向可视化与看板任务布局，按团队的工具审批控制并附带可读的权限提示，任务评论通知，以及交互式 AskUserQuestion 按钮。权限系统全面改造，加入 Write/Edit/NotebookEdit 预置以及 MCP 工具目录集成。参见[完整变更日志](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#120---2026-03-31)。
### v1.1.0 — React 19 + Electron 40、用户发起的任务启动
迁移到 React 19 + Electron 40，从看板发起的用户启动任务，认证故障排查指南，针对 R/Ruby/PHP/SQL 的语法高亮，会话记录搜索速度提升 3 倍，WSL/Windows 路径修复，以及 XSS 漏洞修复。参见[完整变更日志](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#110---2026-03-25)。
### v1.0.0 — 首个公开发布
首个稳定构建：打包应用中的 CLI/认证可靠性，IPC 加固，带签名 macOS 构建的跨平台打包，开源治理文档（LICENSE、CONTRIBUTING、CODE_OF_CONDUCT、SECURITY）。参见[完整变更日志](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md#100---2026-03-23)。
## 权威来源
| 文档 | 说明 |
| --- | --- |
| [RELEASE.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/RELEASE.md) | 发布流程、版本管理指南、构件命名、自动更新设置以及发布说明模板。 |
| [CHANGELOG.md](https://github.com/777genius/agent-teams-ai/blob/main/docs/CHANGELOG.md) | 完整变更日志，从用户视角列出所有版本、功能、改进与缺陷修复。 |
| [GitHub Releases](https://github.com/777genius/agent-teams-ai/releases) | 适用于所有平台的可下载安装包。 |
## 相关页面
- [安装](/zh/guide/installation)
- [快速开始](/zh/guide/quickstart)
- [贡献者架构](/zh/reference/contributor-architecture)
- [开发者](/zh/developers/)