Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 49 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,9 @@ It follows the design of Qoder's `Worktree` execution environment, Codex's `code
## How it works

```
Blank conversation: pick "Worktree mode" in the dock dropdown (before the
conversation starts) → optional branch name (auto-prefixed "worktree/")
Blank conversation: the mode selector above the composer follows the configured
default (Settings → Plugins → Task worktree), or pick "Worktree mode" yourself
│ optional branch name (auto-prefixed "worktree/")
│ send the first message → the host injects an instructions context block
▼ the model calls worktree_create on that same turn
│ git worktree add -b worktree/<name> <repo>/.dsh-worktrees/worktree/worktree/<name>
Expand All @@ -53,7 +54,9 @@ conversation starts) → optional branch name (auto-prefixed "worktree/")
session, and the branch-name field is optional (typed names are
auto-prefixed `worktree/`, blank lets the model propose one). The mode
selector disappears once the conversation starts; the session-header badge
takes over the indication.
takes over the indication. Set the default mode once in
**Settings → Plugins → Task worktree** and every new conversation starts
that way (see [Settings](#settings)).
2. **Send your first message** — the host injects one `instructions` context
block (shown as 上下文注入) right before your message: create the worktree
with a `worktree/`-prefixed branch, work inside the checkout path, and at
Expand All @@ -77,6 +80,41 @@ dsh plugin --profile web add dsh-task-worktree

Requires: DeepSeek Harness `0.1.0-rc.7` package line, Git 2.31+, Node 20+.

## Settings

The plugin registers the `task-worktree` settings namespace and ships its own
card in **Settings → Plugins → Plugin configuration**. One setting — the mode a
new conversation starts in — with three choices (they are exactly the three
states there are; a mode plus a separate "remember" switch would describe a
fourth one that means nothing):

| Choice in the panel | Stored in `task-worktree` | Meaning |
| --- | --- | --- |
| Local mode | `defaultMode: local`, `rememberLastChoice: false` | Every new conversation starts in the main workspace. |
| Worktree mode | `defaultMode: worktree`, `rememberLastChoice: false` | Every new conversation is isolated: the host injects the worktree-creation instruction with the first genuine message, no selector trip needed. |
| Remember the last choice | `rememberLastChoice: true` | The mode you picked last above the composer wins; `defaultMode` holds that pick. |

The default is **Local mode**. An installation that never opens the card keeps
behaving exactly as it did before this setting existed: new conversations start
in the main workspace, and a pick in the composer selector applies to its own
conversation only.

The chosen mode applies to conversations that start empty. Picking **Local mode**
in the composer selector is an explicit answer for that conversation: the host
does not auto-arm it, whatever the setting says.

Values live in the ordinary user-settings document, so they can also be set by
hand and take effect live:

```yaml
task-worktree:
defaultMode: worktree
rememberLastChoice: false
```

On a host without the settings service the plugin keeps working with the
composed defaults (local mode), and the card simply does not appear.

## Model tools

| Tool | Purpose |
Expand Down Expand Up @@ -112,10 +150,17 @@ Delivery and cleanup actions (finish / bring-back / remove) stay **human-only**
## Local development

```bash
npm test # smoke test: full lifecycle on a scratch repository
npm test # smoke (worktree lifecycle) + host half + browser prefs
npm run typecheck # client TypeScript
npm run build:client # rebuild client/client.js (tsdown + lightningcss)
npm pack --dry-run # inspect the tarball before publishing
```

The suites: `test/smoke.mjs` (git lifecycle on a scratch repository),
`test/host.mjs` (the real `apply()` on a fake cordis context: settings
namespace, arming policy, injection), `test/prefs.mjs` (the browser preference
store; needs Node 22.6+ and skips itself on older runtimes).

## License

MIT — see [LICENSE](LICENSE)
37 changes: 34 additions & 3 deletions README.zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@
## 工作流

```
空白对话:发送前在下拉框选「Worktree模式」(分支名可选,自动加 worktree/ 前缀)
空白对话:输入框上方的模式选择器跟随「默认模式」设置(设置 → 插件 → 任务 Worktree),
也可以自己选「Worktree模式」(分支名可选,自动加 worktree/ 前缀)
│ 发送第一条消息 → 宿主注入一条「上下文注入」instructions 块
▼ 模型在同一轮调用 worktree_create
│ git worktree add -b worktree/<名称> <仓库>/.dsh-worktrees/worktree/worktree/<名称>
Expand All @@ -44,7 +45,7 @@
(--force 连未提交改动一起删)
```

1. **以 Worktree 模式开始**:空白对话、发送前,dock 选择器显示「分支名:」——选「Worktree模式」即武装会话;分支名可选(输入的会自动加 `worktree/` 前缀,留空由模型拟定)。**对话开始后选择器自动隐藏**,由会话头部徽标接管指示。
1. **以 Worktree 模式开始**:空白对话、发送前,dock 选择器显示「分支名:」——选「Worktree模式」即武装会话;分支名可选(输入的会自动加 `worktree/` 前缀,留空由模型拟定)。**对话开始后选择器自动隐藏**,由会话头部徽标接管指示。在**设置 → 插件 → 任务 Worktree**里把默认模式设为 Worktree,之后每个新对话都直接以该模式开始。
2. **发送第一条消息** → 宿主在你消息前注入一条 `instructions` 上下文块(界面显示为「上下文注入」):创建 `worktree/` 前缀分支、在 checkout 路径内干活、任务结束时**给出可复制的收尾命令**(`bring-back` 或 `remove --force`)。
3. 或跳过模式,直接让 agent 隔离任务:**"用 worktree 隔离干活,任务叫 xxx"** —— 模型调用 `worktree_create`,name 同时作分支名与路径(支持斜杠)。
4. **不注册任何工作区**,侧边栏保持干净;worktree 模式下会话头部显示分支徽标。
Expand All @@ -58,6 +59,30 @@ dsh plugin --profile web add dsh-task-worktree

要求:DeepSeek Harness `0.1.0-rc.7` 包线、Git 2.31+、Node 20+。

## 设置

插件注册 `task-worktree` 设置命名空间,并在**设置 → 插件 → Plugin configuration** 里提供自己的卡片。只有一项设置——新对话的默认模式——三个选项(本来就只有这三种状态;拆成「模式 + 记住上次选择」开关会多出一个毫无意义的组合):

| 面板选项 | 存储在 `task-worktree` | 含义 |
| --- | --- | --- |
| 本地模式 | `defaultMode: local`、`rememberLastChoice: false` | 每个新对话都直接在主工作区开始。 |
| Worktree模式 | `defaultMode: worktree`、`rememberLastChoice: false` | 每个新对话都隔离:宿主在第一条真人消息到达时自动注入创建指引,不必再动手选。 |
| 记住上次选择 | `rememberLastChoice: true` | 以你在输入框上方最后选定的模式为准,`defaultMode` 保存该选择。 |

默认是**本地模式**。从未打开过这张卡片的安装,行为与本设置存在之前完全一致:新对话从主工作区开始,输入框上方的选择只作用于当前对话。

所选模式只作用于「从空白开始」的对话。在输入框上方选**本地模式**即是对该对话的明确表态:无论设置是什么,宿主都不会为它自动武装。

设置存在普通的用户设置文档里,也可以直接手改并即时生效:

```yaml
task-worktree:
defaultMode: worktree
rememberLastChoice: false
```

宿主没有设置服务时,插件继续用组合默认值(本地模式)工作,卡片不会出现。

## 模型工具

| 工具 | 作用 |
Expand Down Expand Up @@ -93,10 +118,16 @@ dsh plugin --profile web add dsh-task-worktree
## 本地开发

```bash
npm test # 冒烟测试:临时仓库全生命周期
npm test # 冒烟(worktree 全生命周期)+ 宿主半 + 浏览器偏好
npm run typecheck # 客户端 TypeScript 类型检查
npm run build:client # 重新构建 client/client.js(tsdown + lightningcss)
npm pack --dry-run # 发布前检查包内容
```

三个测试:`test/smoke.mjs`(临时仓库上的 git 全生命周期)、
`test/host.mjs`(在假 cordis 上下文里跑真实 `apply()`:设置命名空间、武装策略、注入)、
`test/prefs.mjs`(浏览器偏好 store;需 Node 22.6+,更低版本自动跳过)。

## License

MIT — see [LICENSE](LICENSE)
Loading