docs(guide): improve clarity and completeness of Workflows section (EN+RU)
Add task lifecycle diagram, review states, auth configuration blocks, common member states, CLI auth diagnostic, and safe-cleanup guidance. Synchronize EN and RU pages for runtime-setup, agent-workflow, code-review, and troubleshooting.
This commit is contained in:
777genius
parent
96b9eab346
commit
1490da10f9
8 changed files with 483 additions and 94 deletions
|
|
@ -2,34 +2,84 @@
|
|||
|
||||
Agent Teams makes agent work visible as task state, messages, logs, and reviewable code changes.
|
||||
|
||||
## Lifecycle
|
||||
## Modes
|
||||
|
||||
| Stage | What happens |
|
||||
| Mode | Description |
|
||||
| --- | --- |
|
||||
| Provisioning | The app starts the team and confirms runtime readiness |
|
||||
| Planning | The lead creates tasks and may assign teammates |
|
||||
| In progress | Agents work in parallel and update task state |
|
||||
| Review | Changes are reviewed by agents or by you |
|
||||
| Done | Accepted work stays linked to its task history |
|
||||
| Solo | One teammate with self-managed tasks |
|
||||
| Team | Many teammates working in parallel, reviewing each other |
|
||||
|
||||
Both modes share the same kanban, task logs, and code review surfaces.
|
||||
|
||||
## Task lifecycle
|
||||
|
||||
| Stage | What happens | Owner |
|
||||
| --- | --- | --- |
|
||||
| Provisioning | The app starts the runtime, confirms the process is alive, and waits for bootstrap confirmation | App |
|
||||
| Planning | The lead creates tasks, optionally assigns teammates, and sets dependencies | Lead or user |
|
||||
| In progress | Agents work in parallel and update task state via board MCP tools | Teammates |
|
||||
| Review | Changes are reviewed by agents or by you before final acceptance | Team lead or user |
|
||||
| Done | Accepted work stays linked to its task history and can still be inspected later | User |
|
||||
|
||||
### Planning → In progress
|
||||
|
||||
When a teammate starts a task, the board status becomes `in_progress`. The agent creates a task comment with its plan and continues working. All native tool actions (read, bash, edit, write) are streamed into a task log.
|
||||
|
||||
### In progress → Review
|
||||
|
||||
When the teammate finishes work, it posts a result comment and marks the task `completed`. The lead can then decide whether to accept it immediately or move it into review.
|
||||
|
||||
### Review → Done
|
||||
|
||||
If the review surface shows acceptable changes, approve the review. The task is finalized and linked to its diff.
|
||||
|
||||
::: warning Fix-first review
|
||||
If a teammate is asked for changes during review, it should post a follow-up comment with the fixes, then the lead can approve.
|
||||
:::
|
||||
|
||||
## Kanban board
|
||||
|
||||
The board is the primary operating surface. It lets you scan work, spot blocked tasks, open task detail, inspect logs, and review changes without reading raw session files.
|
||||
The board is the primary operating surface. It lets you:
|
||||
|
||||
- Scan open, blocked, and in-review work
|
||||
- Open task detail and inspect runtime logs
|
||||
- Review changes without reading raw session files
|
||||
- Assign or reassign owners
|
||||
|
||||
::: tip
|
||||
Use quick action buttons on cards to start, complete, or request review without opening the detail panel.
|
||||
:::
|
||||
|
||||
## Messages and comments
|
||||
|
||||
Use direct messages when you need to redirect an agent. Use task comments when the note belongs to a specific piece of work. Comments preserve context for later review.
|
||||
| Channel | When to use |
|
||||
| --- | --- |
|
||||
| Direct message | Redirect an agent, ask a quick question |
|
||||
| Task comment | Notes that belong to a specific task |
|
||||
|
||||
Comments preserve context for later review and appear in the task timeline.
|
||||
|
||||
::: tip Prefer task comments
|
||||
If the remark is about a specific task, add it as a comment on that task rather than sending a direct message. It keeps the history linked to the work.
|
||||
:::
|
||||
|
||||
## Task logs
|
||||
|
||||
Task-specific logs isolate runtime output, actions, and messages for one assignment. Use them when you need to answer:
|
||||
Task-specific logs isolate runtime output, actions, and messages for one assignment. Use them to answer:
|
||||
|
||||
- what did this agent run?
|
||||
- why did it change this file?
|
||||
- did it ask another teammate for help?
|
||||
- which task produced this diff?
|
||||
- What did this agent run?
|
||||
- Why did it change this file?
|
||||
- Did it ask another teammate for help?
|
||||
- Which task produced this diff?
|
||||
|
||||
## Parallel work patterns
|
||||
|
||||
Teammates can work on independent tasks at the same time. You can also create dependency links (`blocked-by`) so that one task waits until another is complete. Watch the board for blocked lanes and reassign owners if one teammate is idle while another is overloaded.
|
||||
|
||||
## Live processes
|
||||
|
||||
The live process section shows URLs and running processes when agents start local servers or tools. Open URLs directly from the app to inspect results.
|
||||
The live process section shows URLs and running processes when agents start local servers or tools. Open URLs directly from the app to inspect results. Processes remain registered until they are explicitly stopped or the runtime exits.
|
||||
|
||||
## Cross-team communication
|
||||
|
||||
Agents can send messages to other teams when teams are linked. Use this for handoffs, shared libraries, or status checks between squads.
|
||||
|
|
|
|||
|
|
@ -4,32 +4,60 @@ Code review in Agent Teams is task-centered. You inspect what changed for a spec
|
|||
|
||||
## Review surface
|
||||
|
||||
Use the review UI to:
|
||||
For each completed task that touched files, the review UI lets you:
|
||||
|
||||
- inspect changed files
|
||||
- accept or reject individual hunks
|
||||
- leave comments
|
||||
- connect the diff back to the task and agent logs
|
||||
- Inspect changed files with before/after context
|
||||
- Accept or reject individual hunks
|
||||
- Leave inline comments
|
||||
- Connect the diff back to the task description and agent logs
|
||||
|
||||
## Hunk-level decisions
|
||||
|
||||
Accept small correct changes and reject isolated mistakes without throwing away the whole task. This is useful when an agent mostly solved the task but overreached in one file.
|
||||
|
||||
::: tip Accept incrementally
|
||||
If a diff is mostly correct, accept the good hunks first and request changes only for the parts that need fixing. This keeps the board moving.
|
||||
:::
|
||||
|
||||
## Initiating review
|
||||
|
||||
1. Open a completed task
|
||||
2. Look at the **Changes** tab
|
||||
3. If the diff looks reasonable, click **Request Review** to move the task into the review column
|
||||
|
||||
During review the task is not yet considered done, so other teammates or the lead can still comment on it.
|
||||
|
||||
## Review states
|
||||
|
||||
| State | Meaning |
|
||||
| --- | --- |
|
||||
| `none` | Task is new, in progress, or completed but not yet in review |
|
||||
| `review` | The task is actively under review |
|
||||
| `needsFix` | Changes were requested; the owner must update before re-approval |
|
||||
| `approved` | The review was accepted and the task is finalized |
|
||||
|
||||
## Agent review workflow
|
||||
|
||||
Teams can review each other's work before you make the final call. This catches obvious regressions and keeps the board honest, but you should still review risky areas yourself.
|
||||
|
||||
## Review participants
|
||||
|
||||
The team lead is the default reviewer. You can configure additional reviewers in the Kanban settings if you want peers to review each other's work.
|
||||
|
||||
## What to check manually
|
||||
|
||||
Prioritize:
|
||||
Prioritize these areas when reviewing:
|
||||
|
||||
- provider auth and runtime detection
|
||||
- IPC, preload, and filesystem boundaries
|
||||
- Git and worktree behavior
|
||||
- parsing and task lifecycle logic
|
||||
- persistence and code review flows
|
||||
- **Provider auth and runtime detection** — did the agent change runtime setup in a way that would break other paths?
|
||||
- **IPC, preload, and filesystem boundaries** — keep Electron responsibilities separated
|
||||
- **Git and worktree behavior** — verify branch naming, commits, and pushes
|
||||
- **Parsing and task lifecycle logic** — changes to task references, chunking, or filtering can break message delivery
|
||||
- **Persistence and code review flows** — changes to task storage or review state must stay consistent across IPC layers
|
||||
|
||||
## Verification
|
||||
|
||||
Prefer focused verification commands. Broad formatting or lint-fix commands should not be used unless the task explicitly intends broad formatting churn.
|
||||
|
||||
::: warning Do not auto-format across the whole project
|
||||
Unless the task is specifically about formatting, avoid running `pnpm lint:fix` on unrelated files. It creates noise in the review surface.
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Agent Teams is a coordination layer. The actual model work runs through supporte
|
|||
## Supported paths
|
||||
|
||||
| Path | Use when |
|
||||
| --- | --- |
|
||||
|------|----------|
|
||||
| Claude | You already use Claude Code or Anthropic-backed workflows |
|
||||
| Codex | You want Codex-native runtime integration |
|
||||
| OpenCode | You want multimodel routing and broad provider coverage |
|
||||
|
|
@ -16,18 +16,48 @@ The app detects supported runtimes and guides setup from the UI when possible.
|
|||
|
||||
Agent Teams has no paid tier of its own. You bring the provider access you already have: subscriptions, local runtime auth, or API keys depending on the path you choose.
|
||||
|
||||
::: tip
|
||||
If you are new to Claude Code, the app includes a built-in installer and authentication helper. Look for the "Install Claude Code" button in the runtime settings.
|
||||
:::
|
||||
|
||||
## Multimodel mode
|
||||
|
||||
Multimodel mode can route work through many provider backends via OpenCode-compatible configuration. Use it when you need provider flexibility or want teammates to use different model lanes.
|
||||
|
||||
Example `~/.opencode/config.json`:
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"anthropic": { "apiKey": "<your-key>" },
|
||||
"openai": { "apiKey": "<your-key>" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Pre-flight checklist
|
||||
|
||||
Before creating your first team:
|
||||
|
||||
- [ ] The chosen runtime is installed and available in your shell `PATH`.
|
||||
- [ ] You have authenticated with the provider (Claude Code `claude login`, OpenCode `opencode auth`, etc.).
|
||||
- [ ] The provider has access to the model you plan to assign.
|
||||
- [ ] The project path exists and is readable.
|
||||
|
||||
::: warning
|
||||
Do not add many providers or multimodel lanes until you have confirmed that a single teammate can launch successfully. Keep the first setup minimal.
|
||||
:::
|
||||
|
||||
## Operational advice
|
||||
|
||||
- Keep the first runtime setup simple.
|
||||
- Confirm one team can launch before adding many providers.
|
||||
- Treat auth, provider model names, and runtime PATH issues as setup problems, not team-prompt problems.
|
||||
- If launch hangs, check the troubleshooting page before changing code.
|
||||
- If launch hangs, check the [Troubleshooting](./troubleshooting.md) page before changing team prompts.
|
||||
|
||||
## When to switch runtime paths
|
||||
|
||||
Switch when the current path is blocked by model availability, rate limits, provider capabilities, or team role needs. Keep the same project and team workflow, but validate one small task after switching.
|
||||
|
||||
::: tip
|
||||
You can mix paths in the same team: for example, assign the lead to Claude while secondary teammates run in OpenCode lanes for multimodel flexibility.
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -6,35 +6,108 @@ Most team issues fall into one of four buckets: runtime setup, launch confirmati
|
|||
|
||||
Check:
|
||||
|
||||
- the selected runtime is installed or authenticated
|
||||
- the runtime is available in the environment PATH
|
||||
- the provider has access to the requested model
|
||||
- the project path exists and is readable
|
||||
- The selected runtime is installed or authenticated
|
||||
- The runtime is available in the environment `PATH`
|
||||
- The provider has access to the requested model
|
||||
- The project path exists and is readable
|
||||
|
||||
If OpenCode shows `registered` but bootstrap is unconfirmed, inspect launch logs before changing team prompts.
|
||||
::: tip
|
||||
Run the runtime binary directly in a terminal to verify it is on PATH and authenticated. For example: `claude --version` or `opencode --version`.
|
||||
:::
|
||||
|
||||
### OpenCode bootstrap unconfirmed
|
||||
|
||||
If OpenCode shows `registered` but bootstrap is unconfirmed:
|
||||
|
||||
1. Inspect the launch logs in the UI.
|
||||
2. Check `~/.claude/teams/<team>/launch-state.json` for the member state.
|
||||
3. Look at `~/.claude/teams/<team>/.opencode-runtime/lanes/<lane-id>/manifest.json` for evidence.
|
||||
4. Do not change team prompts until you confirm whether the lane started but failed to commit evidence.
|
||||
|
||||
::: warning
|
||||
A missing OpenCode inbox during primary launch is normal. Secondary lanes start after primary filesystem readiness. Do not treat primary hang as an OpenCode bug unless the UI explicitly shows `Y` members waiting with `Y` incorrectly including OpenCode lanes.
|
||||
:::
|
||||
|
||||
## Agent replies are missing
|
||||
|
||||
Open task logs and teammate messages. Missing replies often come from runtime delivery, parsing, or task filtering issues. Do not assume the model ignored the message until logs confirm it.
|
||||
Open task logs and teammate messages. Missing replies often come from:
|
||||
|
||||
- Runtime delivery gaps
|
||||
- Parsing or task filtering issues
|
||||
- The agent is still processing (large tasks may take minutes)
|
||||
|
||||
Do not assume the model ignored the message until logs confirm it.
|
||||
|
||||
::: tip
|
||||
For OpenCode teammates, check that `agent-teams_message_send` was called with the correct `from`, `to`, and `taskRefs`. OpenCode replies must be sent via MCP tools, not plain text.
|
||||
:::
|
||||
|
||||
## Tasks are not linked to changes
|
||||
|
||||
Use task-specific logs and code review links. If a diff appears detached, check whether the task id or task reference was included in the agent output.
|
||||
Use task-specific logs and code review links. If a diff appears detached:
|
||||
|
||||
- Check whether the task id or task reference was included in the agent output.
|
||||
- Verify the agent called `task_add_comment` before making edits.
|
||||
- Ensure the agent called `task_start` so the board knows work began.
|
||||
|
||||
## Rate limits
|
||||
|
||||
If a provider reports a known reset time, Agent Teams can nudge the lead to continue after cooldown. If reset time is unknown, wait or switch provider/runtime path.
|
||||
|
||||
## Common member states
|
||||
|
||||
| State | Meaning |
|
||||
|-------|---------|
|
||||
| `confirmed_alive` + `bootstrapConfirmed` | Healthy and usable |
|
||||
| `registered` / `runtime_pending_bootstrap` | Process or lane exists, but bootstrap proof is not committed yet |
|
||||
| `failed_to_start` + `runtime_process` | A process exists but the launch gate failed. Inspect diagnostics |
|
||||
| `failed_to_start` + `stale_metadata` | Persisted pid/session is old or dead |
|
||||
|
||||
::: warning
|
||||
`member_briefing` alone is NOT runtime evidence. For OpenCode, the authoritative proof is committed runtime evidence such as `opencode-sessions.json` and its manifest entry.
|
||||
:::
|
||||
|
||||
## Teammate runtime debug mode
|
||||
|
||||
For local debugging, you can force pane-backed teammates through `tmux`:
|
||||
|
||||
```bash
|
||||
# Terminal launch
|
||||
CLAUDE_TEAM_TEAMMATE_MODE=tmux pnpm dev
|
||||
|
||||
# Or add to custom CLI args
|
||||
--teammate-mode tmux
|
||||
```
|
||||
|
||||
Use this to inspect interactive CLI behavior. Do not treat it as equivalent to the process backend for recovery semantics.
|
||||
|
||||
## CLI auth diagnostic
|
||||
|
||||
Each run of `CliInstallerService.getStatus()` appends one line to `claude-cli-auth-diag.ndjson` inside the Electron logs folder (typically `~/Library/Logs/<product-name>/` on macOS). If the file exceeds **512 KiB**, it is truncated to empty before the next append.
|
||||
|
||||
Check this file if you see "Not logged in" or authentication errors in the packaged app.
|
||||
|
||||
## Safe cleanup
|
||||
|
||||
When cleaning up stale processes:
|
||||
|
||||
1. Identify the pid and confirm it belongs to the current team/lane.
|
||||
2. Stop only processes explicitly owned by the smoke test or the launch you are debugging.
|
||||
3. Do **not** kill all OpenCode processes or shared hosts as a shortcut.
|
||||
|
||||
## When to collect evidence
|
||||
|
||||
Collect:
|
||||
|
||||
- task id
|
||||
- team name
|
||||
- runtime path
|
||||
- launch log excerpt
|
||||
- provider/model
|
||||
- exact time window
|
||||
- Task id
|
||||
- Team name
|
||||
- Runtime path
|
||||
- Launch log excerpt
|
||||
- Provider/model
|
||||
- Exact time window
|
||||
|
||||
This is enough to debug most launch and task lifecycle issues.
|
||||
|
||||
::: tip
|
||||
If the problem persists, open the team's persisted files under `~/.claude/teams/<teamName>/` and correlate UI diagnostics with live process state before changing code.
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -2,34 +2,84 @@
|
|||
|
||||
Agent Teams делает работу агентов видимой через task state, messages, logs и reviewable code changes.
|
||||
|
||||
## Lifecycle
|
||||
## Режимы
|
||||
|
||||
| Этап | Что происходит |
|
||||
| Режим | Описание |
|
||||
| --- | --- |
|
||||
| Provisioning | Приложение запускает команду и проверяет готовность runtime |
|
||||
| Planning | Lead создаёт задачи и назначает teammates |
|
||||
| In progress | Агенты работают параллельно и обновляют статус задач |
|
||||
| Review | Изменения проверяют агенты или вы |
|
||||
| Done | Принятая работа остаётся связанной с историей задачи |
|
||||
| Solo | Один teammate с самоуправляемыми задачами |
|
||||
| Team | Несколько teammates, работающих параллельно и ревьюящих друг друга |
|
||||
|
||||
В обоих режимах используются одни и те же канбан, task logs и surface для код-ревью.
|
||||
|
||||
## Жизненный цикл задачи
|
||||
|
||||
| Этап | Что происходит | Владелец |
|
||||
| --- | --- | --- |
|
||||
| Provisioning | Приложение запускает runtime, проверяет, что процесс жив, и ждёт подтверждения bootstrap | App |
|
||||
| Planning | Lead создаёт задачи, опционально назначает teammates и ставит зависимости | Lead или пользователь |
|
||||
| In progress | Агенты работают параллельно и обновляют статус задач через board MCP tools | Teammates |
|
||||
| Review | Изменения проверяют агенты или вы перед финальным принятием | Lead или пользователь |
|
||||
| Done | Принятая работа остаётся связанной с историей задачи и доступна для просмотра | Пользователь |
|
||||
|
||||
### Planning → In progress
|
||||
|
||||
Когда teammate начинает задачу, статус на доске меняется на `in_progress`. Агент создаёт task comment с планом и продолжает работу. Все native tool actions (read, bash, edit, write) попадают в task log.
|
||||
|
||||
### In progress → Review
|
||||
|
||||
Когда агент завершает работу, он публикует result comment и помечает задачу как `completed`. Lead может принять задачу сразу или перевести её в review.
|
||||
|
||||
### Review → Done
|
||||
|
||||
Если изменения в review выглядят корректно, одобрите review. Задача финализируется и связывается с diff.
|
||||
|
||||
::: warning Review с правками
|
||||
Если во время review агенту запрошены изменения, он должен оставить follow-up comment с исправлениями, после чего lead может одобрить задачу.
|
||||
:::
|
||||
|
||||
## Канбан-доска
|
||||
|
||||
Доска - основной рабочий экран. Через неё удобно смотреть работу, находить blocked tasks, открывать task detail, читать logs и ревьюить changes без ручного чтения session files.
|
||||
Доска - основной рабочий экран. Через неё удобно:
|
||||
|
||||
## Messages и comments
|
||||
- Смотреть открытые, заблокированные и на ревью задачи
|
||||
- Открывать task detail и читать runtime logs
|
||||
- Ревьюить changes без ручного чтения session files
|
||||
- Назначать или переназначать владельцев
|
||||
|
||||
Direct messages подходят для перенаправления агента. Task comments лучше использовать, когда заметка относится к конкретной работе. Комментарии сохраняют контекст для review.
|
||||
::: tip
|
||||
Используйте quick action buttons на карточках для старта, завершения или запроса ревью без открытия detail panel.
|
||||
:::
|
||||
|
||||
## Сообщения и комментарии
|
||||
|
||||
| Канал | Когда использовать |
|
||||
| --- | --- |
|
||||
| Direct message | Перенаправить агента, задать быстрый вопрос |
|
||||
| Task comment | Заметки, относящиеся к конкретной задаче |
|
||||
|
||||
Комментарии сохраняют контекст для review и появляются в таймлайне задачи.
|
||||
|
||||
::: tip Предпочитайте task comments
|
||||
Если замечание относится к конкретной задаче, добавьте его как комментарий к задаче, а не direct message. Это сохраняет историю, привязанную к работе.
|
||||
:::
|
||||
|
||||
## Task logs
|
||||
|
||||
Task-specific logs изолируют runtime output, actions и messages по одному assignment. Они помогают понять:
|
||||
|
||||
- что агент запускал?
|
||||
- почему он изменил этот файл?
|
||||
- просил ли он помощи у teammate?
|
||||
- какая задача породила diff?
|
||||
- Что агент запускал?
|
||||
- Почему он изменил этот файл?
|
||||
- Просил ли он помощи у teammate?
|
||||
- Какая задача породила diff?
|
||||
|
||||
## Параллельная работа
|
||||
|
||||
Teammates могут работать над независимыми задачами одновременно. Вы также можете создавать зависимости (`blocked-by`), чтобы одна задача ждала завершения другой. Следите за заблокированными колонками на доске и переназначайте владельцев, если один teammate простаивает, а другой перегружен.
|
||||
|
||||
## Live processes
|
||||
|
||||
Live process section показывает URLs и running processes, когда агенты поднимают локальные servers или tools. Открывайте URL прямо из приложения.
|
||||
Live process section показывает URLs и running processes, когда агенты поднимают локальные servers или tools. Открывайте URL прямо из приложения. Процессы остаются зарегистрированными до явной остановки или выхода runtime.
|
||||
|
||||
## Межкомандное взаимодействие
|
||||
|
||||
Агенты могут отправлять сообщения в другие команды, если команды связаны. Используйте это для handoffs, shared libraries или status checks между командами.
|
||||
|
|
|
|||
|
|
@ -4,32 +4,60 @@ Code review в Agent Teams строится вокруг задачи. Вы см
|
|||
|
||||
## Review surface
|
||||
|
||||
Через review UI можно:
|
||||
Для каждой завершённой задачи, затронувшей файлы, review UI позволяет:
|
||||
|
||||
- смотреть changed files
|
||||
- принимать или отклонять отдельные hunks
|
||||
- оставлять comments
|
||||
- связывать diff с task logs и агентом
|
||||
- Смотреть changed files с контекстом до/после
|
||||
- Принимать или отклонять отдельные hunks
|
||||
- Оставлять inline comments
|
||||
- Связывать diff с описанием задачи и agent logs
|
||||
|
||||
## Hunk-level decisions
|
||||
|
||||
Принимайте маленькие правильные изменения и отклоняйте отдельные ошибки без удаления всей работы. Это полезно, когда агент в целом решил задачу, но переборщил в одном файле.
|
||||
|
||||
::: tip Принимайте по частям
|
||||
Если diff в основном корректен, сначала примите хорошие hunks и запросите изменения только для тех частей, которые нуждаются в правке. Это не даёт доске застопориться.
|
||||
:::
|
||||
|
||||
## Запуск review
|
||||
|
||||
1. Откройте завершённую задачу
|
||||
2. Перейдите на вкладку **Changes**
|
||||
3. Если diff выглядит разумно, нажмите **Request Review**, чтобы переместить задачу в колонку review
|
||||
|
||||
Во время review задача ещё не считается завершённой, поэтому другие teammates или lead могут оставлять к ней комментарии.
|
||||
|
||||
## Состояния review
|
||||
|
||||
| Состояние | Значение |
|
||||
| --- | --- |
|
||||
| `none` | Задача новая, в работе или завершена, но ещё не на review |
|
||||
| `review` | Задача активно на review |
|
||||
| `needsFix` | Запрошены изменения; владелец должен обновить до повторного одобрения |
|
||||
| `approved` | Review принят, задача финализирована |
|
||||
|
||||
## Agent review workflow
|
||||
|
||||
Команды могут ревьюить работу друг друга до вашего финального решения. Это ловит очевидные регрессии, но risky areas всё равно стоит проверять вручную.
|
||||
|
||||
## Участники review
|
||||
|
||||
Team lead - reviewer по умолчанию. Вы можете настроить дополнительных reviewers в настройках Kanban, если хотите, чтобы peers ревьюили работу друг друга.
|
||||
|
||||
## Что проверять вручную
|
||||
|
||||
Приоритет:
|
||||
Приоритет при review:
|
||||
|
||||
- provider auth и runtime detection
|
||||
- IPC, preload и filesystem boundaries
|
||||
- Git и worktree behavior
|
||||
- parsing и task lifecycle logic
|
||||
- persistence и code review flows
|
||||
- **Provider auth и runtime detection** — изменил ли агент setup так, что сломались другие пути?
|
||||
- **IPC, preload и filesystem boundaries** — сохраняется ли разделение ответственности в Electron
|
||||
- **Git и worktree behavior** — проверьте naming веток, коммиты и пуши
|
||||
- **Parsing и task lifecycle logic** — изменения task references, chunking или filtering могут сломать доставку сообщений
|
||||
- **Persistence и code review flows** — изменения хранилища задач или review state должны оставаться консистентными через IPC layers
|
||||
|
||||
## Verification
|
||||
|
||||
Лучше запускать focused verification commands. Broad formatting или lint-fix команды не стоит использовать, если задача явно не про форматирование.
|
||||
|
||||
::: warning Не запускайте автоформатирование по всему проекту
|
||||
Если задача не про форматирование, избегайте `pnpm lint:fix` на нерелевантных файлах. Это создаёт шум в review surface.
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -2,13 +2,25 @@
|
|||
|
||||
Agent Teams - coordination layer. Model work выполняется через локальные runtimes и providers.
|
||||
|
||||
## Предварительные требования
|
||||
|
||||
Перед запуском команды убедитесь, что:
|
||||
|
||||
- Runtime binary установлен и находится в `PATH`.
|
||||
- Ваш аккаунт провайдера имеет доступ к выбранной модели.
|
||||
- Путь к проекту существует и доступен для чтения.
|
||||
|
||||
::: tip
|
||||
Начните с одного teammate и одного провайдера. Подтвердите запуск одной команды, прежде чем добавлять multimodel lanes.
|
||||
:::
|
||||
|
||||
## Поддерживаемые пути
|
||||
|
||||
| Путь | Когда использовать |
|
||||
| --- | --- |
|
||||
| Claude | Если вы уже используете Claude Code или Anthropic access |
|
||||
| Codex | Для Codex-native workflows и OpenAI access |
|
||||
| OpenCode | Для multimodel routing и широкой provider coverage |
|
||||
| Путь | CLI по умолчанию | Типичные провайдеры | Когда использовать |
|
||||
| --- | --- | --- | --- |
|
||||
| Claude | `claude` | Anthropic | Если вы уже используете Claude Code или Anthropic access |
|
||||
| Codex | `codex` | OpenAI | Для Codex-native workflows и OpenAI access |
|
||||
| OpenCode | `opencode` | OpenRouter и многие другие | Для multimodel routing и широкой provider coverage |
|
||||
|
||||
Приложение по возможности определяет доступные runtimes и ведёт настройку через UI.
|
||||
|
||||
|
|
@ -16,18 +28,71 @@ Agent Teams - coordination layer. Model work выполняется через
|
|||
|
||||
У Agent Teams нет своего платного тарифа. Вы используете доступ к провайдеру, который у вас уже есть: subscription, local runtime auth или API keys в зависимости от выбранного пути.
|
||||
|
||||
- Для **Claude** и **Codex** используется auth соответствующего CLI.
|
||||
- Для **OpenCode** требуются provider-specific API keys в файле конфигурации (например, `openrouter`, `openai`, `anthropic`).
|
||||
|
||||
## Настройка авторизации
|
||||
|
||||
### Claude Code
|
||||
|
||||
Запустите стандартный auth flow в терминале:
|
||||
|
||||
```bash
|
||||
claude login
|
||||
```
|
||||
|
||||
Затем проверьте, что CLI доступен:
|
||||
|
||||
```bash
|
||||
claude --version
|
||||
```
|
||||
|
||||
### Codex
|
||||
|
||||
Установите и авторизуйтесь через CLI OpenAI:
|
||||
|
||||
```bash
|
||||
codex login
|
||||
```
|
||||
|
||||
### OpenCode
|
||||
|
||||
Создайте или отредактируйте `~/.opencode/config.json` (или эквивалентный путь на вашей платформе):
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"openrouter": {
|
||||
"apiKey": "sk-or-..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Используйте точное имя провайдера, которое ожидает OpenCode. Если вы используете кастомное имя, убедитесь, что оно совпадает с provider ID в строке модели (например, `openrouter/moonshotai/kimi-k2.6` использует блок `openrouter`).
|
||||
|
||||
## Multimodel mode
|
||||
|
||||
Multimodel mode может направлять работу через разные provider backends в OpenCode-compatible конфигурации. Используйте его, когда нужна гибкость провайдеров или разные model lanes для teammates.
|
||||
|
||||
## Практические советы
|
||||
::: info Model lanes
|
||||
Каждый teammate может использовать свою пару `providerId` + `model`. В UI редактирования команды разверните опции member, чтобы переопределить глобальные значения.
|
||||
:::
|
||||
|
||||
- Первый runtime setup держите простым.
|
||||
- Подтвердите запуск одной команды до добавления многих providers.
|
||||
- Auth, model names и PATH issues считайте setup-проблемами, а не проблемами team prompt.
|
||||
- Если запуск завис, сначала откройте диагностику.
|
||||
## Чеклист перед запуском
|
||||
|
||||
Перед запуском команды:
|
||||
|
||||
1. Выбранный runtime установлен
|
||||
2. Binary runtime находится в environment `PATH`
|
||||
3. Auth провайдера настроен для выбранного backend
|
||||
4. Провайдер имеет доступ к точной строке модели
|
||||
5. Путь к проекту существует и доступен для чтения
|
||||
|
||||
## Когда менять runtime path
|
||||
|
||||
Меняйте путь, когда текущий упирается в availability модели, rate limits, provider capabilities или роли команды. После смены проверьте одну маленькую задачу.
|
||||
|
||||
::: warning Считайте ошибки setup setup-проблемами
|
||||
Если auth падает, имя модели отклонено или binary runtime не найден — сначала исправьте настройку. Не меняйте team prompts или код проекта, чтобы обойти проблему конфигурации рантайма.
|
||||
:::
|
||||
|
|
|
|||
|
|
@ -1,40 +1,105 @@
|
|||
# Диагностика
|
||||
|
||||
Большинство проблем команды попадает в четыре группы: runtime setup, launch confirmation, task parsing или provider limits.
|
||||
Большинство проблем команды попадает в пять групп: runtime setup, launch confirmation, task parsing, provider limits и review state gaps.
|
||||
|
||||
## Команда не запускается
|
||||
|
||||
Проверьте:
|
||||
Проверьте по порядку:
|
||||
|
||||
- выбранный runtime установлен или авторизован
|
||||
- runtime доступен в environment PATH
|
||||
- у провайдера есть доступ к нужной модели
|
||||
- project path существует и читается
|
||||
1. **Runtime доступен** — выбранный CLI (`claude`, `codex`, `opencode`) установлен
|
||||
2. **PATH reachable** — binary доступен в environment `PATH`
|
||||
3. **Доступ к модели** — у провайдера есть доступ к запрошенной строке модели (особенно для OpenCode точные имена провайдера/модели важны)
|
||||
4. **Путь к проекту** — директория проекта существует и доступна для чтения
|
||||
5. **Network / VPN** — некоторые провайдеры режут трафик при активном VPN
|
||||
|
||||
Если OpenCode показывает `registered`, но bootstrap не подтверждён, сначала смотрите launch logs.
|
||||
### OpenCode: registered, но bootstrap не подтверждён
|
||||
|
||||
Если OpenCode показывает `registered`, но bootstrap не подтверждён, сначала смотрите артефакты, а не меняйте team prompts.
|
||||
|
||||
Посмотрите на свежий artifact неудачного запуска:
|
||||
|
||||
```bash
|
||||
~/.claude/teams/<team>/launch-failure-artifacts/latest.json
|
||||
```
|
||||
|
||||
Манифест внутри включает:
|
||||
|
||||
- `classification` — почему запуск считался неудачным
|
||||
- `bootstrapTransportBreadcrumb` — использованный путь доставки
|
||||
- Статусы spawn members
|
||||
- Редактированные логи и traces
|
||||
|
||||
Также проверьте lane manifest:
|
||||
|
||||
```bash
|
||||
jq '.lanes' ~/.claude/teams/<team>/.opencode-runtime/lanes.json
|
||||
jq '.activeRunId, .entries' ~/.claude/teams/<team>/.opencode-runtime/lanes/<lane>/manifest.json
|
||||
```
|
||||
|
||||
::: tip Не гадайте по UI
|
||||
Всегда коррелируйте UI-диагностику с persisted файлами (`launch-state.json`, `bootstrap-journal.jsonl`) и runtime-specific evidence.
|
||||
:::
|
||||
|
||||
## Не видны ответы агента
|
||||
|
||||
Откройте task logs и teammate messages. Пропавшие replies часто связаны с runtime delivery, parsing или task filtering. Не считайте, что модель проигнорировала сообщение, пока это не подтверждено логами.
|
||||
Откройте task logs и teammate messages. Пропавшие replies часто связаны с:
|
||||
|
||||
- **Runtime delivery retry** — агент мог ответить, но сообщение не было доставлено в приложение. Проверьте delivery ledger.
|
||||
- **Parsing или filtering** — вывод агента не содержал ожидаемых маркеров или task references.
|
||||
- **Task attribution** — работа выполнялась в сессии, но не была привязана к задаче, так как в выводе отсутствовал корректный task id.
|
||||
|
||||
::: warning Не считайте молчание игнорированием
|
||||
Не считайте, что модель проигнорировала сообщение, пока это не подтверждено логами.
|
||||
:::
|
||||
|
||||
## Changes не связаны с tasks
|
||||
|
||||
Используйте task-specific logs и code review links. Если diff выглядит detached, проверьте, был ли task id или task reference в output агента.
|
||||
|
||||
Для OpenCode teammates авторитетным доказательством принадлежности сессии задаче является `opencode-sessions.json` и запись в lane manifest, а не только UI message stream.
|
||||
|
||||
## Rate limits
|
||||
|
||||
Если провайдер сообщает reset time, Agent Teams может подтолкнуть lead продолжить после cooldown. Если reset time неизвестен, подождите или смените provider/runtime path.
|
||||
|
||||
| Поведение провайдера | Рекомендуемое действие |
|
||||
| --- | --- |
|
||||
| Показан known reset time | Дождитесь cooldown и продолжите |
|
||||
| Reset time неизвестен | Смените провайдера или runtime path |
|
||||
| Повторяющиеся 429 | Снизьте concurrency или используйте другой model lane |
|
||||
|
||||
## Проблемы CLI auth
|
||||
|
||||
### `claude login` не сохраняется
|
||||
|
||||
Если CLI авторизован в одном терминале, но приложение говорит, что нет — проверьте, что auth сохранён в ожидаемый config path и что процесс приложения видит тот же `$HOME`.
|
||||
|
||||
### OpenCode provider key отклонён
|
||||
|
||||
- Дважды проверьте, что имя провайдера в `config.json` совпадает с префиксом в строке модели
|
||||
- Убедитесь, что ключ не истёк и не отозван в dashboard провайдера
|
||||
|
||||
## Lane bootstrap завис
|
||||
|
||||
Для OpenCode secondary lanes:
|
||||
|
||||
- Отсутствие `inboxes/<member>.json` — не автоматически баг. OpenCode lanes не обязаны быть primary-inbox-created перед стартом.
|
||||
- Если UI показывает, что команда всё ещё запускается, а primary members уже usable, "all teammates joined" ждёт secondary lanes.
|
||||
- Если `Prepared communication channels for X/Y members` зависло, проверьте, что `Y` некорректно включает secondary OpenCode members.
|
||||
|
||||
### Пустые entries в lane manifest
|
||||
|
||||
Если bridge говорит, что bootstrap успешен, но `manifest.json` показывает `entries: []`, проблема в **evidence commit**, а не в поведении модели. Member не должен считаться deliverable до тех пор, пока не существуют `opencode-sessions.json` и его запись в manifest.
|
||||
|
||||
## Какие данные собрать
|
||||
|
||||
Соберите:
|
||||
Прежде чем обращаться за помощью, соберите:
|
||||
|
||||
- task id
|
||||
- team name
|
||||
- runtime path
|
||||
- launch log excerpt
|
||||
- provider/model
|
||||
- точный time window
|
||||
|
||||
Этого обычно хватает для диагностики launch и task lifecycle issues.
|
||||
- Task id (короткий или полный)
|
||||
- Team name
|
||||
- Runtime path (`claude`, `codex` или `opencode`)
|
||||
- Excerpt launch logs (из `latest.json` или `bootstrap-journal.jsonl`)
|
||||
- Provider / model string
|
||||
- Точный time window, когда произошла проблема
|
||||
|
||||
Этих данных обычно достаточно для диагностики launch и task lifecycle issues.
|
||||
|
|
|
|||
Loading…
Reference in a new issue