dsh-artel 0.0.0-stage → 0.1.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/CHANGELOG.md +40 -0
- package/LICENSE +21 -0
- package/README.md +183 -2
- package/cordis.patch.yml +12 -0
- package/docs/guide.md +136 -0
- package/docs/guide.ru.md +138 -0
- package/docs/guide.zh.md +115 -0
- package/docs/preview.svg +102 -0
- package/docs/publishing.md +130 -0
- package/icon.svg +5 -0
- package/lib/client.js +1824 -0
- package/lib/copy.js +349 -0
- package/lib/diff.js +212 -0
- package/lib/engine.js +903 -0
- package/lib/host-driver.js +489 -0
- package/lib/index.js +319 -0
- package/lib/ownership.js +202 -0
- package/lib/paths.js +114 -0
- package/lib/prompts.js +191 -0
- package/lib/routes.js +323 -0
- package/lib/run-store.js +217 -0
- package/locale/en.json +7 -0
- package/locale/ru.json +7 -0
- package/locale/zh.json +7 -0
- package/package.json +62 -3
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses
|
|
5
|
+
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
## [0.1.0] — 2026-11-17
|
|
8
|
+
|
|
9
|
+
First public release.
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- **Solo** mode: one coding agent runs the task in its own copy of the project, end to end.
|
|
14
|
+
- **Swarm** mode: three agents share one copy and one agent tree. They open with a planning turn
|
|
15
|
+
that divides the files, then work in parallel, read each other's edits, and message each other
|
|
16
|
+
with the standard `send_message` / `list_agents` tools. Peer messages appear in the shared feed.
|
|
17
|
+
- Live run feed: agent messages, tool calls, status changes, ownership plans and collision notices.
|
|
18
|
+
You can write to a running agent without stopping it, and interrupt the run at any time.
|
|
19
|
+
- Per-file diff review with added/removed line counts and a line-by-line unified diff.
|
|
20
|
+
- Manual **Apply**: only the files you tick are copied into your project. A file you edited during
|
|
21
|
+
the run is reported and never overwritten.
|
|
22
|
+
- **Discard** removes the copy; nothing reaches the project.
|
|
23
|
+
- The run copy lives outside the project under `<DSH home>/artel/<profile>/copies` and is swept
|
|
24
|
+
after `keepCopiesHours` (72 by default).
|
|
25
|
+
- Locales: English, Russian, Chinese.
|
|
26
|
+
- Loopback-only HTTP API under `/api/dsh-artel/*`, fenced by local socket, local `Host` header and
|
|
27
|
+
a same-origin `Origin` check.
|
|
28
|
+
- First start moves the data root of the pre-rename `dsh-forge` build to the new `artel` directory,
|
|
29
|
+
so existing run records, feeds and copies keep working.
|
|
30
|
+
|
|
31
|
+
### Notes
|
|
32
|
+
|
|
33
|
+
- The plugin was renamed from `dsh-forge` (the npm name `dsh-forge` belongs to an unrelated
|
|
34
|
+
placeholder package). The tab id changed as well, so an already open Forge tab does not restore —
|
|
35
|
+
open the **Artel** tab once after the restart.
|
|
36
|
+
- Requires DSH `^0.2.2-rc.1` and Node `^22.19.0 || >=24`.
|
|
37
|
+
- No build step: the host half is plain ESM and the client half is hand-written
|
|
38
|
+
`React.createElement`.
|
|
39
|
+
|
|
40
|
+
[0.1.0]: https://github.com/ksolodev/dsh-artel/releases/tag/v0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 dsh-artel contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,184 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-artel
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/dsh-artel)
|
|
4
|
+
[](https://github.com/ksolodev/dsh-artel/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
Run a development task in an isolated copy of your project, watch the work as it happens, review the
|
|
10
|
+
diff line by line, then apply it yourself.
|
|
11
|
+
|
|
12
|
+
Artel is a DeepSeek Harness plugin. It adds an **Artel** tab to the right sidebar of a chat session.
|
|
13
|
+
The chat session's working directory is the project; Artel never touches it until you press Apply.
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
Artel is a DSH bundle: it installs with the standard plugin CLI and needs no build step.
|
|
18
|
+
|
|
19
|
+
**From npm**
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
dsh plugin --profile <profile> add dsh-artel
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
**From the release tarball** — download `dsh-artel-0.1.0.tgz` from the
|
|
26
|
+
[v0.1.0 release](https://github.com/ksolodev/dsh-artel/releases/tag/v0.1.0), then:
|
|
27
|
+
|
|
28
|
+
```sh
|
|
29
|
+
dsh plugin --profile <profile> add C:/path/to/dsh-artel-0.1.0.tgz
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
**From a checkout** — point the plugin CLI at the directory:
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
dsh plugin --profile <profile> add C:/path/to/dsh-artel
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
A directory install is recorded as a `link:` dependency, so edits in the checkout are live after a
|
|
39
|
+
host reload. In the desktop app you can also use **Settings → Plugins → Install from file** and pick
|
|
40
|
+
the `.tgz` or the checkout folder.
|
|
41
|
+
|
|
42
|
+
After installing, restart DeepSeek Harness (or reload the page, which recomposes the client boot
|
|
43
|
+
graph), open a chat session that has a project directory, and click **Artel** in the session header.
|
|
44
|
+
The plugin's page is served over a loopback-only HTTP API, so the plugin and the host must run on the
|
|
45
|
+
same machine.
|
|
46
|
+
|
|
47
|
+
## How it works
|
|
48
|
+
|
|
49
|
+
1. **Copy** — Artel copies the project into a fresh directory under your DSH home. `node_modules` is
|
|
50
|
+
linked, not copied, so the agents can still run the project's checks. The real project is not
|
|
51
|
+
touched.
|
|
52
|
+
2. **Agents** — one agent works in the copy in **Solo**; three agents share one copy and one agent
|
|
53
|
+
tree in **Swarm**, so they can message each other with `send_message`/`list_agents`. The first
|
|
54
|
+
Swarm turn is planning only: the agents divide the files and announce who owns what.
|
|
55
|
+
3. **Diff** — when every agent goes idle, Artel stops the run and shows every changed file with added
|
|
56
|
+
and removed line counts and a line-by-line diff.
|
|
57
|
+
4. **Apply** — you tick the files you want and press **Apply**. Before writing, Artel checks each file
|
|
58
|
+
against the state it had when the run started; a file you edited during the run is reported and
|
|
59
|
+
never overwritten. **Discard** deletes the copy and changes nothing.
|
|
60
|
+
|
|
61
|
+
## Two ways to run a task
|
|
62
|
+
|
|
63
|
+
**Solo** — one agent does the whole task in its own copy of the project. It reads the code, edits the
|
|
64
|
+
copy, and runs whatever checks it needs. Use it when the task is small and well understood: fix a
|
|
65
|
+
bug, add a screen, change some text.
|
|
66
|
+
|
|
67
|
+
Write the task the way you would write it to a colleague: what should come out, and where in the
|
|
68
|
+
project it lives. The agent finds and reads the files itself.
|
|
69
|
+
|
|
70
|
+
**Swarm** — three agents share one copy and one conversation tree. Their first turn is a planning
|
|
71
|
+
turn: they make no edits, they divide the files among themselves and say out loud who owns what, so
|
|
72
|
+
that nobody edits the same file. They can also message each other directly: the team has
|
|
73
|
+
`send_message`/`list_agents`, so a question, a heads-up or a promise to take an area reaches the
|
|
74
|
+
other agents as a real turn, and every such message appears in the shared feed. After the planning
|
|
75
|
+
turn they work in parallel, read each other's edits on disk, and Artel flags any file that two agents
|
|
76
|
+
touch. Checks run once, against the whole copy.
|
|
77
|
+
|
|
78
|
+
Use Swarm when the work splits into pieces that do not meet in the same files.
|
|
79
|
+
|
|
80
|
+
## Review and apply
|
|
81
|
+
|
|
82
|
+
While a run is active, the Artel tab shows the live feed of every agent. You can write to an agent at
|
|
83
|
+
any time without waiting for it to finish; in Swarm you can also address one agent only.
|
|
84
|
+
|
|
85
|
+
When every agent is idle, Artel stops and waits for you:
|
|
86
|
+
|
|
87
|
+
- **Changes** lists every changed file with added and removed line counts. Open a file to see the diff.
|
|
88
|
+
- Untick the files you do not want.
|
|
89
|
+
- **Apply N files** copies the selected files into your project. A file that you edited during the run
|
|
90
|
+
is never overwritten: Artel reports it and leaves it alone.
|
|
91
|
+
- **Discard** deletes the copy. Nothing was applied.
|
|
92
|
+
|
|
93
|
+
The copy lives outside the project, under your DSH home directory, and is removed when the run is
|
|
94
|
+
discarded or when it gets older than `keepCopiesHours`.
|
|
95
|
+
|
|
96
|
+
## Open it
|
|
97
|
+
|
|
98
|
+
1. Open a chat session that has a project directory.
|
|
99
|
+
2. Click the **Artel** button in the session header, or open it from the right sidebar guide.
|
|
100
|
+
3. Pick Solo or Swarm, write the task, press Start.
|
|
101
|
+
|
|
102
|
+
Each agent works in the copy as its working directory. The first agent of a Swarm run is an ordinary
|
|
103
|
+
DSH session, so you can open its full conversation from the Agents section of the Artel tab; the other
|
|
104
|
+
two are that session's subagents, live in the same agent tree, and are not listed in the sidebar as
|
|
105
|
+
separate chats. Solo agents are ordinary sessions as well, titled `Artel · <agent> — <task>`; archive
|
|
106
|
+
or delete those sessions when you no longer need them.
|
|
107
|
+
|
|
108
|
+
## Upgrading from `dsh-forge`
|
|
109
|
+
|
|
110
|
+
The plugin was renamed to Artel (the npm name `dsh-forge` belongs to an unrelated placeholder package).
|
|
111
|
+
On its first start the Host moves the previous data root from `<DSH home>/forge/<profile>` to
|
|
112
|
+
`<DSH home>/artel/<profile>`, so existing run records, feeds and copies stay available. The plugin id
|
|
113
|
+
changed with the name, so an already open Forge tab does not restore — open the **Artel** tab once after
|
|
114
|
+
the restart.
|
|
115
|
+
|
|
116
|
+
## Requirements
|
|
117
|
+
|
|
118
|
+
- DSH `^0.2.2-rc.1` with a Host that provides the session controller (the desktop app or `dsh web`).
|
|
119
|
+
- Node `^22.19.0 || >=24` — the same runtime the Host uses.
|
|
120
|
+
- No Git, no extra binaries and no global install: copies, diffs and applying are done by the plugin.
|
|
121
|
+
|
|
122
|
+
## Configuration
|
|
123
|
+
|
|
124
|
+
All values are optional; set them in the bundle's plugin configuration.
|
|
125
|
+
|
|
126
|
+
| Key | Default | Meaning |
|
|
127
|
+
| --- | --- | --- |
|
|
128
|
+
| `swarmAgentCount` | `3` | Agents per Swarm run (2–8). |
|
|
129
|
+
| `maxRunsPerSession` | `10` | Runs kept per session. Older runs are dropped. |
|
|
130
|
+
| `keepCopiesHours` | `72` | Copies older than this are deleted on startup. `0` disables the sweep. |
|
|
131
|
+
| `diffContext` | `3` | Context lines around each diff hunk (0–12). |
|
|
132
|
+
| `idleGraceMs` | `1200` | How long Artel waits for a possible agent-to-agent message before it calls the run idle (0–10000). |
|
|
133
|
+
| `excludeGlobs` | `[]` | Extra paths never copied, diffed, or applied. |
|
|
134
|
+
| `copyRoot` | `<DSH home>/artel/<profile>/copies` | Where run copies are created. |
|
|
135
|
+
| `stateDir` | `<DSH home>/artel/<profile>/state` | Run index and feeds. |
|
|
136
|
+
|
|
137
|
+
## Limitations
|
|
138
|
+
|
|
139
|
+
- The project is copied as files, not through Git. Git metadata is not copied, and Artel does not
|
|
140
|
+
require Git to be installed.
|
|
141
|
+
- A copy holds up to 20,000 files, 32 MB per file and 512 MB in total. Larger projects are refused
|
|
142
|
+
with an error instead of a partial copy.
|
|
143
|
+
- `node_modules` is linked into the copy instead of copied, so agents can run project checks.
|
|
144
|
+
- Artel watches the copy, not your project: it cannot know about edits you make during the run until
|
|
145
|
+
you apply, and then it refuses to overwrite those files.
|
|
146
|
+
- Only files are applied. Deleted files are deleted on Apply; renames arrive as one deletion and one
|
|
147
|
+
addition.
|
|
148
|
+
- Swarm agents live in one agent tree: the first agent is the session at the root of that tree and the
|
|
149
|
+
other two are its subagents. That is what lets them message each other, and it means the root session
|
|
150
|
+
must exist for their messages to be delivered. Closing that session (or restarting the Host) ends the
|
|
151
|
+
transport, exactly like the "runs stop on restart" rule below. A profile that does not provide the
|
|
152
|
+
subagent stack falls back to three independent sessions: the run still works, but the agents cannot
|
|
153
|
+
message each other and coordinate only through the ownership line and the files on disk.
|
|
154
|
+
- If no one claims a file, Artel hands the unclaimed files that sit next to claimed work to the agents
|
|
155
|
+
that claimed nothing, and marks them in the plan as "nobody claimed it" — so nobody idles through a
|
|
156
|
+
run. If the task is small enough for one agent, the other two end up verifying the copy and say so
|
|
157
|
+
in their summaries instead of inventing work.
|
|
158
|
+
- Restarting the plugin or the Host interrupts active runs. Their work stays reviewable and can still
|
|
159
|
+
be applied or discarded, but the agents stop and no longer accept messages.
|
|
160
|
+
|
|
161
|
+
## Data and privacy
|
|
162
|
+
|
|
163
|
+
Run records and feeds are plain JSON and JSONL files under `stateDir`. Agent conversations are
|
|
164
|
+
ordinary DSH sessions and stay in your session store. The plugin serves its page over a loopback-only
|
|
165
|
+
HTTP API; every request is checked for a local socket, a local Host header and a same-origin origin.
|
|
166
|
+
|
|
167
|
+
## Development
|
|
168
|
+
|
|
169
|
+
```sh
|
|
170
|
+
node --test test/*.test.js
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
No build step: the host half is plain ESM (`lib/*.js`) and the client half is hand-written
|
|
174
|
+
`React.createElement` (`lib/client.js`). CI runs the suite on Ubuntu and Windows with Node 22 and 24.
|
|
175
|
+
|
|
176
|
+
- [ARCHITECTURE.md](ARCHITECTURE.md) — host/client design, the run and data model, the route surface.
|
|
177
|
+
- [docs/publishing.md](docs/publishing.md) — how a release is packed, published and listed.
|
|
178
|
+
- [docs/guide.md](docs/guide.md), [docs/guide.ru.md](docs/guide.ru.md),
|
|
179
|
+
[docs/guide.zh.md](docs/guide.zh.md) — the user guide (en / ru / zh).
|
|
180
|
+
- [CHANGELOG.md](CHANGELOG.md) — release notes.
|
|
181
|
+
|
|
182
|
+
## License
|
|
183
|
+
|
|
184
|
+
MIT © dsh-artel contributors — see [LICENSE](LICENSE).
|
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Artel bundle.
|
|
2
|
+
#
|
|
3
|
+
# This file is the bundle patch: `dsh.bundle.patch` in package.json points here,
|
|
4
|
+
# and the plugin CLI appends this package to the profile's `dsh.profile.bundles`
|
|
5
|
+
# when it is installed.
|
|
6
|
+
#
|
|
7
|
+
# The row id must match the Host plugin's `export const name` (`dsh-artel` in
|
|
8
|
+
# lib/index.js). Keep the config block empty here: settings live in the plugin
|
|
9
|
+
# details page, and the client reads them through the plugin's own routes.
|
|
10
|
+
- insert:
|
|
11
|
+
- id: dsh-artel
|
|
12
|
+
name: dsh-artel
|
package/docs/guide.md
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# Artel
|
|
2
|
+
|
|
3
|
+
Artel runs a development task in an isolated copy of the project open in your chat session, shows the
|
|
4
|
+
work while it happens, and applies the result to your project only when you say so.
|
|
5
|
+
|
|
6
|
+
Open the **Artel** tab from the session header (**Artel** button) or from the right sidebar guide. The
|
|
7
|
+
tab belongs to the current chat session, and that session's working directory is the project.
|
|
8
|
+
|
|
9
|
+
## Start a run
|
|
10
|
+
|
|
11
|
+
1. Choose a mode: **Solo** or **Swarm**.
|
|
12
|
+
2. Describe the task in your own words: what should come out, and where in the project it lives. You do
|
|
13
|
+
not have to prepare files — the agents find and read them.
|
|
14
|
+
3. Press **Start** (or Ctrl+Enter).
|
|
15
|
+
|
|
16
|
+
Artel then:
|
|
17
|
+
|
|
18
|
+
1. copies the project into a fresh directory outside it;
|
|
19
|
+
2. starts one agent (Solo) or three agents (Swarm) whose working directory is the copy;
|
|
20
|
+
3. sends them the task and a short set of rules: own the copy, never touch the real project, run the
|
|
21
|
+
checks that fit the change, and explain what they did at the end.
|
|
22
|
+
|
|
23
|
+
The copy is created once per run and shared by every agent in it. The project itself is not modified.
|
|
24
|
+
|
|
25
|
+
## Solo
|
|
26
|
+
|
|
27
|
+
One agent carries the task from start to finish. Its messages, tool calls and file edits appear in the
|
|
28
|
+
feed as they happen. Write to it at any time; the message joins the conversation without stopping it.
|
|
29
|
+
|
|
30
|
+
## Swarm
|
|
31
|
+
|
|
32
|
+
Three agents work in one copy and read each other's edits on disk as they appear. They also talk to
|
|
33
|
+
each other: the team shares one conversation tree, so `send_message({ agent: "<name>", message: "..." })`
|
|
34
|
+
reaches a teammate as a real turn, and `list_agents()` shows the whole team. Messages the agents send
|
|
35
|
+
each other appear in the feed with both names (`Orion → Vega`), so you can follow the negotiation
|
|
36
|
+
without opening their conversations.
|
|
37
|
+
|
|
38
|
+
**First turn — planning.** The agents are told not to edit anything. They read the project, decide who
|
|
39
|
+
takes which files, talk it over when a boundary is unclear, and end their turn with one line:
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
OWNERSHIP: src/app/settings/**
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Artel collects those claims, keeps the first claim on a contested path, and shows the divided map in
|
|
46
|
+
the feed. If two agents claim the same files, the feed names both agents and the winner.
|
|
47
|
+
|
|
48
|
+
**Then — parallel work.** Artel sends each agent its final area and starts them together. Each agent
|
|
49
|
+
reads the files the others already changed on disk and adapts to them; an agent that needs something
|
|
50
|
+
outside its area messages the owner instead of editing the owner's files, and says so in its final
|
|
51
|
+
summary. A message that arrives while an agent is idle wakes it for another turn; Artel waits a moment
|
|
52
|
+
before calling the run waiting, so a short exchange between two agents does not look like a finished run.
|
|
53
|
+
|
|
54
|
+
While the run is active, Artel watches every edit tool call. When a second agent touches a path that
|
|
55
|
+
another agent already touched, the feed shows a collision line with both names. Ownership is
|
|
56
|
+
announced, not enforced: the collision is visible, but the edit is not blocked.
|
|
57
|
+
|
|
58
|
+
An agent that ends up with no claimed files is handed unclaimed files that sit next to the claimed work,
|
|
59
|
+
marked "nobody claimed it" in the plan. If the task is small enough for one agent, the other two simply
|
|
60
|
+
change nothing, verify the copy and say so in their summaries.
|
|
61
|
+
|
|
62
|
+
If no agent announces ownership in the planning turn, Artel asks once more. If the second attempt also
|
|
63
|
+
comes back empty, Artel splits the top level of the project between the agents so the run can still
|
|
64
|
+
proceed, and says so in the feed.
|
|
65
|
+
|
|
66
|
+
## While the run is active
|
|
67
|
+
|
|
68
|
+
The header shows the run status: preparing, dividing work, working, waiting for you, applied,
|
|
69
|
+
discarded, failed, interrupted.
|
|
70
|
+
|
|
71
|
+
- **Feed** — every message, tool call, status change, plan and collision, in order.
|
|
72
|
+
- **Agents** — one row per agent with its state and claimed files. **Open conversation** opens the
|
|
73
|
+
agent's full DSH conversation in a new chat; those chats also appear in the sidebar titled
|
|
74
|
+
`Artel · <agent> — <task>` and can be archived like any other chat. In Swarm only the lead agent has
|
|
75
|
+
its own chat: the other two are its subagents and live inside that conversation tree, which is exactly
|
|
76
|
+
what lets all three message each other. Their traffic is in the feed instead.
|
|
77
|
+
- **Write to the agents** — the composer at the bottom of the run. In Solo it goes to the agent; in
|
|
78
|
+
Swarm you choose one agent or **All agents** (broadcast). A message turns a waiting run back into a
|
|
79
|
+
working run.
|
|
80
|
+
- **Stop** interrupts every agent. The work already done in the copy stays available for review.
|
|
81
|
+
|
|
82
|
+
When every agent goes idle, Artel stops the run, computes the diff against the copy and marks the run
|
|
83
|
+
as **Waiting for you**.
|
|
84
|
+
|
|
85
|
+
## Review, apply, discard
|
|
86
|
+
|
|
87
|
+
The **Changes** list shows every file that differs from your project: `A` added, `M` modified,
|
|
88
|
+
`D` deleted, `B` binary (binary files can be applied but not previewed as text). Added and removed line
|
|
89
|
+
counts are shown per file; open a file to read its hunks.
|
|
90
|
+
|
|
91
|
+
- Untick files you do not want to apply. **Select all** and **Select none** are shortcuts.
|
|
92
|
+
- **Apply N files** copies the selected files into your project.
|
|
93
|
+
- **Discard** throws the copy away. Nothing reaches your project.
|
|
94
|
+
- **New task** starts a fresh run; the previous run stays in the list.
|
|
95
|
+
|
|
96
|
+
Before writing anything, Artel re-reads your project. For every selected file it checks whether the
|
|
97
|
+
file still matches the state it had when the run started:
|
|
98
|
+
|
|
99
|
+
- If it does, the file is applied.
|
|
100
|
+
- If you changed it during the run, Artel refuses that file and says `changed in your project during
|
|
101
|
+
the run`; the rest of the selection is not applied either — the whole Apply is rejected so that you
|
|
102
|
+
can decide again.
|
|
103
|
+
- A file that appeared in your project during the run is refused the same way.
|
|
104
|
+
|
|
105
|
+
Applying a run is final: the run becomes **Applied** and its copy stays on disk for later inspection
|
|
106
|
+
until the sweep removes it.
|
|
107
|
+
|
|
108
|
+
## Where the data lives
|
|
109
|
+
|
|
110
|
+
- Copies: `<DSH home>/artel/<profile>/copies/<run id>` — deleted on Discard, and on startup when older
|
|
111
|
+
than `keepCopiesHours`.
|
|
112
|
+
- Run index and feeds: `<DSH home>/artel/<profile>/state/runs` — JSON index plus one JSONL feed per
|
|
113
|
+
run, capped per run.
|
|
114
|
+
- Agent conversations: ordinary DSH sessions in your session store.
|
|
115
|
+
|
|
116
|
+
Artel keeps at most `maxRunsPerSession` runs per session; the oldest are dropped from the list.
|
|
117
|
+
|
|
118
|
+
## Troubleshooting
|
|
119
|
+
|
|
120
|
+
**"Artel cannot see the web server"** — the profile does not expose a Host web server, so the page
|
|
121
|
+
cannot be served. This plugin needs the desktop/web profile.
|
|
122
|
+
|
|
123
|
+
**"This chat session has no project directory yet"** — the session has no working directory. Open a
|
|
124
|
+
workspace or start the session in a directory first.
|
|
125
|
+
|
|
126
|
+
**"The project is too large to copy"** — the copy limits are 20,000 files, 32 MB per file, 512 MB in
|
|
127
|
+
total. Exclude heavy directories with `excludeGlobs`.
|
|
128
|
+
|
|
129
|
+
**"Another run is already in progress in this session"** — one active run per session. Stop or finish
|
|
130
|
+
it before starting another.
|
|
131
|
+
|
|
132
|
+
**No changes are shown** — the agents may have finished without editing files. Read the feed; if the
|
|
133
|
+
task needs a nudge, write to the agents.
|
|
134
|
+
|
|
135
|
+
**Apply is refused** — the message names the files that changed in your project during the run.
|
|
136
|
+
Discard the run, or re-run after the file is quiet, or apply the remaining files by starting a new run.
|
package/docs/guide.ru.md
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# Artel
|
|
2
|
+
|
|
3
|
+
Artel выполняет задачу по разработке в изолированной копии проекта, открытого в текущей сессии чата:
|
|
4
|
+
показывает работу по ходу дела и переносит результат в ваш проект только по вашей команде.
|
|
5
|
+
|
|
6
|
+
Откройте вкладку **Artel** в заголовке сессии (кнопка **Artel**) или в подсказках правой панели.
|
|
7
|
+
Вкладка привязана к сессии чата, а рабочий каталог этой сессии — это проект.
|
|
8
|
+
|
|
9
|
+
## Запуск
|
|
10
|
+
|
|
11
|
+
1. Выберите режим: **Solo** или **Swarm**.
|
|
12
|
+
2. Опишите задачу своими словами: что должно получиться и где это в проекте. Готовить файлы для
|
|
13
|
+
агентов не нужно — они находят и читают их сами.
|
|
14
|
+
3. Нажмите **Start** (или Ctrl+Enter).
|
|
15
|
+
|
|
16
|
+
Дальше Artel:
|
|
17
|
+
|
|
18
|
+
1. копирует проект в отдельный каталог вне его;
|
|
19
|
+
2. запускает одного агента (Solo) или трёх (Swarm) с рабочим каталогом, равным копии;
|
|
20
|
+
3. передаёт им задачу и короткие правила: работать только в копии, не трогать настоящий проект,
|
|
21
|
+
запускать подходящие проверки и в конце объяснить, что сделано.
|
|
22
|
+
|
|
23
|
+
Копия создаётся один раз на запуск, и все агенты работают в ней. Сам проект не меняется.
|
|
24
|
+
|
|
25
|
+
## Solo
|
|
26
|
+
|
|
27
|
+
Один агент ведёт задачу от начала до конца. Его сообщения, вызовы инструментов и правки появляются в
|
|
28
|
+
ленте сразу. Писать ему можно в любой момент — сообщение попадёт в разговор, не останавливая работу.
|
|
29
|
+
|
|
30
|
+
## Swarm
|
|
31
|
+
|
|
32
|
+
Три агента работают в одной копии и видят правки друг друга: каждый читает файлы, которые соседи уже
|
|
33
|
+
изменили, и подстраивается под них. Они ещё и переписываются между собой: вся команда живёт в одном
|
|
34
|
+
дереве разговоров, поэтому `send_message({ agent: "<имя>", message: "..." })` доходит до соседа
|
|
35
|
+
настоящим ходом, а `list_agents()` показывает всю команду. Сообщения агентов друг другу видны в ленте
|
|
36
|
+
с обоими именами (`Orion → Vega`), так что переговоры можно читать, не открывая их разговоры.
|
|
37
|
+
|
|
38
|
+
**Первый ход — планирование.** Агентам запрещено что-либо править. Они читают проект, договариваются,
|
|
39
|
+
кто за какие файлы отвечает (при неясной границе — прямо сообщением соседу), и завершают ход одной
|
|
40
|
+
строкой:
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
OWNERSHIP: src/app/settings/**
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Artel собирает заявки, оставляет за первым претендентом спорный участок и показывает карту разделения
|
|
47
|
+
в ленте. Если двое заявили одни и те же файлы, лента называет обоих и победителя.
|
|
48
|
+
|
|
49
|
+
**Затем — параллельная работа.** Artel отправляет каждому его участок и запускает их одновременно.
|
|
50
|
+
Каждый читает файлы, которые соседи уже изменили, и подстраивается под них; если нужна правка вне
|
|
51
|
+
участка, агент пишет владельцу сообщением, а не правит чужой файл, и упоминает это в итоговом отчёте.
|
|
52
|
+
Сообщение, пришедшее простаивающему агенту, будит его на новый ход; Artel немного выжидает, прежде чем
|
|
53
|
+
объявить запуск ожидающим, чтобы короткая переписка двух агентов не выглядела как завершённая работа.
|
|
54
|
+
|
|
55
|
+
Пока запуск активен, Artel следит за правками. Когда второй агент трогает файл, который уже трогал
|
|
56
|
+
другой, в ленте появляется строка о пересечении с обоими именами. Владение объявляется, но не
|
|
57
|
+
блокирует: пересечение видно, правка не запрещается.
|
|
58
|
+
|
|
59
|
+
Агенту, которому не досталось заявленных файлов, Artel выдаёт незанятые файлы рядом с заявленной
|
|
60
|
+
работой с пометкой «nobody claimed it» в плане. Если задача по силам одному агенту, остальные просто
|
|
61
|
+
ничего не меняют, проверяют копию и сообщают об этом в отчёте.
|
|
62
|
+
|
|
63
|
+
Если на планирующем ходу никто не объявил участок, Artel спрашивает ещё раз. Если и вторая попытка
|
|
64
|
+
пуста, Artel делит верхний уровень проекта между агентами, чтобы запуск не остановился, и сообщает об
|
|
65
|
+
этом в ленте.
|
|
66
|
+
|
|
67
|
+
## Пока запуск активен
|
|
68
|
+
|
|
69
|
+
В заголовке виден статус: подготовка, разделение работы, работа, ожидание вас, применено,
|
|
70
|
+
отброшено, ошибка, прервано.
|
|
71
|
+
|
|
72
|
+
- **Feed** — все сообщения, вызовы инструментов, смены статуса, план и пересечения по порядку.
|
|
73
|
+
- **Agents** — строка на агента с его состоянием и заявленными файлами. **Open conversation**
|
|
74
|
+
открывает полный разговор агента в новом чате; эти чаты видны в боковой панели с названием
|
|
75
|
+
`Artel · <агент> — <задача>` и архивируются как обычные. В Swarm свой чат есть только у ведущего
|
|
76
|
+
агента: двое других — его подагенты и живут внутри этого дерева разговоров, поэтому все трое и могут
|
|
77
|
+
переписываться. Их переписка видна в ленте.
|
|
78
|
+
- **Сообщение агентам** — поле внизу страницы запуска. В Solo оно уходит агенту; в Swarm вы
|
|
79
|
+
выбираете конкретного агента или **All agents** (всем сразу). Сообщение возвращает ожидающий запуск
|
|
80
|
+
в работу.
|
|
81
|
+
- **Stop** прерывает всех агентов. Уже сделанная в копии работа остаётся доступной для просмотра.
|
|
82
|
+
|
|
83
|
+
Когда все агенты простаивают, Artel останавливает запуск, считает разницу с проектом и переводит
|
|
84
|
+
запуск в **Waiting for you**.
|
|
85
|
+
|
|
86
|
+
## Проверка, применение, отказ
|
|
87
|
+
|
|
88
|
+
Список **Changes** показывает каждый файл, который отличается от вашего проекта: `A` — добавлен,
|
|
89
|
+
`M` — изменён, `D` — удалён, `B` — двоичный (его можно применить, но не показать текстом). Для
|
|
90
|
+
каждого файла видны счётчики добавленных и удалённых строк; откройте файл, чтобы прочитать его куски.
|
|
91
|
+
|
|
92
|
+
- Снимите отметки с файлов, которые не нужны. **Select all** и **Select none** — быстрые действия.
|
|
93
|
+
- **Apply N files** переносит выбранные файлы в ваш проект.
|
|
94
|
+
- **Discard** выбрасывает копию. В проект ничего не попадает.
|
|
95
|
+
- **New task** начинает новый запуск; предыдущий остаётся в списке.
|
|
96
|
+
|
|
97
|
+
Перед записью Artel заново читает ваш проект. Для каждого выбранного файла проверяется, совпадает ли
|
|
98
|
+
он с состоянием на момент старта запуска:
|
|
99
|
+
|
|
100
|
+
- Если совпадает — файл применяется.
|
|
101
|
+
- Если вы изменили его во время запуска, Artel отказывает этому файлу с причиной `changed in your
|
|
102
|
+
project during the run`; остальные файлы тоже не применяются — весь Apply отклоняется, чтобы вы
|
|
103
|
+
решили заново.
|
|
104
|
+
- Файл, появившийся в проекте во время запуска, отклоняется так же.
|
|
105
|
+
|
|
106
|
+
Применение окончательно: запуск становится **Applied**, а его копия остаётся на диске для разбора,
|
|
107
|
+
пока её не удалит уборка.
|
|
108
|
+
|
|
109
|
+
## Где лежат данные
|
|
110
|
+
|
|
111
|
+
- Копии: `<DSH home>/artel/<profile>/copies/<run id>` — удаляются при Discard и при старте, если
|
|
112
|
+
старше `keepCopiesHours`.
|
|
113
|
+
- Индекс запусков и ленты: `<DSH home>/artel/<profile>/state/runs` — JSON-индекс и по одному JSONL на
|
|
114
|
+
запуск, с ограничением размера.
|
|
115
|
+
- Разговоры агентов: обычные сессии DSH в вашем хранилище сессий.
|
|
116
|
+
|
|
117
|
+
Artel хранит не больше `maxRunsPerSession` запусков на сессию; самые старые убираются из списка.
|
|
118
|
+
|
|
119
|
+
## Если что-то не работает
|
|
120
|
+
|
|
121
|
+
**«Artel cannot see the web server»** — в профиле нет веб-сервера Host, страницу не откуда отдать.
|
|
122
|
+
Плагину нужен desktop/web-профиль.
|
|
123
|
+
|
|
124
|
+
**«This chat session has no project directory yet»** — у сессии нет рабочего каталога. Откройте
|
|
125
|
+
рабочее пространство или начните сессию в каталоге.
|
|
126
|
+
|
|
127
|
+
**«The project is too large to copy»** — пределы копии: 20 000 файлов, 32 МБ на файл, 512 МБ всего.
|
|
128
|
+
Тяжёлые каталоги исключайте через `excludeGlobs`.
|
|
129
|
+
|
|
130
|
+
**«Another run is already in progress in this session»** — на сессию допускается один активный запуск.
|
|
131
|
+
Завершите или остановите его.
|
|
132
|
+
|
|
133
|
+
**Изменений нет** — агенты могли закончить без правок. Прочитайте ленту; если задаче нужен толчок,
|
|
134
|
+
напишите агентам.
|
|
135
|
+
|
|
136
|
+
**Apply отклонён** — в сообщении перечислены файлы, изменённые в проекте во время запуска. Отбросьте
|
|
137
|
+
запуск, дождитесь, пока файл освободится, и запустите заново, либо примените остальные файлы новым
|
|
138
|
+
запуском.
|
package/docs/guide.zh.md
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Artel
|
|
2
|
+
|
|
3
|
+
Artel 在项目的一份隔离副本里执行开发任务:过程中可以看到每一步操作,只有你按下应用按钮,结果才会
|
|
4
|
+
进入你的项目。
|
|
5
|
+
|
|
6
|
+
在会话标题栏点击 **Artel** 按钮,或从右侧栏的引导页打开 **Artel** 标签页。该标签页属于当前聊天
|
|
7
|
+
会话,会话的工作目录就是项目本身。
|
|
8
|
+
|
|
9
|
+
## 启动一次运行
|
|
10
|
+
|
|
11
|
+
1. 选择模式:**Solo** 或 **Swarm**。
|
|
12
|
+
2. 用自己的话描述任务:想要什么结果、在项目里的哪个位置。不需要预先准备文件,智能体会自己查找
|
|
13
|
+
并阅读。
|
|
14
|
+
3. 点击 **Start**(或按 Ctrl+Enter)。
|
|
15
|
+
|
|
16
|
+
随后 Artel 会:
|
|
17
|
+
|
|
18
|
+
1. 把项目复制到项目之外的一个新目录;
|
|
19
|
+
2. 启动一个(Solo)或三个(Swarm)工作目录为该副本的智能体;
|
|
20
|
+
3. 发送任务和一组简短规则:只在副本里改动、绝不碰真实项目、运行与改动匹配的检查、结束时说明
|
|
21
|
+
做了什么。
|
|
22
|
+
|
|
23
|
+
每次运行只创建一份副本,所有智能体共用它。项目本身不会被修改。
|
|
24
|
+
|
|
25
|
+
## Solo
|
|
26
|
+
|
|
27
|
+
一个智能体从头到尾负责这个任务。它的消息、工具调用和文件改动会实时出现在动态里。你随时可以给它
|
|
28
|
+
写消息,消息会进入对话,不会中断当前工作。
|
|
29
|
+
|
|
30
|
+
## Swarm
|
|
31
|
+
|
|
32
|
+
三个智能体在同一份副本里工作,能看到彼此已经写入磁盘的改动。它们还能直接互相发消息:整支队伍共用
|
|
33
|
+
一棵对话树,`send_message({ agent: "<名字>", message: "..." })` 会把消息作为真实的一轮送到队友那里,
|
|
34
|
+
`list_agents()` 列出全队。智能体之间的消息会以 `Orion → Vega` 的形式出现在动态里,不用打开各自的
|
|
35
|
+
对话就能跟上协商过程。
|
|
36
|
+
|
|
37
|
+
**第一轮——分工。** 智能体被要求不做任何编辑。它们阅读项目、商定谁负责哪些文件(边界不清楚时直接
|
|
38
|
+
发消息问队友),并以一行 `OWNERSHIP: src/app/settings/**` 结束本轮。
|
|
39
|
+
|
|
40
|
+
Artel 汇总这些声明,同一路径以第一个声明者为准,并在动态里显示分工结果。若两个智能体声明了相同
|
|
41
|
+
文件,动态里会同时点出两者和最终归属。
|
|
42
|
+
|
|
43
|
+
**之后——并行工作。** Artel 把最终区域发给每个智能体并同时启动。它们会读邻居的进展,进入别人的
|
|
44
|
+
区域前必须先询问负责人;需要区域外改动时,智能体会给负责人发消息,而不是改别人的文件。
|
|
45
|
+
处于空闲的智能体收到队友消息会被唤醒再跑一轮;Artel 会稍等片刻才把运行置为等待,这样两人之间
|
|
46
|
+
简短的往来不会被误判为工作结束。
|
|
47
|
+
|
|
48
|
+
运行期间 Artel 监视每次编辑:当第二个智能体改到另一个智能体已改过的路径时,动态里会出现带两个
|
|
49
|
+
名字的冲突行。分工是公开声明,不是强制锁:冲突可见,但编辑不会被拦截。
|
|
50
|
+
|
|
51
|
+
如果分工轮里没有任何声明,Artel 会再问一次;第二次仍为空时,Artel 按项目顶层目录把工作分给
|
|
52
|
+
各智能体,让运行继续,并在动态里说明。
|
|
53
|
+
|
|
54
|
+
## 运行期间
|
|
55
|
+
|
|
56
|
+
标题显示状态:准备中、分工中、工作中、等待你、已应用、已丢弃、失败、已中断。
|
|
57
|
+
|
|
58
|
+
- **Feed** — 按顺序显示所有消息、工具调用、状态变化、分工和冲突。
|
|
59
|
+
- **Agents** — 每个智能体一行,显示状态和声明的文件。**Open conversation** 会在新聊天里打开该
|
|
60
|
+
智能体的完整对话;这些聊天会以 `Artel · <agent> — <task>` 出现在侧边栏,可以像普通聊天一样归档。
|
|
61
|
+
Swarm 中只有主智能体有自己的聊天:另外两个是它的子智能体,住在这棵对话树里——正因如此三者才能
|
|
62
|
+
互相发消息。它们的往来显示在动态里。
|
|
63
|
+
- **给智能体写消息** — 运行页底部的输入框。Solo 中直接发给唯一智能体;Swarm 中可选择某个智能体
|
|
64
|
+
或 **All agents**(广播)。等待中的运行收到消息后会重新进入工作。
|
|
65
|
+
- **Stop** 中断所有智能体。副本里已完成的工作仍可查看。
|
|
66
|
+
|
|
67
|
+
所有智能体进入空闲后,Artel 停止运行、计算与项目的差异,并把运行置为 **Waiting for you**。
|
|
68
|
+
|
|
69
|
+
## 检查、应用、丢弃
|
|
70
|
+
|
|
71
|
+
**Changes** 列出每个与你的项目不同的文件:`A` 新增、`M` 修改、`D` 删除、`B` 二进制(可应用,但
|
|
72
|
+
不能以文本预览)。每个文件显示新增和删除的行数;展开可查看具体差异。
|
|
73
|
+
|
|
74
|
+
- 取消勾选你不想应用的文件。**Select all** 和 **Select none** 是快捷操作。
|
|
75
|
+
- **Apply N files** 把选中的文件写回你的项目。
|
|
76
|
+
- **Discard** 丢弃副本,项目里不会有任何变化。
|
|
77
|
+
- **New task** 开始新的运行;上一次运行仍留在列表里。
|
|
78
|
+
|
|
79
|
+
写入之前 Artel 会重新读取你的项目:对每个选中的文件检查它是否仍与运行开始时的状态一致。
|
|
80
|
+
|
|
81
|
+
- 一致则应用。
|
|
82
|
+
- 如果你在运行期间改过该文件,Artel 会以 `changed in your project during the run` 拒绝该文件;
|
|
83
|
+
整个应用会被拒绝,让你重新决定。
|
|
84
|
+
- 运行期间在项目里新出现的文件同样会被拒绝。
|
|
85
|
+
|
|
86
|
+
应用是最终操作:运行变为 **Applied**,副本留在磁盘上供检查,直到清理时删除。
|
|
87
|
+
|
|
88
|
+
## 数据位置
|
|
89
|
+
|
|
90
|
+
- 副本:`<DSH home>/artel/<profile>/copies/<run id>`——丢弃时删除;启动时删除超过
|
|
91
|
+
`keepCopiesHours` 的副本。
|
|
92
|
+
- 运行索引和动态:`<DSH home>/artel/<profile>/state/runs`——JSON 索引加每个运行一个 JSONL 动态
|
|
93
|
+
文件,有大小上限。
|
|
94
|
+
- 智能体对话:普通的 DSH 会话,保存在你的会话存储里。
|
|
95
|
+
|
|
96
|
+
每个会话最多保留 `maxRunsPerSession` 次运行,超出后最旧的会从列表中移除。
|
|
97
|
+
|
|
98
|
+
## 常见问题
|
|
99
|
+
|
|
100
|
+
**「Artel cannot see the web server」** —— 当前档案没有 Host Web 服务器,页面无法提供。此插件需要
|
|
101
|
+
桌面/网页档案。
|
|
102
|
+
|
|
103
|
+
**「This chat session has no project directory yet」** —— 会话没有工作目录。先打开工作区,或在
|
|
104
|
+
某个目录下开始会话。
|
|
105
|
+
|
|
106
|
+
**「The project is too large to copy」** —— 副本上限为 20 000 个文件、单文件 32 MB、总计 512 MB。
|
|
107
|
+
用 `excludeGlobs` 排除体积大的目录。
|
|
108
|
+
|
|
109
|
+
**「Another run is already in progress in this session」** —— 每个会话只允许一个活动运行,请先结束
|
|
110
|
+
或停止它。
|
|
111
|
+
|
|
112
|
+
**没有显示改动** —— 智能体可能没有编辑文件就结束了。查看动态;如果需要推动,就给智能体写消息。
|
|
113
|
+
|
|
114
|
+
**应用被拒绝** —— 消息里列出了运行期间在项目中被改动的文件。丢弃本次运行,等文件稳定后重跑,或
|
|
115
|
+
用新的运行应用剩下的文件。
|