dsh-artel 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/guide.ru.md CHANGED
@@ -3,15 +3,46 @@
3
3
  Artel выполняет задачу по разработке в изолированной копии проекта, открытого в текущей сессии чата:
4
4
  показывает работу по ходу дела и переносит результат в ваш проект только по вашей команде.
5
5
 
6
- Откройте вкладку **Artel** в заголовке сессии (кнопка **Artel**) или в подсказках правой панели.
7
- Вкладка привязана к сессии чата, а рабочий каталог этой сессии — это проект.
6
+ Артель открывается прямо из чата. Кнопка с иконкой **Артель** стоит в ряду инструментов композера,
7
+ рядом с «+». Она накладывает панель (оверлей) на область текущего чата; сам чат остаётся под ней и не
8
+ меняется. Панель привязана к этой сессии, а рабочий каталог сессии — это проект.
8
9
 
9
- ## Запуск
10
+ ![Панель «Артель»: рейл сессий и форма новой артели](artel-in-chat/screens/hero.png)
11
+
12
+ ## Открыть артель
13
+
14
+ 1. Откройте чат, в рабочем каталоге которого лежит проект.
15
+ 2. Нажмите кнопку **Артель** в ряду инструментов под полем ввода чата (рядом с **+**). Пока в этой
16
+ сессии идёт запуск, на кнопке горит точка.
17
+ 3. Панель займёт область чата. Вернуться в чат — кнопка **← Чат** в её шапке или клавиша Esc.
18
+ Закрытие панели не останавливает запуск: агенты продолжают работать, а при следующем открытии
19
+ панель вернётся к последнему выбранному запуску.
20
+
21
+ В шапке панели: кнопка **← Чат**, название **Артель**, статус выбранного запуска и кнопка **Обновить**
22
+ (она перечитывает список артелей и открытый запуск; сама лента обновляется, пока панель открыта).
23
+
24
+ Слева — рейл **Сессии**. Это все артели текущей сессии, сгруппированные по проекту. В строке артели:
25
+ точка состояния, задача и краткая строка `Solo · 1/3 · фаза` — режим, сколько агентов уже закончило
26
+ ход из общего числа и текущая фаза (последнее сообщение статуса или плана). Активная артель
27
+ подсвечена, клик открывает её страницу. Кнопка **+ Новая артель** возвращает к форме новой артели, а
28
+ внизу рейла видны счётчики `артелей: N` и `файлов: M`. Пока артелей нет, рейл пишет «Пока нет ни одной
29
+ артели.» и «Опишите задачу справа — агенты работают в изолированной копии.».
30
+
31
+ ## Новая артель
10
32
 
11
- 1. Выберите режим: **Solo** или **Swarm**.
12
- 2. Опишите задачу своими словами: что должно получиться и где это в проекте. Готовить файлы для
13
- агентов не нужно — они находят и читают их сами.
14
- 3. Нажмите **Start** (или Ctrl+Enter).
33
+ Форма занимает правую часть панели. Заголовок называет проект и режим: «Новая артель в <проект> ·
34
+ через <режим>». Если проект ещё не определён, заголовок короче — «Новая артель · через <режим>».
35
+
36
+ 1. Опишите задачу в поле «Что нужно сделать? Опишите задачу для агентов…»: что должно получиться и
37
+ где это в проекте. Готовить файлы не нужно — агенты находят и читают их сами.
38
+ 2. Выберите режим: **Solo** («Один агент, одна копия») или **Swarm** («Три агента делят файлы»).
39
+ 3. Нажмите **Поехали →** (или Ctrl+Enter). Пока запрос уходит, кнопка показывает «Запускаю…».
40
+
41
+ Под формой — напоминание: «Артель работает в изолированной копии проекта. Ваши файлы не меняются, пока
42
+ вы не примените изменения.» Если запуск не стартовал, под кнопкой появляется баннер «Не удалось
43
+ запустить артель» с текстом ошибки.
44
+
45
+ ## Запуск
15
46
 
16
47
  Дальше Artel:
17
48
 
@@ -22,6 +53,10 @@ Artel выполняет задачу по разработке в изолир
22
53
 
23
54
  Копия создаётся один раз на запуск, и все агенты работают в ней. Сам проект не меняется.
24
55
 
56
+ Агенты работают без запросов подтверждения: Artel выдаёт им политику approval `never` и переносит
57
+ режим песочницы (sandbox) из родительской сессии чата. Инструменты, недоступные в этой песочнице,
58
+ вернут агенту отказ, и запуск не зависнет на ожидании подтверждения.
59
+
25
60
  ## Solo
26
61
 
27
62
  Один агент ведёт задачу от начала до конца. Его сообщения, вызовы инструментов и правки появляются в
@@ -32,8 +67,8 @@ Artel выполняет задачу по разработке в изолир
32
67
  Три агента работают в одной копии и видят правки друг друга: каждый читает файлы, которые соседи уже
33
68
  изменили, и подстраивается под них. Они ещё и переписываются между собой: вся команда живёт в одном
34
69
  дереве разговоров, поэтому `send_message({ agent: "<имя>", message: "..." })` доходит до соседа
35
- настоящим ходом, а `list_agents()` показывает всю команду. Сообщения агентов друг другу видны в ленте
36
- с обоими именами (`Orion → Vega`), так что переговоры можно читать, не открывая их разговоры.
70
+ настоящим ходом, а `list_agents()` показывает всю команду. Переписка агентов видна в ленте отдельными
71
+ строками: имя отправителя, стрелка и текст сообщения.
37
72
 
38
73
  **Первый ход — планирование.** Агентам запрещено что-либо править. Они читают проект, договариваются,
39
74
  кто за какие файлы отвечает (при неясной границе — прямо сообщением соседу), и завершают ход одной
@@ -44,7 +79,7 @@ OWNERSHIP: src/app/settings/**
44
79
  ```
45
80
 
46
81
  Artel собирает заявки, оставляет за первым претендентом спорный участок и показывает карту разделения
47
- в ленте. Если двое заявили одни и те же файлы, лента называет обоих и победителя.
82
+ в ленте карточкой **План**. Если двое заявили одни и те же файлы, лента называет обоих и победителя.
48
83
 
49
84
  **Затем — параллельная работа.** Artel отправляет каждому его участок и запускает их одновременно.
50
85
  Каждый читает файлы, которые соседи уже изменили, и подстраивается под них; если нужна правка вне
@@ -53,86 +88,126 @@ Artel собирает заявки, оставляет за первым пре
53
88
  объявить запуск ожидающим, чтобы короткая переписка двух агентов не выглядела как завершённая работа.
54
89
 
55
90
  Пока запуск активен, Artel следит за правками. Когда второй агент трогает файл, который уже трогал
56
- другой, в ленте появляется строка о пересечении с обоими именами. Владение объявляется, но не
57
- блокирует: пересечение видно, правка не запрещается.
91
+ другой, в ленте появляется строка **Конфликт правок** с обоими именами и путём. Владение объявляется,
92
+ но не блокирует: пересечение видно, правка не запрещается.
58
93
 
59
- Агенту, которому не досталось заявленных файлов, Artel выдаёт незанятые файлы рядом с заявленной
60
- работой с пометкой «nobody claimed it» в плане. Если задача по силам одному агенту, остальные просто
61
- ничего не меняют, проверяют копию и сообщают об этом в отчёте.
94
+ Агенту, который ничего не заявил, Artel отдаёт незанятые файлы с пометкой «nobody claimed it» в
95
+ плане, чтобы он не простаивал; если незанятых файлов нет, он становится проверяющим общей копии и
96
+ пишет об этом в отчёте.
62
97
 
63
98
  Если на планирующем ходу никто не объявил участок, Artel спрашивает ещё раз. Если и вторая попытка
64
99
  пуста, Artel делит верхний уровень проекта между агентами, чтобы запуск не остановился, и сообщает об
65
100
  этом в ленте.
66
101
 
67
- ## Пока запуск активен
102
+ ## Страница артели
68
103
 
69
- В заголовке виден статус: подготовка, разделение работы, работа, ожидание вас, применено,
70
- отброшено, ошибка, прервано.
104
+ Справа открывается страница выбранной артели: сверху задача, тег режима (**Solo** или **Swarm**),
105
+ статус, тег с числом изменённых файлов (появляется, когда файлы уже есть) и строка фазы — то же краткое
106
+ описание этапа, что и в рейле.
71
107
 
72
- - **Feed** — все сообщения, вызовы инструментов, смены статуса, план и пересечения по порядку.
73
- - **Agents** — строка на агента с его состоянием и заявленными файлами. **Open conversation**
74
- открывает полный разговор агента в новом чате; эти чаты видны в боковой панели с названием
75
- `Artel · <агент> — <задача>` и архивируются как обычные. В Swarm свой чат есть только у ведущего
76
- агента: двое других — его подагенты и живут внутри этого дерева разговоров, поэтому все трое и могут
77
- переписываться. Их переписка видна в ленте.
78
- - **Сообщение агентам** — поле внизу страницы запуска. В Solo оно уходит агенту; в Swarm вы
79
- выбираете конкретного агента или **All agents** (всем сразу). Сообщение возвращает ожидающий запуск
80
- в работу.
81
- - **Stop** прерывает всех агентов. Уже сделанная в копии работа остаётся доступной для просмотра.
108
+ Статусы запуска: **Подготовка**, **Планирование**, **В работе**, **Ждёт вас**, **Готово**,
109
+ **Остановлено**, **Ошибка**, **Применено**, **Выброшено**.
82
110
 
83
- Когда все агенты простаивают, Artel останавливает запуск, считает разницу с проектом и переводит
84
- запуск в **Waiting for you**.
111
+ ![Страница запуска: реплики агентов и группы вызовов инструментов](artel-in-chat/screens/run.png)
85
112
 
86
- ## Проверка, применение, отказ
113
+ Пока запуск активен, в шапке есть кнопка **Остановить**. Она просит подтверждение: «Остановить
114
+ артель?» с кнопками **Остановить** и **Продолжить** (на время запроса — «Останавливаю…»).
115
+ Остановленный запуск переходит в **Остановлено**, копия и дифф остаются доступны, а сообщением агентов
116
+ можно вернуть в работу.
87
117
 
88
- Список **Changes** показывает каждый файл, который отличается от вашего проекта: `A` — добавлен,
89
- `M` — изменён, `D` — удалён, `B` — двоичный (его можно применить, но не показать текстом). Для
90
- каждого файла видны счётчики добавленных и удалённых строк; откройте файл, чтобы прочитать его куски.
118
+ ### Лента
91
119
 
92
- - Снимите отметки с файлов, которые не нужны. **Select all** и **Select none** — быстрые действия.
93
- - **Apply N files** переносит выбранные файлы в ваш проект.
94
- - **Discard** выбрасывает копию. В проект ничего не попадает.
95
- - **New task** начинает новый запуск; предыдущий остаётся в списке.
120
+ - Полноценные реплики агентов: аватар с инициалом, имя, роль и время; текст выводится как markdown.
121
+ - Вызовы инструментов собраны в компактные строки: имя инструмента и путь к файлу или команда.
122
+ - Строки статуса с отметкой времени и карточка **План** с картой разделения работы.
123
+ - Ваши сообщения — пузырь с подписью «Вы → Всем» или «Вы → <агент>».
124
+ - Переписка агентов между собой: имя отправителя, стрелка и текст сообщения.
125
+ - **Конфликт правок** — если два агента тронули один путь; **Ошибка** — если ход агента завершился
126
+ ошибкой. В обеих строках ниже указан путь, если он известен.
96
127
 
97
- Перед записью Artel заново читает ваш проект. Для каждого выбранного файла проверяется, совпадает ли
98
- он с состоянием на момент старта запуска:
128
+ Пока лента пуста, на её месте надпись «Агенты готовятся — первые сообщения появятся здесь.»; во время
129
+ загрузки — «Загружаю ленту…».
130
+
131
+ ### Сообщение агентам
132
+
133
+ Поле внизу страницы — «Написать агентам…», кнопка **Отправить**. В футере — **Кому**: по умолчанию
134
+ **Всем**, можно выбрать и конкретного агента. Подсказка рядом: «Ctrl+Enter — отправить».
135
+ Сообщение появляется в ленте строкой «Вы → …» и возвращает ожидающий или остановленный запуск в работу,
136
+ пока копия ещё не применена и не отклонена.
137
+
138
+ ## Изменения: применить или отклонить
139
+
140
+ Когда агенты простаивают, Artel останавливается, считает разницу с проектом и переводит запуск в
141
+ **Ждёт вас**. Карточка **Изменения** внизу страницы показывает файлы, которые отличаются от вашего
142
+ проекта: заголовок «Изменения · N файлов» и общие счётчики `+N/−M`. У каждой строки — статус
143
+ **добавлен**, **изменён**, **удалён** или **двоичный** и свои `+N/−M`. Нажмите на файл, чтобы раскрыть
144
+ его дифф (**Показать дифф**); повторное нажатие скрывает его (**Скрыть дифф**). Двоичные файлы
145
+ раскрыть нельзя. В шапке карточки — **Обновить изменения** и свернуть/развернуть карточку (**Показать
146
+ изменения** / **Скрыть изменения**).
147
+
148
+ ![Карточка «Изменения» с раскрытым диффом файла](artel-in-chat/screens/changes.png)
149
+
150
+ - **Применить** — сначала спрашивает подтверждение: «Применить изменения?» и «Изменения будут
151
+ записаны в <проект>. Копия будет удалена.», кнопки **Применить** и **Отмена**. Записываются все
152
+ файлы из карточки; выбора отдельных файлов нет.
153
+ - **Отклонить** — подтверждение «Отклонить изменения?» и «Изолированная копия будет удалена, а
154
+ <проект> останется без изменений.», кнопки **Отклонить** и **Отмена**.
155
+
156
+ После решения на месте кнопок появляется плашка **Применено** с подсказкой «Изменения записаны в
157
+ <проект>.» или **Отклонено** с подсказкой «Копия удалена; проект не изменён.». Если часть файлов не
158
+ удалось записать, карточка добавляет строку «Пропущено: N».
159
+
160
+ Перед записью Artel заново читает ваш проект. Для каждого файла проверяется, совпадает ли он с
161
+ состоянием на момент старта запуска:
99
162
 
100
163
  - Если совпадает — файл применяется.
101
- - Если вы изменили его во время запуска, Artel отказывает этому файлу с причиной `changed in your
102
- project during the run`; остальные файлы тоже не применяются — весь Apply отклоняется, чтобы вы
103
- решили заново.
164
+ - Если вы изменили его во время запуска, Artel отказывает: «Nothing was applied. <файл>: changed in
165
+ your project during the run» — и не записывает ничего, чтобы вы решили заново.
104
166
  - Файл, появившийся в проекте во время запуска, отклоняется так же.
105
167
 
106
- Применение окончательно: запуск становится **Applied**, а его копия остаётся на диске для разбора,
107
- пока её не удалит уборка.
168
+ Применение окончательно: запуск становится **Применено**, его изменения — в проекте, а изолированная копия
169
+ сразу удаляется. Диффы остаются в ленте запуска, так что посмотреть изменения можно и потом.
108
170
 
109
171
  ## Где лежат данные
110
172
 
111
- - Копии: `<DSH home>/artel/<profile>/copies/<run id>` — удаляются при Discard и при старте, если
112
- старше `keepCopiesHours`.
173
+ - Копии: `<DSH home>/artel/<profile>/copies/<run id>` — удаляются при **Применить** и **Отклонить**;
174
+ копия, оставшаяся после сбоя, убирается при следующем старте.
113
175
  - Индекс запусков и ленты: `<DSH home>/artel/<profile>/state/runs` — JSON-индекс и по одному JSONL на
114
176
  запуск, с ограничением размера.
115
177
  - Разговоры агентов: обычные сессии DSH в вашем хранилище сессий.
116
178
 
117
- Artel хранит не больше `maxRunsPerSession` запусков на сессию; самые старые убираются из списка.
179
+ Artel хранит не больше `maxRunsPerSession` запусков на сессию: самые старые завершённые запуски
180
+ (применённые, отклонённые, остановленные, с ошибкой) убираются из списка вместе с копиями. Запуски,
181
+ которые ещё ждут вашего решения, не удаляются.
118
182
 
119
183
  ## Если что-то не работает
120
184
 
121
- **«Artel cannot see the web server»** — в профиле нет веб-сервера Host, страницу не откуда отдать.
122
- Плагину нужен desktop/web-профиль.
185
+ **«Серверная часть «Артели» недоступна. Проверьте, что плагин включён.»** — клиентская половина
186
+ загружена, а серверная не отвечает: плагин выключен или host-половина не загрузилась. Включите плагин и
187
+ перезагрузите страницу.
123
188
 
124
- **«This chat session has no project directory yet»** — у сессии нет рабочего каталога. Откройте
125
- рабочее пространство или начните сессию в каталоге.
189
+ **«Сервер «Артели» перезапускается — повторите чуть позже»** — хост обновляется или перезапускается.
190
+ Подождите и нажмите **Повторить** в баннере.
126
191
 
127
- **«The project is too large to copy»** — пределы копии: 20 000 файлов, 32 МБ на файл, 512 МБ всего.
128
- Тяжёлые каталоги исключайте через `excludeGlobs`.
192
+ **«This chat session has no project directory yet, so there is nothing to copy»** — у сессии нет
193
+ рабочего каталога, копировать нечего. Откройте рабочее пространство или начните сессию в каталоге.
194
+ Если каталог проекта существует, но был удалён или перемещён, сервер отвечает
195
+ «The project directory does not exist».
196
+
197
+ **«Could not copy the project: project is larger than 536870912 bytes; excluded folders or a smaller
198
+ project are required»** — проект не влез в лимит копии 512 МБ. Частичную копию Artel не делает:
199
+ запуск отклоняется. Исключите тяжёлые каталоги через `excludeGlobs` или возьмите проект меньше.
200
+ Файлы крупнее 32 МБ в копию не попадают.
129
201
 
130
202
  **«Another run is already in progress in this session»** — на сессию допускается один активный запуск.
131
203
  Завершите или остановите его.
132
204
 
133
- **Изменений нет** — агенты могли закончить без правок. Прочитайте ленту; если задаче нужен толчок,
134
- напишите агентам.
205
+ **Изменений нет** — агенты могли закончить без правок; карточка пишет «В этой артели нет изменений в
206
+ файлах.». Прочитайте ленту; если задаче нужен толчок, напишите агентам.
207
+
208
+ **Применение отклонено** — в баннере карточки перечислены файлы, изменённые в проекте во время
209
+ запуска. Отклоните запуск, дождитесь, пока файл освободится, и запустите заново: применить только
210
+ остальные файлы нельзя, потому что в карточке нет выбора по файлам.
135
211
 
136
- **Apply отклонён** — в сообщении перечислены файлы, изменённые в проекте во время запуска. Отбросьте
137
- запуск, дождитесь, пока файл освободится, и запустите заново, либо примените остальные файлы новым
138
- запуском.
212
+ **Запуск прерван перезапуском** — если плагин или хост перезапустились, активные запуски становятся
213
+ **Остановлено**. Копия и дифф остаются: их можно применить или отклонить.
package/docs/guide.zh.md CHANGED
@@ -1,115 +1,189 @@
1
1
  # Artel
2
2
 
3
- Artel 在项目的一份隔离副本里执行开发任务:过程中可以看到每一步操作,只有你按下应用按钮,结果才会
4
- 进入你的项目。
3
+ Artel 在项目的隔离副本中执行一项开发任务,而该项目就是当前聊天会话的工作目录:它实时展示工作
4
+ 过程,并且只在你要求时把结果写入你的项目。
5
5
 
6
- 在会话标题栏点击 **Artel** 按钮,或从右侧栏的引导页打开 **Artel** 标签页。该标签页属于当前聊天
7
- 会话,会话的工作目录就是项目本身。
6
+ Artel 直接从聊天中打开。**Artel** 图标按钮位于输入框的工具行中,「+」的旁边。它会在当前聊天区域
7
+ 上覆盖一层面板(浮层),聊天仍保留在下面且不会被修改。面板属于当前会话,而会话的工作目录就是
8
+ 项目。
8
9
 
9
- ## 启动一次运行
10
+ ![Artel 面板:会话栏和新建运行表单](artel-in-chat/screens/hero.png)
10
11
 
11
- 1. 选择模式:**Solo** 或 **Swarm**。
12
- 2. 用自己的话描述任务:想要什么结果、在项目里的哪个位置。不需要预先准备文件,智能体会自己查找
13
- 并阅读。
14
- 3. 点击 **Start**(或按 Ctrl+Enter)。
12
+ ## 打开 Artel
15
13
 
16
- 随后 Artel 会:
14
+ 1. 打开一个工作目录中包含项目的聊天。
15
+ 2. 点击聊天输入框下方工具行中的 **Artel**(在 **+** 旁边)。当该会话中有运行正在进行时,按钮上
16
+ 会显示一个圆点。
17
+ 3. 面板会覆盖聊天区域。返回聊天:点击面板标题栏中的 **← 聊天**,或按 Esc。关闭面板不会停止
18
+ 运行:智能体会继续工作,下次打开面板时会回到上次选择的运行。
17
19
 
18
- 1. 把项目复制到项目之外的一个新目录;
19
- 2. 启动一个(Solo)或三个(Swarm)工作目录为该副本的智能体;
20
- 3. 发送任务和一组简短规则:只在副本里改动、绝不碰真实项目、运行与改动匹配的检查、结束时说明
20
+ 面板标题栏包含:**← 聊天**、标题 **Artel**、所选运行的状态,以及 **刷新**(重新读取运行列表和
21
+ 当前打开的运行;面板打开期间动态会自动更新)。
22
+
23
+ 左侧是 **会话** 栏:当前会话的所有 Artel 运行,按项目分组。每一行显示状态点、任务和简短的
24
+ `Solo · 1/3 · 阶段` 行——模式、已结束回合的智能体数占总数的比例,以及当前阶段(最后一条状态或
25
+ 计划消息)。活动运行会高亮,点击一行即可打开它的页面。**+ 新建 Artel** 返回新建运行表单,栏底部
26
+ 显示 `运行:N` 和 `文件:M` 计数。还没有运行时,栏中显示「还没有 Artel 运行。」和「在右侧描述
27
+ 任务——智能体将在隔离副本中工作。」。
28
+
29
+ ## 新建 Artel
30
+
31
+ 表单占据面板右侧。标题会给出项目和模式:「在 <项目> 中新建 Artel · <模式>」。如果项目还未确定,
32
+ 标题会更短:「新建 Artel · <模式>」。
33
+
34
+ 1. 在「需要做什么?描述任务…」中描述任务:要得到什么结果、它在项目中的位置。不需要提前准备
35
+ 文件——智能体会自己查找并读取。
36
+ 2. 选择模式:**Solo**(「一个智能体,一份副本」)或 **Swarm**(「三个智能体划分文件」)。
37
+ 3. 点击 **开始 →**(或 Ctrl+Enter)。请求发出期间,按钮显示「启动中…」。
38
+
39
+ 表单下方是提示:「Artel 在项目的隔离副本中工作。在应用更改之前,你的文件不会被修改。」如果运行
40
+ 没能启动,按钮下方会出现标题为「无法启动 Artel」的横幅,并附上错误文本。
41
+
42
+ ## 启动
43
+
44
+ 接下来 Artel 会:
45
+
46
+ 1. 把项目复制到项目之外的独立目录;
47
+ 2. 启动一个智能体(Solo)或三个智能体(Swarm),工作目录就是该副本;
48
+ 3. 把任务和几条规则交给它们:只在副本中修改、绝不触碰真实项目、运行适当的检查,并在结束时说明
21
49
  做了什么。
22
50
 
23
- 每次运行只创建一份副本,所有智能体共用它。项目本身不会被修改。
51
+ 每次运行只创建一份副本,所有智能体都在其中工作。项目本身不会改变。
52
+
53
+ 智能体在无人值守的情况下工作:Artel 会给它们 `never` 审批策略,并继承父聊天会话的沙箱
54
+ (sandbox)模式。该沙箱中不可用的工具会向智能体返回拒绝,而不是让运行一直等待审批。
24
55
 
25
56
  ## Solo
26
57
 
27
- 一个智能体从头到尾负责这个任务。它的消息、工具调用和文件改动会实时出现在动态里。你随时可以给它
28
- 写消息,消息会进入对话,不会中断当前工作。
58
+ 一个智能体从头到尾负责这项任务。它的消息、工具调用和修改会立即出现在动态中。你随时可以给它发
59
+ 消息——消息会加入对话,不会打断工作。
29
60
 
30
61
  ## Swarm
31
62
 
32
- 三个智能体在同一份副本里工作,能看到彼此已经写入磁盘的改动。它们还能直接互相发消息:整支队伍共用
33
- 一棵对话树,`send_message({ agent: "<名字>", message: "..." })` 会把消息作为真实的一轮送到队友那里,
34
- `list_agents()` 列出全队。智能体之间的消息会以 `Orion → Vega` 的形式出现在动态里,不用打开各自的
35
- 对话就能跟上协商过程。
63
+ 三个智能体在同一份副本中工作,并能看到彼此的修改:每个智能体都会读取邻居已经改过的文件并据此
64
+ 调整。它们还会互相通信:整个团队位于同一棵对话树中,因此
65
+ `send_message({ agent: "<name>", message: "..." })` 会作为真实回合送达邻居,`list_agents()`
66
+ 会列出整个团队。它们的往来会以独立行出现在动态中:发送者名字、箭头和消息文本。
67
+
68
+ **第一个回合是规划。** 智能体不得修改任何内容。它们阅读项目,商定谁负责哪些文件(边界不清晰时
69
+ 直接发消息给邻居),并用一行文字结束回合:
70
+
71
+ ```
72
+ OWNERSHIP: src/app/settings/**
73
+ ```
36
74
 
37
- **第一轮——分工。** 智能体被要求不做任何编辑。它们阅读项目、商定谁负责哪些文件(边界不清楚时直接
38
- 发消息问队友),并以一行 `OWNERSHIP: src/app/settings/**` 结束本轮。
75
+ Artel 收集声明,把有争议的区域留给第一个声明者,并以 **计划** 卡片在动态中展示分工。如果两个
76
+ 智能体声明了相同文件,动态会写出两者以及获胜者。
39
77
 
40
- Artel 汇总这些声明,同一路径以第一个声明者为准,并在动态里显示分工结果。若两个智能体声明了相同
41
- 文件,动态里会同时点出两者和最终归属。
78
+ **然后是并行工作。** Artel 把各自的区域发给他们,并同时启动。每个智能体读取邻居已经改过的文件
79
+ 并据此调整;如果需要修改区域之外的内容,智能体会发消息给负责人,而不是直接改别人的文件,并在
80
+ 最终报告中说明。空闲智能体收到消息后会被唤醒进入新回合;Artel 会在宣布运行等待之前稍作停顿,
81
+ 以免两个智能体之间的短促往来被误认为工作已结束。
42
82
 
43
- **之后——并行工作。** Artel 把最终区域发给每个智能体并同时启动。它们会读邻居的进展,进入别人的
44
- 区域前必须先询问负责人;需要区域外改动时,智能体会给负责人发消息,而不是改别人的文件。
45
- 处于空闲的智能体收到队友消息会被唤醒再跑一轮;Artel 会稍等片刻才把运行置为等待,这样两人之间
46
- 简短的往来不会被误判为工作结束。
83
+ 运行进行期间,Artel 会监视修改。当第二个智能体改动另一个智能体已经改过的文件时,动态中会出现
84
+ **编辑冲突** 行,包含两个名字和路径。归属只是声明,并不强制:重叠可见,但修改不会被阻止。
47
85
 
48
- 运行期间 Artel 监视每次编辑:当第二个智能体改到另一个智能体已改过的路径时,动态里会出现带两个
49
- 名字的冲突行。分工是公开声明,不是强制锁:冲突可见,但编辑不会被拦截。
86
+ 没有声明任何区域的智能体会分到无人认领的文件,并在计划中标注「nobody claimed it」,以免闲置;
87
+ 如果没有无人认领的文件,它就成为共享副本的检查者,并在报告中说明。
50
88
 
51
- 如果分工轮里没有任何声明,Artel 会再问一次;第二次仍为空时,Artel 按项目顶层目录把工作分给
52
- 各智能体,让运行继续,并在动态里说明。
89
+ 如果规划回合中没有人声明区域,Artel 会再问一次。如果第二次仍然为空,Artel 会把项目的顶层目录
90
+ 分给各智能体,以免运行停滞,并在动态中说明。
53
91
 
54
- ## 运行期间
92
+ ## 运行页面
55
93
 
56
- 标题显示状态:准备中、分工中、工作中、等待你、已应用、已丢弃、失败、已中断。
94
+ 所选运行的页面在右侧打开:顶部是任务、模式标签(**Solo** 或 **Swarm**)、状态、已修改文件数
95
+ 标签(有文件后出现)以及阶段行——与栏中相同的简短阶段说明。
57
96
 
58
- - **Feed** — 按顺序显示所有消息、工具调用、状态变化、分工和冲突。
59
- - **Agents** — 每个智能体一行,显示状态和声明的文件。**Open conversation** 会在新聊天里打开该
60
- 智能体的完整对话;这些聊天会以 `Artel · <agent> — <task>` 出现在侧边栏,可以像普通聊天一样归档。
61
- Swarm 中只有主智能体有自己的聊天:另外两个是它的子智能体,住在这棵对话树里——正因如此三者才能
62
- 互相发消息。它们的往来显示在动态里。
63
- - **给智能体写消息** — 运行页底部的输入框。Solo 中直接发给唯一智能体;Swarm 中可选择某个智能体
64
- 或 **All agents**(广播)。等待中的运行收到消息后会重新进入工作。
65
- - **Stop** 中断所有智能体。副本里已完成的工作仍可查看。
97
+ 运行状态:**准备中**、**规划中**、**进行中**、**等待你**、**已完成**、**已停止**、**失败**、
98
+ **已应用**、**已丢弃**。
66
99
 
67
- 所有智能体进入空闲后,Artel 停止运行、计算与项目的差异,并把运行置为 **Waiting for you**。
100
+ ![运行页面:智能体回复和分组的工具调用](artel-in-chat/screens/run.png)
68
101
 
69
- ## 检查、应用、丢弃
102
+ 运行进行期间,标题栏中有 **停止** 按钮。它会请求确认:「停止这次 Artel 运行?」并给出
103
+ **停止运行** 和 **继续**(请求发出期间显示「停止中…」)。停止后的运行变为 **已停止**;副本和
104
+ 差异仍然可用,给智能体发消息可以让它重新工作。
70
105
 
71
- **Changes** 列出每个与你的项目不同的文件:`A` 新增、`M` 修改、`D` 删除、`B` 二进制(可应用,但
72
- 不能以文本预览)。每个文件显示新增和删除的行数;展开可查看具体差异。
106
+ ### 动态
73
107
 
74
- - 取消勾选你不想应用的文件。**Select all** 和 **Select none** 是快捷操作。
75
- - **Apply N files** 把选中的文件写回你的项目。
76
- - **Discard** 丢弃副本,项目里不会有任何变化。
77
- - **New task** 开始新的运行;上一次运行仍留在列表里。
108
+ - 完整的智能体回复:带首字母的头像、名字、角色和时间;文本按 markdown 渲染。
109
+ - 工具调用被归入紧凑的行:工具名和文件路径或命令。
110
+ - 带时间戳的状态行,以及展示分工的 **计划** 卡片。
111
+ - 你的消息:标有「你 → 所有人」或「你 → <智能体>」的气泡。
112
+ - 智能体之间的往来:发送者名字、箭头和消息文本。
113
+ - 两个智能体碰到同一路径时出现 **编辑冲突**;智能体回合失败时出现 **错误**。两者在已知时都会
114
+ 在下方给出路径。
78
115
 
79
- 写入之前 Artel 会重新读取你的项目:对每个选中的文件检查它是否仍与运行开始时的状态一致。
116
+ 动态为空时显示「智能体正在准备——消息会出现在这里。」;加载期间显示「正在加载动态…」。
80
117
 
81
- - 一致则应用。
82
- - 如果你在运行期间改过该文件,Artel 会以 `changed in your project during the run` 拒绝该文件;
83
- 整个应用会被拒绝,让你重新决定。
84
- - 运行期间在项目里新出现的文件同样会被拒绝。
118
+ ### 给智能体发消息
85
119
 
86
- 应用是最终操作:运行变为 **Applied**,副本留在磁盘上供检查,直到清理时删除。
120
+ 底部的输入框是「给智能体发消息…」,按钮为 **发送**。页脚有 **发给**:默认 **所有人**,也可以
121
+ 选择具体智能体。旁边提示「Ctrl+Enter — 发送」。消息会以「你 → …」出现在动态中,并在副本尚未
122
+ 应用或丢弃之前,让等待或已停止的运行重新工作。
123
+
124
+ ## 更改:应用或丢弃
125
+
126
+ 当智能体空闲下来,Artel 会停止、计算与你的项目之间的差异,并把运行转为 **等待你**。页面底部的
127
+ **变更** 卡片列出与你的项目不同的文件:标题「变更 · N 个文件」和总计 `+N/−M`。每行有状态——
128
+ **新增**、**修改**、**删除** 或 **二进制**——以及自己的 `+N/−M`。点击文件可展开差异
129
+ (**显示差异**),再次点击则收起(**隐藏差异**)。二进制文件无法展开。卡片标题栏中有
130
+ **刷新更改** 和折叠开关(**显示更改** / **隐藏更改**)。
131
+
132
+ ![展开文件差异的「变更」卡片](artel-in-chat/screens/changes.png)
133
+
134
+ - **应用** 会先请求确认:「应用这些更改?」和「更改将写入 <项目>。隔离副本将被删除。」,按钮为
135
+ **应用** 和 **取消**。它会写入卡片中的所有文件;没有逐文件选择。
136
+ - **丢弃** 会询问「丢弃这些更改?」和「隔离副本将被删除,<项目> 保持不变。」,按钮为
137
+ **丢弃** 和 **取消**。
138
+
139
+ 做出决定后,按钮处会出现标记:**已应用** 并附「更改已写入 <项目>。」,或 **已丢弃** 并附
140
+ 「副本已删除;项目未更改。」。如果部分文件未能写入,卡片会加上「已跳过:N」。
141
+
142
+ 写入之前,Artel 会重新读取你的项目。对每个文件,它会检查该文件是否仍与运行开始时一致:
143
+
144
+ - 如果一致,文件被应用。
145
+ - 如果你在运行期间改过它,Artel 会拒绝:「Nothing was applied. <文件>: changed in your project
146
+ during the run」——并且不写入任何内容,让你重新决定。
147
+ - 运行期间在项目中新出现的文件同样会被拒绝。
148
+
149
+ 应用是最终操作:运行变为 **已应用**,它的更改进入项目,隔离副本会立即删除。差异仍保留在运行的
150
+ 动态中,之后仍可查看改了什么。
87
151
 
88
152
  ## 数据位置
89
153
 
90
- - 副本:`<DSH home>/artel/<profile>/copies/<run id>`——丢弃时删除;启动时删除超过
91
- `keepCopiesHours` 的副本。
92
- - 运行索引和动态:`<DSH home>/artel/<profile>/state/runs`——JSON 索引加每个运行一个 JSONL 动态
93
- 文件,有大小上限。
94
- - 智能体对话:普通的 DSH 会话,保存在你的会话存储里。
154
+ - 副本:`<DSH home>/artel/<profile>/copies/<run id>`——在 **应用** 或 **丢弃** 时删除;崩溃后遗留的
155
+ 副本会在下次启动时清理。
156
+ - 运行索引和动态:`<DSH home>/artel/<profile>/state/runs`——一个 JSON 索引和每次运行一个 JSONL
157
+ 文件,大小有上限。
158
+ - 智能体对话:你会话存储中的普通 DSH 会话。
95
159
 
96
- 每个会话最多保留 `maxRunsPerSession` 次运行,超出后最旧的会从列表中移除。
160
+ Artel 每个会话最多保留 `maxRunsPerSession` 次运行:最旧的已结束运行(已应用、已丢弃、已停止、
161
+ 失败)会连同副本一起从列表中移除。仍在等待你决定的运行不会被移除。
97
162
 
98
163
  ## 常见问题
99
164
 
100
- **「Artel cannot see the web server」** —— 当前档案没有 Host Web 服务器,页面无法提供。此插件需要
101
- 桌面/网页档案。
165
+ **「Artel 服务端不可用。请检查插件是否已启用。」**——客户端部分已加载,但服务端不响应:插件被
166
+ 禁用,或服务端部分加载失败。请启用插件并重新加载页面。
102
167
 
103
- **「This chat session has no project directory yet」** —— 会话没有工作目录。先打开工作区,或在
104
- 某个目录下开始会话。
168
+ **「Artel 服务端正在重启——请稍后重试」**——服务端正在更新或重启。请稍候,并在横幅中点击
169
+ **重试**。
105
170
 
106
- **「The project is too large to copy」** —— 副本上限为 20 000 个文件、单文件 32 MB、总计 512 MB。
107
- 用 `excludeGlobs` 排除体积大的目录。
171
+ **「This chat session has no project directory yet, so there is nothing to copy」**——会话没有工作
172
+ 目录,没有可复制的内容。请打开工作空间,或在目录中启动会话。如果项目目录存在但已被删除或移动,
173
+ 服务端会返回「The project directory does not exist」。
108
174
 
109
- **「Another run is already in progress in this session」** —— 每个会话只允许一个活动运行,请先结束
175
+ **「Could not copy the project: project is larger than 536870912 bytes; excluded folders or a
176
+ smaller project are required」**——项目超过 512 MB 的副本上限。Artel 不会做部分副本:运行会被
177
+ 拒绝。请用 `excludeGlobs` 排除庞大的目录,或改用更小的项目。单个文件超过 32 MB 不会进入副本。
178
+
179
+ **「Another run is already in progress in this session」**——每个会话只允许一个活动运行。请完成
110
180
  或停止它。
111
181
 
112
- **没有显示改动** —— 智能体可能没有编辑文件就结束了。查看动态;如果需要推动,就给智能体写消息。
182
+ **没有更改**——智能体可能没有做任何修改就结束了;卡片会显示「本次运行没有文件更改。」。请查看
183
+ 动态;如果任务需要推动,就给智能体发消息。
184
+
185
+ **应用被拒绝**——卡片横幅会列出运行期间在你的项目中发生变化的文件。请丢弃这次运行,等文件空闲
186
+ 后重新启动:只应用其余文件是不可能的,因为卡片没有逐文件选择。
113
187
 
114
- **应用被拒绝** —— 消息里列出了运行期间在项目中被改动的文件。丢弃本次运行,等文件稳定后重跑,或
115
- 用新的运行应用剩下的文件。
188
+ **运行因重启而中断**——如果插件或服务端重启,活动运行会变为 **已停止**。副本和差异仍然保留:
189
+ 你可以应用或丢弃它们。