@iamsamyiok/agents-chat 3.31.0 → 3.33.0

package/README.md

@@ -1,42 +1,94 @@
-# @iamsamyiok/agents-chat (npm 包版)
+# Agents Chat
 
-多智能体群聊工具，通过 npm 全局安装后可使用 `agents-chat` 命令启动。
+一个页面指挥一支 AI 智能体团队：你说需求，管家拆解调度，多个智能体并行干活、互相验收。本地运行、数据不出本机，支持免安装单文件 exe。
 
-> 包名说明：npm 相似名策略禁止发布裸名 `agents-chat`（已存在相似包 `agentschat`），
-> 因此使用官方建议的 scoped 包名 `@iamsamyiok/agents-chat`，安装后的命令仍是 `agents-chat`。
+> 生态位说明：同类开源工具 Vibe Kanban（28k★）已停止维护、Crystal 已转商业化，Agents Chat 是这个赛道持续维护的免费开源选择，并额外提供定时任务、人工审批、卡牌协作等编排能力。
 
-## 安装
+## 30 秒上手
 
 ```bash
-npm install -g @iamsamyiok/agents-chat
+# 安装（Node >= 18；也可直接下载免安装 exe，见下）
+npm install -g agents-chat-cli
+
+# 启动：自动打开浏览器；首次打开有新手引导，点「一键体验示例」即可看完整流程
+agents-chat
 ```
 
-## 前置要求
+没装 AI 内核也能跑：未检测到内核时自动进入演示模式（模拟输出），先体验界面再安装真实内核。
 
-本机需已安装任一 AI 执行内核：
+```bash
+# 推荐内核（任选其一，装完重启 agents-chat 即真实执行）
+npm install -g opencode-ai
+```
 
-- **OpenCode** (推荐): `npm install -g opencode-ai`
-- **Claude Code**: `npm install -g @anthropic-ai/claude-code`
-- **Codex CLI**: `npm install -g @openai/codex`
-- **pi**: `npm install -g @earendil-works/pi-coding-agent`
+## 核心玩法
 
-## 快速开始
+| 能力 | 说明 |
+|---|---|
+| 群聊编排 | 直接输入需求，管家智能体拆解成阶段计划，调度子智能体并行执行，自动验收不合格返工 |
+| 批量任务 | 粘贴一段文本一次导入多条任务（`1. xxx` 每行一条），可拖拽排序、批量执行 |
+| 定时任务 | 行首写时间即定时（`2026-08-18 13:07 生成日报`），到点自动执行，停机错过的启动时补跑，可开机自启 |
+| Git 隔离 | 导入时勾选「Git 隔离执行」：每任务独立 worktree 分支互不污染，完成后逐文件看 diff、一键合并或丢弃 |
+| 人工审批 | 可选在「方案确定后 / 最终交付前」暂停等你点头，超时 10 分钟自动否决 |
+| 完成通知 | 页面在后台弹系统通知；webhook 转发钉钉/飞书/自建中转 |
+| 单聊工作台 | 与 OpenCode 单体多轮续聊；任务链支持 `-` 接续上一会话、`//` 并行执行 |
+| 卡牌协作 | 每个智能体一张卡牌实时直播工作过程，可中途插话纠偏或委派转交 |
 
-```bash
-# 启动服务（后台运行，自动打开浏览器）
-agents-chat
+## 安装方式
 
-# 查看状态
-agents-chat status
+### npm（推荐）
 
-# 停止服务
-agents-chat stop
+```bash
+npm install -g agents-chat-cli
 ```
 
-默认访问 http://localhost:3456
+> 旧包名 `@iamsamyiok/agents-chat` 同步发布，两个包内容一致，命令都叫 `agents-chat`。
+
+### 免安装单文件 exe
+
+从 [Releases](https://github.com/iamsamyiok/agents-chat/releases) 下载对应平台文件（Windows / Linux / macOS Intel / Apple Silicon），双击即用，数据保存在 exe 旁 `.data/` 目录。SHA-256 校验值见 checksums.txt。
+
+- Windows SmartScreen 提示「已保护你的电脑」→「更多信息」→「仍要运行」
+- macOS 首次运行：`xattr -d com.apple.quarantine agents-chat-darwin-*`
+
+## 常用命令
+
+```bash
+agents-chat          # 启动（后台运行，自动开浏览器）
+agents-chat status   # 查看运行状态
+agents-chat stop     # 停止（自动清理执行中的 AI 子进程）
+agents-chat update   # 一键升级到最新版
+agents-chat autostart on   # 开机自启（定时任务无人值守推荐开启）
+```
 
 ## 配置
 
-编辑 `~/.agents-chat/.env` 文件进行配置。
+配置文件位于 `~/.agents-chat/.env`（exe 形态在 `.data/.env`），全部可省略：
+
+```bash
+AGENTS_CHAT_WEBHOOK_URL=      # 任务完成转发地址（钉钉/飞书中转）
+AGENTS_CHAT_PRUNE_DAYS=15     # 历史数据保留天数
+AGENTS_CHAT_TIMEOUT_MS=600000 # 单任务超时
+AGENTS_CHAT_AUTO_APPROVE=0    # 关闭 OpenCode 自动放行
+```
+
+完整说明见仓库 `.env.example` 与页面内「帮助」。
+
+## 支持的执行内核
+
+OpenCode（推荐）/ Claude Code / Codex CLI / pi，页面右上角可切换。多智能体编排深度适配 OpenCode，其余内核以单轮对话方式执行。
+
+## 开发
+
+```bash
+git clone https://github.com/iamsamyiok/agents-chat
+cd agents-chat && npm install
+AGENTS_CHAT_MOCK=1 npm start   # 演示模式开发，无需内核
+npm test                       # 66 个测试用例
+```
+
+零运行时依赖，Node 原生模块实现（HTTP/SSE/存储均为自研轻量层）。
+
+## License
 
-详见原始项目文档。
+MIT

package/app/lib/agent.js

@@ -349,10 +349,13 @@ function runAgent(agent, prompt, onChunk, scope) {
 }
 
 // 智能体工作目录（全局统一）：
-// - 环境变量 AGENTS_CHAT_CWD 优先（卡牌 workspace 等单次执行场景注入）
+// - 任务隔离上下文优先（worktree 任务执行期间注入，见 lib/worktree.js runWithTaskCwd）
+// - 环境变量 AGENTS_CHAT_CWD 次之（卡牌 workspace 等单次执行场景注入）
 // - 配置了有效 globalCwd → 所有智能体共用该目录（文件资料集中在一处）
 // - 否则默认 <数据目录>/workspace/ 共享目录
 function resolveCwd() {
+  const wtCwd = require('./worktree').currentTaskCwd();
+  if (wtCwd) return wtCwd;
   const envCwd = String(process.env.AGENTS_CHAT_CWD || '').trim();
   if (envCwd) {
     try { if (fs.existsSync(envCwd) && fs.statSync(envCwd).isDirectory()) return envCwd; } catch { /* ignore */ }

package/app/lib/oc.js

@@ -193,9 +193,16 @@ function chatSolo(runnerKind, runner, opts, onEvent) {
   const ocSessionId = String(opts.ocSessionId || '');
   // 进程归属 scope：停止编排（stopScope('solo')）只杀编排任务，追加聊天用独立 scope 免受牵连
   const scope = String(opts.scope || 'solo');
-  // 工作区：指定后 Agent 在该目录读写文件（卡牌可选 workspace）
-  const cwd = opts.cwd && fs.existsSync(opts.cwd) && fs.statSync(opts.cwd).isDirectory() ? opts.cwd : '';
-  const cwdEnv = cwd ? { ...process.env, AGENTS_CHAT_CWD: cwd } : process.env;
+  // 工作区：指定后 Agent 在该目录读写文件（卡牌可选 workspace；任务隔离 worktree 经 ALS 注入）
+  const alsCwd = require('./worktree').currentTaskCwd();
+  const cwdInput = opts.cwd || alsCwd;
+  const cwd = cwdInput && fs.existsSync(cwdInput) && fs.statSync(cwdInput).isDirectory() ? cwdInput : '';
+  // 演示模式按调用场景选择 mock 行为（solo-task 会真实写产出文件，供隔离区 diff 演示）
+  const cwdEnv = {
+    ...process.env,
+    ...(cwd ? { AGENTS_CHAT_CWD: cwd } : {}),
+    ...(runnerKind === 'demo' ? { MOCK_BEHAVIOR: String(opts.behavior || 'echo') } : {})
+  };
 
   // ---- 演示模式：mock 子进程 + 快照模拟 ----
   if (runnerKind === 'demo') {

package/app/lib/orchestrator.js

@@ -1076,32 +1076,37 @@ async function runTasks(tasks, butler, subAgents, opts, emit, onMessage, onTaskS
       emit({ type: 'notice', content: '已手动停止，剩余任务保持待执行状态' });
       break;
     }
-    const prompt = `请完成以下任务并给出结果：\n${task.title}${task.notes ? `\n\n补充说明：${task.notes}` : ''}`;
-    // 先建历史背景（不含本任务的起始消息），再写入任务会话首条消息
-    const history = opts.getHistory ? opts.getHistory(task.id) : '';
-    if (onTaskStart) onTaskStart(task);
-    // 该任务产生的全部消息都归入对应任务会话
-    const persistTask = (m) => onMessage({ ...m, taskId: task.id });
-
-    const assigned = opts.resolveAssign ? opts.resolveAssign(task) : null;
-    let r;
-    if (assigned && assigned.id !== butler.id) {
-      // 指派子智能体：独立完成，无管家编排
-      emit({ type: 'task_start', taskId: task.id, title: task.title, agentName: assigned.name });
-      emit({ type: 'notice', content: `本任务由 @${assigned.name} 独立完成（无管家调度）`, taskId: task.id });
-      r = await runMentioned([assigned], prompt, { taskId: task.id, history, scope: opts.scope, isStopped }, emit, persistTask);
-    } else {
-      emit({ type: 'task_start', taskId: task.id, title: task.title, agentName: butler.name });
-      r = await runButler(butler, subAgents, prompt, { taskId: task.id, history, scope: opts.scope, isStopped }, emit, persistTask);
-    }
-    let status = r.ok ? 'done' : 'failed';
-    let resultText = (r.finalText || '').trim() || '执行失败';
-    if (isStopped() && !r.ok) {
-      status = 'pending'; // 手动停止的任务回到待执行，可随时重跑
-      resultText = '已手动停止，可重新执行';
-    }
-    onTaskDone(task.id, { status, result: resultText.slice(0, 10000) });
-    emit({ type: 'task_done', taskId: task.id, status, title: task.title });
+    // 任务隔离 worktree：opts.taskCwd(task) 返回隔离目录（空 = 共享目录），整任务执行期间注入 cwd 上下文
+    const taskCwd = opts.taskCwd ? String(opts.taskCwd(task) || '') : '';
+    if (taskCwd) emit({ type: 'notice', content: `🌿 本任务在 Git 隔离区执行：${taskCwd}`, taskId: task.id });
+    await require('./worktree').runWithTaskCwd(taskCwd, async () => {
+      const prompt = `请完成以下任务并给出结果：\n${task.title}${task.notes ? `\n\n补充说明：${task.notes}` : ''}`;
+      // 先建历史背景（不含本任务的起始消息），再写入任务会话首条消息
+      const history = opts.getHistory ? opts.getHistory(task.id) : '';
+      if (onTaskStart) onTaskStart(task);
+      // 该任务产生的全部消息都归入对应任务会话
+      const persistTask = (m) => onMessage({ ...m, taskId: task.id });
+
+      const assigned = opts.resolveAssign ? opts.resolveAssign(task) : null;
+      let r;
+      if (assigned && assigned.id !== butler.id) {
+        // 指派子智能体：独立完成，无管家编排
+        emit({ type: 'task_start', taskId: task.id, title: task.title, agentName: assigned.name });
+        emit({ type: 'notice', content: `本任务由 @${assigned.name} 独立完成（无管家调度）`, taskId: task.id });
+        r = await runMentioned([assigned], prompt, { taskId: task.id, history, scope: opts.scope, isStopped }, emit, persistTask);
+      } else {
+        emit({ type: 'task_start', taskId: task.id, title: task.title, agentName: butler.name });
+        r = await runButler(butler, subAgents, prompt, { taskId: task.id, history, scope: opts.scope, isStopped }, emit, persistTask);
+      }
+      let status = r.ok ? 'done' : 'failed';
+      let resultText = (r.finalText || '').trim() || '执行失败';
+      if (isStopped() && !r.ok) {
+        status = 'pending'; // 手动停止的任务回到待执行，可随时重跑
+        resultText = '已手动停止，可重新执行';
+      }
+      onTaskDone(task.id, { status, result: resultText.slice(0, 10000) });
+      emit({ type: 'task_done', taskId: task.id, status, title: task.title });
+    });
   }
   emit({ type: 'all_done' });
 }

package/app/lib/store.js

@@ -397,7 +397,7 @@ function importTasks(text, mode, runner, model) {
   for (const t of tasks) { if (t.seq === undefined) t.seq = next++; else next = Math.max(next, t.seq + 1); }
   for (const t of parsed) { t.seq = next++; if (runner === 'solo' && model) t.model = String(model); }
   saveTasks(tasks.concat(parsed));
-  return { added: parsed.length, warnings };
+  return { added: parsed.length, warnings, addedTasks: parsed };
 }
 
 // 拖拽排序：按给定 id 顺序重编 seq（ids 应为全量，未包含的追加在末尾）

package/app/lib/worktree.js

@@ -0,0 +1,192 @@
+// Git worktree 任务隔离：
+// 创建任务时可选在独立 git worktree 中执行（每任务独立分支+目录，互不污染），
+// 完成后可查看改动 diff、合并回主工作目录或整体丢弃。
+// 工作目录（resolveCwd()）不是 git 仓库时功能自动降级（任务照常在共享目录执行）。
+//
+// cwd 传递：AsyncLocalStorage 按任务执行上下文注入（agent.js/oc.js 的 resolveCwd 优先读取），
+// 与并发的聊天请求互不干扰（聊天不在该 async 上下文内）。
+const fs = require('fs');
+const path = require('path');
+const { execFile } = require('child_process');
+const { AsyncLocalStorage } = require('node:async_hooks');
+const store = require('./store');
+
+const WT_ROOT = path.join(store.DATA_DIR, 'worktrees');
+const BRANCH_PREFIX = 'ac/';
+const DIFF_MAX_FILES = 50;          // diff 视图最多展示文件数
+const DIFF_MAX_PATCH = 20 * 1024;   // 单文件 patch 截断
+const DIFF_MAX_TOTAL = 200 * 1024;  // 总 patch 截断
+
+// ---------- 任务级 cwd 注入（AsyncLocalStorage） ----------
+const taskCwdStorage = new AsyncLocalStorage();
+function runWithTaskCwd(cwd, fn) {
+  return cwd ? taskCwdStorage.run({ cwd }, fn) : fn();
+}
+function currentTaskCwd() {
+  const s = taskCwdStorage.getStore();
+  if (!s || !s.cwd) return '';
+  try { if (fs.existsSync(s.cwd) && fs.statSync(s.cwd).isDirectory()) return s.cwd; } catch { /* ignore */ }
+  return '';
+}
+
+// ---------- git 基础 ----------
+function git(args, opts = {}) {
+  return new Promise((resolve) => {
+    execFile('git', args, {
+      cwd: opts.cwd,
+      timeout: opts.timeout || 30000,
+      maxBuffer: 8 * 1024 * 1024,
+      windowsHide: true
+    }, (err, so, se) => {
+      resolve({ code: err ? (err.code === undefined ? 1 : err.code) : 0, so: String(so || ''), se: String(se || '') });
+    });
+  });
+}
+
+// 工作目录是否为可用 git 仓库（有至少一个提交）
+async function isGitRepo(dir) {
+  if (!dir) return false;
+  const r = await git(['rev-parse', '--is-inside-work-tree'], { cwd: dir });
+  if (String(r.so).trim() !== 'true') return false;
+  const h = await git(['rev-parse', 'HEAD'], { cwd: dir });
+  return h.code === 0 && h.so.trim() !== '';
+}
+
+function wtDirOf(taskId) { return path.join(WT_ROOT, String(taskId).replace(/[^\w-]/g, '')); }
+function branchOf(taskId) { return BRANCH_PREFIX + String(taskId).replace(/[^\w-]/g, ''); }
+
+// ---------- 创建 / 清理 ----------
+// 为任务创建隔离 worktree；返回 { dir, branch, base } 或 null（非 git 仓库 / git 不可用 / 目录残留等）
+async function createForTask(taskId) {
+  try {
+    const { resolveCwd } = require('./agent');
+    const baseCwd = resolveCwd();
+    if (!(await isGitRepo(baseCwd))) return null;
+    const head = await git(['rev-parse', 'HEAD'], { cwd: baseCwd });
+    const base = head.so.trim();
+    if (!base) return null;
+    const dir = wtDirOf(taskId);
+    const branch = branchOf(taskId);
+    // 残留清理（上次异常退出可能留下同名 worktree/分支）
+    await git(['worktree', 'remove', '--force', dir], { cwd: baseCwd });
+    await git(['branch', '-D', branch], { cwd: baseCwd });
+    const r = await git(['worktree', 'add', '-b', branch, dir, 'HEAD'], { cwd: baseCwd });
+    if (r.code !== 0) return null;
+    return { dir, branch, base, createdAt: Date.now() };
+  } catch {
+    return null;
+  }
+}
+
+// 从 worktree 目录反查主仓库根目录
+async function findMainRepo(dir) {
+  const g = await git(['rev-parse', '--git-common-dir'], { cwd: dir });
+  if (g.code !== 0) return '';
+  const common = g.so.trim();
+  if (!common) return '';
+  let main = path.resolve(dir, common.replace(/[/\\]\.git$/, ''));
+  try { if (!fs.statSync(main).isDirectory()) return ''; } catch { return ''; }
+  return main;
+}
+
+// 删除 worktree 与对应分支；返回 { ok, error }
+async function removeForTask(worktree, { keepBranch = false } = {}) {
+  if (!worktree || !worktree.dir) return { ok: false, error: '无隔离区信息' };
+  let mainRepo = worktree.mainRepo || '';
+  if (!mainRepo && fs.existsSync(worktree.dir)) mainRepo = await findMainRepo(worktree.dir);
+  const r1 = await git(['worktree', 'remove', '--force', worktree.dir], { cwd: mainRepo || undefined });
+  let r2 = { code: 0 };
+  if (!keepBranch && worktree.branch) r2 = await git(['branch', '-D', worktree.branch], { cwd: mainRepo || undefined });
+  const ok = r1.code === 0; // 分支删除失败不阻塞（可能已被合并删除）
+  return { ok, error: ok ? '' : String((r1.se || r1.so || '').split('\n')[0] || '清理失败').slice(0, 200) };
+}
+
+// ---------- 改动查看 ----------
+// 统计与明细：base（创建时 HEAD）→ 当前工作区（含未提交与未跟踪）
+async function diff(worktree, { withPatch = true } = {}) {
+  if (!worktree || !worktree.dir) throw new Error('无隔离区信息');
+  const dir = worktree.dir;
+  const base = worktree.base || 'HEAD';
+  // add -A 仅为了让未跟踪文件进入 diff（不动分支指针）
+  await git(['add', '-A'], { cwd: dir });
+  const st = await git(['diff', '--numstat', base, '--'], { cwd: dir });
+  const stat = [];
+  for (const line of st.so.split('\n')) {
+    if (!line.trim()) continue;
+    const parts = line.split('\t');
+    if (parts.length < 3) continue;
+    stat.push({ file: parts[2], add: parts[0] === '-' ? null : Number(parts[0]), del: parts[1] === '-' ? null : Number(parts[1]) });
+    if (stat.length >= DIFF_MAX_FILES) break;
+  }
+  const out = { base, branch: worktree.branch, dir, stat, files: [] };
+  if (!withPatch || !stat.length) return out;
+  let total = 0;
+  for (const s of stat) {
+    if (total >= DIFF_MAX_TOTAL) { out.truncated = true; break; }
+    const p = await git(['diff', base, '--', s.file], { cwd: dir });
+    let patch = p.so;
+    if (patch.length > DIFF_MAX_PATCH) { patch = patch.slice(0, DIFF_MAX_PATCH) + '\n…（已截断）'; out.truncated = true; }
+    total += patch.length;
+    out.files.push({ path: s.file, patch });
+  }
+  return out;
+}
+
+// ---------- 合并回主工作目录 ----------
+// worktree 内未提交改动先提交，再在主仓库 merge 该分支
+async function mergeToMain(worktree, title) {
+  if (!worktree || !worktree.dir) throw new Error('无隔离区信息');
+  const dir = worktree.dir;
+  // 找主仓库：worktree 里 git rev-parse --git-common-dir 指向主 .git
+  const mainRepo = await findMainRepo(dir);
+  // 1. worktree 内提交全部改动
+  const hasChange = await git(['status', '--porcelain'], { cwd: dir });
+  if (hasChange.code === 0 && hasChange.so.trim()) {
+    await git(['add', '-A'], { cwd: dir });
+    const cm = await git(['commit', '-m', `agents-chat: ${String(title || '任务').slice(0, 60)}`], { cwd: dir });
+    if (cm.code !== 0) return { ok: false, error: `隔离区提交失败：${String((cm.se || cm.so).split('\n')[0]).slice(0, 200)}` };
+  }
+  // 2. 主仓库合并（--no-edit 保留默认合并信息；无改动则 nothing to commit）
+  const mr = await git(['merge', '--no-edit', worktree.branch], { cwd: mainRepo || undefined });
+  const mOut = String((mr.so || '') + (mr.se || '')).trim();
+  if (/Already up to date|已是最新|Nothing to merge/i.test(mOut)) return { ok: true, already: true };
+  if (mr.code !== 0) {
+    // 合并冲突：回滚合并状态，让用户在隔离区自行处理后再试
+    await git(['merge', '--abort'], { cwd: mainRepo || undefined });
+    return { ok: false, error: `合并冲突（已还原主目录）：${mOut.split('\n')[0].slice(0, 200)}` };
+  }
+  return { ok: true };
+}
+
+// ---------- 数据治理 ----------
+// 清理无主（任务已删）或完结超期的 worktree；liveTasks: 当前任务数组
+async function pruneStale(days, liveTasks) {
+  const stat = { worktrees: 0 };
+  const cutoff = Date.now() - Math.max(1, Number(days) || 15) * 24 * 3600 * 1000;
+  const live = new Map((liveTasks || []).filter(t => t.worktree).map(t => [wtDirOf(t.id), t]));
+  let names = [];
+  try { names = fs.readdirSync(WT_ROOT); } catch { return stat; }
+  for (const name of names) {
+    const dir = path.join(WT_ROOT, name);
+    try {
+      if (!fs.statSync(dir).isDirectory()) continue;
+      const task = live.get(dir);
+      const w = task ? task.worktree : { dir, branch: branchOf(name), mainRepo: '' };
+      let stale = !task;
+      if (task) {
+        const end = Number(task.updatedAt || task.createdAt) || 0;
+        stale = (task.status === 'done' || task.status === 'failed') && end && end < cutoff;
+      }
+      if (!stale) continue;
+      const r = await removeForTask(w);
+      if (r.ok) stat.worktrees++;
+    } catch { /* 单项失败跳过 */ }
+  }
+  return stat;
+}
+
+module.exports = {
+  WT_ROOT, DIFF_MAX_FILES,
+  runWithTaskCwd, currentTaskCwd,
+  isGitRepo, createForTask, removeForTask, diff, mergeToMain, pruneStale
+};

package/app/mock/mock-agent.js

@@ -33,10 +33,15 @@ if (behavior === 'solo-chat') {
     `已处理完成 ${DEMO_TAG}`
   ]);
 } else if (behavior === 'solo-task') {
-  // 单聊任务执行演示：输出任务结果（作为 result 持久化）
+  // 单聊任务执行演示：在工作目录真实写入一个成果文件（供 Git 隔离 diff 演示），再流式输出任务结果
+  try {
+    const fs = require('fs');
+    const path = require('path');
+    fs.writeFileSync(path.join(process.cwd(), 'demo-solo-output.md'), '# 单聊任务演示产出\n\n演示模式下写入工作目录的成果文件。\n');
+  } catch { /* 只读目录时跳过 */ }
   streamOutput([
     `[单聊任务] 开始处理：${prompt.slice(0, 120)}`,
-    `任务完成：产出模拟结果 ${DEMO_TAG}`
+    `任务完成：产出模拟结果（已写入 demo-solo-output.md） ${DEMO_TAG}`
   ]);
 } else if (behavior === 'echo') {
   if (prompt.includes('【委派背景】')) {

package/app/public/index.html

@@ -215,14 +215,14 @@
   .at-tx i { font-style: normal; color: #999; font-size: 11px; display: block; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; max-width: 380px; }
 
   /* ---------- 弹窗 ---------- */
-  #modalMask, #batchMask, #agentsMask, #historyMask, #helpMask, #flowMask, #cardMask, #teamsMask, #memMask { position: fixed; inset: 0; background: rgba(0,0,0,.4); display: none; align-items: center; justify-content: center; z-index: 51; }
+  #modalMask, #batchMask, #agentsMask, #historyMask, #helpMask, #flowMask, #cardMask, #teamsMask, #memMask, #diffMask, #welcomeMask { position: fixed; inset: 0; background: rgba(0,0,0,.4); display: none; align-items: center; justify-content: center; z-index: 51; }
   /* 弹窗出现动画：遮罩淡入（含毛玻璃）+ 内容上浮，全站弹窗统一节奏 */
   div[id$="Mask"] { backdrop-filter: blur(3px); -webkit-backdrop-filter: blur(3px); }
   div[id$="Mask"].show { animation: fade-in .18s ease; }
   .modal, .preview-card { animation: modal-in .24s cubic-bezier(.2,.7,.3,1); }
   @keyframes fade-in { from { opacity: 0; } to { opacity: 1; } }
   @keyframes modal-in { from { opacity: 0; transform: translateY(14px) scale(.985); } to { opacity: 1; transform: none; } }
-  #modalMask.show, #batchMask.show, #agentsMask.show, #historyMask.show, #helpMask.show, #flowMask.show, #cardMask.show, #teamsMask.show, #memMask.show { display: flex; }
+  #modalMask.show, #batchMask.show, #agentsMask.show, #historyMask.show, #helpMask.show, #flowMask.show, #cardMask.show, #teamsMask.show, #memMask.show, #diffMask.show, #welcomeMask.show { display: flex; }
   /* 团队仓库卡片 */
   .team-card { border: 1px solid #e5e7eb; border-radius: 10px; padding: 14px 16px; margin-bottom: 12px; }
   .team-card .tc-head { display: flex; align-items: center; gap: 8px; margin-bottom: 6px; }
@@ -261,6 +261,21 @@
   .flow-detail .fd-title { font-weight: 600; margin-bottom: 6px; }
   .flow-detail .fd-files { color: #7d5ac8; }
   .modal { background: #fff; border-radius: 10px; width: 560px; max-width: 92vw; max-height: 88vh; overflow-y: auto; padding: 20px; }
+  /* 新手引导步骤卡 */
+  .onb-step { flex: 1; background: #f5f7fa; border-radius: 8px; padding: 10px; font-size: 12px; line-height: 1.6; display: flex; flex-direction: column; gap: 4px; }
+  .onb-step .onb-num { width: 22px; height: 22px; border-radius: 50%; background: #10aeff; color: #fff; font-weight: 600; display: flex; align-items: center; justify-content: center; font-size: 13px; }
+  .onb-step span { color: #666; }
+  /* 主会话空状态欢迎卡 */
+  .main-welcome { text-align: center; padding: 44px 18px; color: #666; }
+  .main-welcome h4 { font-size: 16px; margin: 0 0 8px; color: #222; }
+  .main-welcome p { font-size: 13px; line-height: 1.9; margin: 0 0 14px; }
+  .main-welcome .onb-acts { display: flex; gap: 8px; justify-content: center; flex-wrap: wrap; }
+  /* Git 改动视图：行级着色 */
+  .diff-pre { margin: 6px 0 0; padding: 8px; background: #fff; border-radius: 6px; font-size: 12px; line-height: 1.55; overflow-x: auto; white-space: pre; font-family: ui-monospace, Menlo, Consolas, monospace; }
+  .diff-pre .dl { padding: 0 4px; border-radius: 3px; }
+  .diff-pre .dl.add { background: #e6ffec; color: #116329; }
+  .diff-pre .dl.del { background: #ffebe9; color: #82071e; }
+  .diff-pre .dl.hun { color: #0550ae; background: #ddf4ff; }
   .modal h3 { font-size: 15px; margin-bottom: 6px; }
   .modal .tip { font-size: 12px; color: #999; line-height: 1.7; margin-bottom: 10px; }
   .modal textarea { width: 100%; height: 200px; border: 1px solid #ddd; border-radius: 6px; padding: 10px; font-size: 13px; resize: vertical; outline: none; }
@@ -510,6 +525,38 @@
   </div>
 </div>
 
+<!-- 新手引导弹窗 -->
+<div id="welcomeMask">
+  <div class="modal" style="width:600px">
+    <h3>👋 欢迎使用 Agents Chat</h3>
+    <div class="tip">一个页面指挥一支 AI 智能体团队：你说需求，管家拆解调度，多个智能体并行干活、互相验收。三步上手：</div>
+    <div style="display:flex;gap:10px;margin:10px 0">
+      <div class="onb-step"><div class="onb-num">1</div><b>直接聊</b><span>下方输入框发需求，管家自动安排团队分工协作</span></div>
+      <div class="onb-step"><div class="onb-num">2</div><b>批量任务</b><span>「导入任务」一次粘贴多条，可排序、可定时、可 Git 隔离</span></div>
+      <div class="onb-step"><div class="onb-num">3</div><b>无人值守</b><span>定时任务到点自动跑，完成推送通知，错过自动补跑</span></div>
+    </div>
+    <div class="tip" id="onbKernelTip" style="margin-bottom:6px"></div>
+    <div class="modal-actions">
+      <button onclick="closeWelcome(true)">我自己逛逛</button>
+      <button class="primary" onclick="seedDemoTasks()">🚀 一键体验示例（自动导入并执行）</button>
+    </div>
+  </div>
+</div>
+
+<!-- 任务 Git 改动弹窗（隔离区 diff / 合并 / 丢弃） -->
+<div id="diffMask">
+  <div class="modal" style="max-width:860px">
+    <h3 id="diffTitle">🌿 任务改动</h3>
+    <div class="tip" id="diffMeta"></div>
+    <div id="diffBody" style="max-height:52vh;overflow:auto;border:1px solid #d8dee9;border-radius:8px;padding:8px;background:#fafbfc"></div>
+    <div class="modal-actions">
+      <button class="mini-btn danger" onclick="discardTaskDiff()">🗑 丢弃隔离区</button>
+      <button class="primary" onclick="mergeTaskDiff()">合并到主目录</button>
+      <button onclick="closeTaskDiff()">关闭</button>
+    </div>
+  </div>
+</div>
+
 <!-- 导入任务弹窗 -->
 <div id="modalMask">
   <div class="modal">
@@ -523,6 +570,10 @@
       <textarea id="importText" onkeydown="importKeydown(event)"></textarea>
       <div id="importAtMenu"></div>
     </div>
+    <div class="ag-row" style="margin:6px 0 2px;align-items:center;gap:6px">
+      <input type="checkbox" id="importIsolated" style="width:auto">
+      <label for="importIsolated" style="flex:1;cursor:pointer">🌿 Git 隔离执行：每个任务在独立 Git worktree 分支中执行，互不污染；完成后可查看改动、合并回主目录或整体丢弃（统一工作目录需是 Git 仓库）</label>
+    </div>
     <div class="modal-actions">
       <button onclick="closeImport()">取消</button>
       <button class="primary" onclick="doImport()">提取任务</button>
@@ -651,6 +702,8 @@
     <h3>❓ 使用帮助</h3>
     <div id="helpBody"></div>
     <div class="modal-actions">
+      <button class="mini-btn" onclick="closeHelp(); openWelcome()">👋 重新查看新手引导</button>
+      <span style="flex:1"></span>
       <button class="primary" onclick="closeHelp()">关闭</button>
     </div>
   </div>
@@ -696,7 +749,7 @@
 </div>
 
 <script>
-const PAGE_VERSION = '3.31.0'; // 与服务端 /api/health.version 互检，不一致说明页面缓存过期
+const PAGE_VERSION = '3.33.0'; // 与服务端 /api/health.version 互检，不一致说明页面缓存过期
 const AV_COLORS = ['#5b8def','#07c160','#fa9d3b','#10aeff','#8a6fe8','#fa5151','#e8a33d','#3aa7a3'];
 const PHASE_LABEL = { plan: '调度规划', work: '执行', review: '验收', report: '汇总', talk: '圆桌发言', task: '任务执行' };
 // 职业图标库（智能体配置可选）
@@ -815,6 +868,15 @@ async function init() {
   renderUpdateInfo(health);
   refreshNotifyBtn();
 
+  // 新手引导：从未使用过（主会话无消息、无任务、本机未看过引导）→ 自动弹欢迎
+  try {
+    if (!localStorage.getItem(ONBOARD_KEY)
+      && getSess('').length === 0
+      && tasks.filter(t => t.kind !== 'scheduled').length === 0) {
+      openWelcome();
+    }
+  } catch { /* localStorage 不可用时跳过 */ }
+
   input.addEventListener('input', handleAtInput);
   input.addEventListener('blur', () => setTimeout(hideAt, 150));
   // 消息区滚动：贴底时收起「新消息」悬浮按钮
@@ -1402,6 +1464,15 @@ function linkBadge(t) {
     ? '<span style="color:#8a6fe8;font-size:11px;margin-right:4px" title="在上一任务的会话中继续执行（同进程续聊）">↪ 续聊</span>'
     : '<span style="color:#0a742e;font-size:11px;margin-right:4px" title="与相邻并行任务同时执行（独立进程）">⚡ 并行</span>';
 }
+// Git 隔离徽标与改动按钮
+function wtBadge(t) {
+  return t.worktree ? '<span style="color:#0a742e;font-size:11px;margin-right:4px" title="Git 隔离执行（独立 worktree 分支）">🌿</span>' : '';
+}
+function wtBtn(t) {
+  return (t.worktree && (t.status === 'done' || t.status === 'failed'))
+    ? `<button class="mini-btn" title="查看本任务在隔离区的 Git 改动（可合并/丢弃）" onclick="event.stopPropagation();openTaskDiff('${escAttr(t.id)}')">改动</button>`
+    : '';
+}
 function renderTasks() {
   const el = document.getElementById('taskList');
   const badge = document.getElementById('pendingBadge');
@@ -1424,10 +1495,11 @@ function renderTasks() {
           <div class="task-avatar st-${t.status === 'pending' ? 'scheduled' : t.status}">${icon}</div>
           <div class="task-main">
             <div class="task-title">${esc(t.title)}</div>
-            <div class="task-sub"><span>${linkBadge(t)}${st}</span></div>
+            <div class="task-sub"><span>${linkBadge(t)}${wtBadge(t)}${st}</span></div>
           </div>
           ${t.status === 'pending' ? `<button class="mini-btn" title="不再等到点，立即执行" onclick="event.stopPropagation();runSchedNow('${escAttr(t.id)}')">立即执行</button>` : ''}
           ${t.status === 'failed' ? `<button class="mini-btn" title="重新执行" onclick="event.stopPropagation();runSchedNow('${escAttr(t.id)}')">重跑</button>` : ''}
+          ${wtBtn(t)}
           <button class="mini-btn danger" title="删除任务及其会话" onclick="event.stopPropagation();delTask('${escAttr(t.id)}')">✕</button>
         </div>`;
       }).join('') : '<div class="task-empty">暂无定时任务<br>点上方「导入任务」→「定时任务」标签添加</div>';
@@ -1443,12 +1515,13 @@ function renderTasks() {
           <div class="task-avatar st-${t.status}">${icon}</div>
           <div class="task-main">
             <div class="task-title">${esc(t.title)}</div>
-            <div class="task-sub"><span>${linkBadge(t)}${statusText(t.status)}</span><span>${fmtTime(t.createdAt)}</span></div>
+            <div class="task-sub"><span>${linkBadge(t)}${wtBadge(t)}${statusText(t.status)}</span><span>${fmtTime(t.createdAt)}</span></div>
           </div>
           ${t.status === 'pending' || t.status === 'failed' ? `<button class="mini-btn" onclick="event.stopPropagation();runTask('${escAttr(t.id)}')">执行</button>` : ''}
+          ${wtBtn(t)}
           <button class="mini-btn danger" title="删除任务及其会话" onclick="event.stopPropagation();delTask('${escAttr(t.id)}')">✕</button>
         </div>`;
-      }).join('') : '<div class="task-empty">暂无顺序任务<br>点上方「导入任务」添加<br>（单聊任务由 OpenCode 单体执行）</div>';
+      }).join('') : '<div class="task-empty">暂无顺序任务<br>点上方「导入任务」添加<br>（单聊任务由 OpenCode 单体执行）<br><button class="mini-btn" style="margin-top:6px" onclick="seedDemoTasks()">🚀 试试示例任务</button></div>';
     }
     el.innerHTML = `<div class="list-sep">${taskView === 'sched' ? '定时任务（单聊 · 到点自动执行）' : '单聊任务（点击查看会话，可拖拽排序）'}</div>` + tasksHtml;
     return;
@@ -1475,10 +1548,11 @@ function renderTasks() {
           <div class="task-avatar st-${t.status === 'pending' ? 'scheduled' : t.status}">${icon}</div>
           <div class="task-main">
             <div class="task-title">${esc(t.title)}</div>
-            <div class="task-sub"><span>${st}${assign}</span></div>
+            <div class="task-sub"><span>${wtBadge(t)}${st}${assign}</span></div>
           </div>
           ${t.status === 'pending' ? `<button class="mini-btn" title="不再等到点，立即执行" onclick="event.stopPropagation();runSchedNow('${escAttr(t.id)}')">立即执行</button>` : ''}
           ${t.status === 'failed' ? `<button class="mini-btn" title="重新执行" onclick="event.stopPropagation();runSchedNow('${escAttr(t.id)}')">重跑</button>` : ''}
+          ${wtBtn(t)}
           <button class="mini-btn danger" title="删除任务及其会话" onclick="event.stopPropagation();delTask('${escAttr(t.id)}')">✕</button>
         </div>`;
       }).join('');
@@ -1495,7 +1569,7 @@ function renderTasks() {
 
   let tasksHtml;
   if (vis.length === 0) {
-    tasksHtml = '<div class="task-empty">暂无顺序任务<br>点上方「导入任务」添加<br>定时任务请切到上方「⏰ 定时任务」</div>';
+    tasksHtml = '<div class="task-empty">暂无顺序任务<br>点上方「导入任务」添加<br>定时任务请切到上方「⏰ 定时任务」<br><button class="mini-btn" style="margin-top:6px" onclick="seedDemoTasks()">🚀 试试示例任务</button></div>';
   } else {
     tasksHtml = vis.map((t) => {
       const icon = t.status === 'done' ? '✓' : t.status === 'failed' ? '!' : t.status === 'running' ? '▶' : '•';
@@ -1505,9 +1579,10 @@ function renderTasks() {
         <div class="task-avatar st-${t.status}">${icon}</div>
         <div class="task-main">
           <div class="task-title">${esc(t.title)}</div>
-          <div class="task-sub"><span>${statusText(t.status)}${assign}</span><span>${fmtTime(t.createdAt)}</span></div>
+          <div class="task-sub"><span>${wtBadge(t)}${statusText(t.status)}${assign}</span><span>${fmtTime(t.createdAt)}</span></div>
         </div>
         ${t.status === 'pending' || t.status === 'failed' ? `<button class="mini-btn" onclick="event.stopPropagation();runTask('${escAttr(t.id)}')">执行</button>` : ''}
+        ${wtBtn(t)}
         <button class="mini-btn danger" title="删除任务及其会话" onclick="event.stopPropagation();delTask('${escAttr(t.id)}')">✕</button>
       </div>`;
     }).join('');
@@ -1937,6 +2012,18 @@ function renderMessages() {
     box.appendChild(node);
     finalizeMsgLinks(all[i]); // 定稿消息中的 .md 路径变成可点击预览链接
   }
+  // 主会话空状态：欢迎卡 + 快捷动作（新用户零点击成本看到入口）
+  if (curTaskId === '' && chatMode === 'group' && all.length === 0) {
+    box.innerHTML = `<div class="main-welcome">
+      <h4>👋 今天想让团队做点什么？</h4>
+      <p>直接在下方输入需求，管家会拆解调度智能体团队协作完成；<br>也可以先导入一批任务批量执行，或点「试试示例」看完整流程。</p>
+      <div class="onb-acts">
+        <button class="primary" onclick="seedDemoTasks()">🚀 试试示例</button>
+        <button onclick="openImport()">📥 导入任务</button>
+        <button onclick="openHelp()">📖 查看帮助</button>
+      </div>
+    </div>`;
+  }
   scrollBottom();
   requestAnimationFrame(() => requestAnimationFrame(() => box.classList.remove('bulk')));
   const jb = document.getElementById('jumpBtn'); if (jb) jb.style.display = 'none';
@@ -2571,11 +2658,17 @@ async function doImport() {
   // 单聊导入时记录当前所选模型，定时触发时用它执行（页面关闭也不丢）
   const data = await api('/api/tasks/import', {
     method: 'POST', headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ text, mode: importMode, runner: chatMode === 'solo' ? 'solo' : '', model: chatMode === 'solo' ? (curOcModel || '') : '' })
+    body: JSON.stringify({
+      text, mode: importMode, runner: chatMode === 'solo' ? 'solo' : '', model: chatMode === 'solo' ? (curOcModel || '') : '',
+      isolated: !!(document.getElementById('importIsolated') || {}).checked
+    })
   });
   if (data.success) {
     tasks = data.tasks || [];
     renderSidebar();
+    if (data.isolated > 0) {
+      (chatMode === 'solo' ? addSoloSys : addSys)(`🌿 ${data.isolated} 个任务将在 Git 隔离区执行（独立分支，互不污染）`);
+    }
     if (chatMode === 'solo') {
       addSoloSys(importMode === 'scheduled'
         ? `已添加 ${data.added} 个单聊定时任务（到点由 OpenCode 自动执行）`
@@ -2591,6 +2684,100 @@ async function doImport() {
   } else toast(data.error || '导入失败');
 }
 
+// ---------- Git 隔离区改动查看 / 合并 / 丢弃 ----------
+let diffTask = null; // 当前弹窗对应的任务
+function escDiffLine(l) {
+  const e = esc(l);
+  if (l.startsWith('+')) return `<div class="dl add">${e}</div>`;
+  if (l.startsWith('-')) return `<div class="dl del">${e}</div>`;
+  if (l.startsWith('@@')) return `<div class="dl hun">${e}</div>`;
+  return `<div class="dl">${e}</div>`;
+}
+async function openTaskDiff(id) {
+  const t = tasks.find(x => x.id === id);
+  if (!t) return;
+  document.getElementById('diffTitle').textContent = `🌿 改动：${t.title.slice(0, 30)}`;
+  document.getElementById('diffMeta').textContent = '加载中…';
+  document.getElementById('diffBody').innerHTML = '';
+  document.getElementById('diffMask').classList.add('show');
+  diffTask = t;
+  const data = await api('/api/tasks/diff?id=' + encodeURIComponent(id));
+  if (!data.success) { document.getElementById('diffMeta').textContent = data.error || '加载失败'; return; }
+  const d = data.diff;
+  const addAll = d.stat.reduce((a, s) => a + (s.add || 0), 0);
+  const delAll = d.stat.reduce((a, s) => a + (s.del || 0), 0);
+  const merged = t.mergedAt ? '（已合并过）' : '';
+  document.getElementById('diffMeta').innerHTML =
+    `分支 ${esc(d.branch)}${merged} · ${d.stat.length} 个文件 · <span style="color:#0a742e">+${addAll}</span> / <span style="color:#c0392b">-${delAll}</span>${d.truncated ? '（内容过长已截断）' : ''}`;
+  if (!d.stat.length) {
+    document.getElementById('diffBody').innerHTML = '<div style="color:#666;padding:12px">隔离区没有任何改动</div>';
+    return;
+  }
+  const byFile = Object.fromEntries((d.files || []).map(f => [f.path, f.patch]));
+  document.getElementById('diffBody').innerHTML = d.stat.map(s => `
+    <details ${d.stat.length <= 5 ? 'open' : ''} style="margin-bottom:8px">
+      <summary style="cursor:pointer;font-size:13px;padding:4px 6px;background:#eef1f5;border-radius:6px">
+        <b>${esc(s.file)}</b>
+        <span style="color:#0a742e">+${s.add == null ? '二进制' : s.add}</span>
+        <span style="color:#c0392b">-${s.del == null ? '' : s.del}</span>
+      </summary>
+      <pre class="diff-pre">${(byFile[s.file] || '').split('\n').map(escDiffLine).join('')}</pre>
+    </details>`).join('');
+}
+function closeTaskDiff() {
+  document.getElementById('diffMask').classList.remove('show');
+  diffTask = null;
+}
+async function mergeTaskDiff() {
+  if (!diffTask) return;
+  if (!confirm(`把「${diffTask.title.slice(0, 30)}」的隔离区改动合并到主工作目录？\n（未提交改动会先自动提交到隔离分支，再在主目录执行 git merge）`)) return;
+  const data = await api('/api/tasks/merge', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id: diffTask.id }) });
+  if (data.success) { toast(data.already ? '隔离区改动此前已合并' : '已合并到主工作目录'); closeTaskDiff(); loadTasks(); }
+  else toast(data.error || '合并失败');
+}
+async function discardTaskDiff() {
+  if (!diffTask) return;
+  if (!confirm(`丢弃「${diffTask.title.slice(0, 30)}」的隔离区？\n（删除独立 worktree 与分支，其中未合并的改动将永久丢失；任务本身保留，可重新执行）`)) return;
+  const data = await api('/api/tasks/discard', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id: diffTask.id }) });
+  if (data.success) { toast('隔离区已丢弃'); closeTaskDiff(); loadTasks(); }
+  else toast(data.error || '丢弃失败');
+}
+
+// ---------- 新手引导与一键示例 ----------
+const ONBOARD_KEY = 'acOnboarded';
+function closeWelcome(markSeen) {
+  document.getElementById('welcomeMask').classList.remove('show');
+  if (markSeen) try { localStorage.setItem(ONBOARD_KEY, '1'); } catch { /* 隐私模式忽略 */ }
+}
+function openWelcome() {
+  const tip = document.getElementById('onbKernelTip');
+  const rs = runnerState || {};
+  if (rs.kind === 'demo') tip.innerHTML = '🧪 当前为<b>演示模式</b>（模拟输出，无需任何配置即可体验完整流程）；安装 OpenCode 后即为真实执行';
+  else if (rs.kind === 'missing') tip.innerHTML = '⚠ 未检测到执行内核，真实任务前需安装：npm install -g opencode-ai（详见帮助）';
+  else tip.innerHTML = `✅ 运行内核就绪：${rs.label || 'OpenCode'}`;
+  document.getElementById('welcomeMask').classList.add('show');
+}
+// 一键体验：自动导入一组示例任务并立即执行（群聊=管家编排双任务；单聊=OpenCode 续聊链）
+async function seedDemoTasks() {
+  closeWelcome(true);
+  const solo = chatMode === 'solo';
+  const text = solo
+    ? '1. 用一句话介绍你能帮我做什么，再列出你最擅长的三类任务\n2. -继续：针对上面三类任务，各举一个具体例子说明你会怎么完成'
+    : '1. 盘点当前工作目录的文件与子目录结构，输出一份简明的目录说明\n2. 根据上一任务的盘点结果，为这个项目生成一份 README.md 草稿';
+  const data = await api('/api/tasks/import', {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ text, mode: 'sequential', runner: solo ? 'solo' : '' })
+  });
+  if (!data.success) { toast(data.error || '示例导入失败'); return; }
+  tasks = data.tasks || [];
+  renderSidebar();
+  addSys(`🚀 已导入 ${data.added} 个示例任务，开始体验（随时可在任务列表删除）`);
+  const ids = tasks.filter(t => t.runner === (solo ? 'solo' : '') && t.kind === 'sequential' && t.status === 'pending').map(t => t.id);
+  if (!ids.length) { toast('示例任务已导入，请手动执行'); return; }
+  if (solo) await soloExecTasks(ids.slice(0, 2));
+  else await runTask(ids[0]);
+}
+
 async function clearTasks() {
   if (!confirm('确定清空全部任务？（任务会话的对话记录也会从列表移除）')) return;
   await api('/api/tasks/clear', { method: 'POST' });
@@ -3513,6 +3700,13 @@ function openHelp() {
       <li>全部页面关闭且无任务执行/审批等待时，后台服务空闲约 1 分钟自动退出（需要定时任务到点执行请保持页面打开，或运行 <code>agents-chat autostart on</code> 开机自启；<code>.env AGENTS_CHAT_AUTOSTOP=0</code> 可关闭），需要时重新运行 start 即可</li>
     </ul>
   </div>
+  <div class="help-sec"><h4>🌿 Git 隔离执行（worktree）</h4>
+    <ul>
+      <li>导入任务时勾选「Git 隔离执行」：每个任务在<b>独立 Git worktree 分支</b>中执行，多任务并行互不污染，失败的尝试可整体丢弃（统一工作目录需是 Git 仓库且至少有一个提交）</li>
+      <li>任务完成后任务条出现「改动」按钮：<b>逐文件查看 diff</b>（新增/删除/修改着色显示），确认后「合并到主目录」（自动提交隔离分支并 git merge，冲突会还原主目录并提示）或「丢弃隔离区」（删除该 worktree 与分支）</li>
+      <li>隔离区随数据维护自动治理：任务删除或完结超 15 天的 worktree 自动清理</li>
+    </ul>
+  </div>
   <div class="help-sec"><h4>🔔 完成通知</h4>
     <ul>
       <li>顶栏「🔔 通知」开启后（需浏览器授权），页面在后台时任务/卡牌完成会弹<b>系统级通知</b>，人不在电脑前也不错过</li>

package/app/server.js

@@ -30,9 +30,14 @@ const { spawn } = require('child_process');
   } catch { /* 日志系统自身失败：静默，服务照常 */ }
 })();
 
-// 首先加载 .env（根目录，行为开关配置）
+// 首先加载 .env（行为开关配置）：
+// 1) 数据目录 .env（npm/exe 形态用户配置处：~/.agents-chat/.env 或 exe 旁 .data/.env，优先）
+// 2) 程序根目录 .env（源码开发形态）
 const { loadEnv } = require('./lib/env');
 const ROOT_DIR = path.join(__dirname, '..');
+const ENV_DATA_DIR = process.env.AGENTS_CHAT_DATA
+  || (process.env.AGENTS_CHAT_STANDALONE === '1' && process.execPath ? path.join(path.dirname(process.execPath), '.data') : '');
+loadEnv(path.join(ENV_DATA_DIR || path.join(ROOT_DIR, '.data'), '.env'));
 loadEnv(path.join(ROOT_DIR, '.env'));
 
 // ---------- 日志 tee：控制台输出同时写入 .data/server.log ----------
@@ -629,8 +634,18 @@ const server = http.createServer(async (req, res) => {
     }
     const mode = body.mode === 'scheduled' ? 'scheduled' : 'sequential';
     const runner = body.runner === 'solo' ? 'solo' : '';
-    const { added, warnings } = store.importTasks(body.text, mode, runner, body.model);
-    json(res, 200, { success: true, added, warnings, mode, runner, tasks: store.getTasks() });
+    const { added, warnings, addedTasks } = store.importTasks(body.text, mode, runner, body.model);
+    // Git 隔离执行：为每个新任务创建独立 worktree（工作目录是 git 仓库时生效）
+    let isolated = 0;
+    if (body.isolated && Array.isArray(addedTasks)) {
+      const worktree = require('./lib/worktree');
+      for (const t of addedTasks) {
+        const wt = await worktree.createForTask(t.id);
+        if (wt) { store.updateTask(t.id, { worktree: wt }); isolated++; }
+      }
+      if (!isolated) warnings.push('统一工作目录不是 Git 仓库（或没有任何提交），任务将按共享目录执行');
+    }
+    json(res, 200, { success: true, added, warnings, mode, runner, isolated, tasks: store.getTasks() });
     return;
   }
 
@@ -647,14 +662,62 @@ const server = http.createServer(async (req, res) => {
   }
 
   if (p === '/api/tasks/delete' && req.method === 'POST') {
-    // 删除任务及其会话消息
+    // 删除任务及其会话消息；Git 隔离区一并清理
     const body = await readBody(req);
     if (!body.id) { json(res, 400, { success: false, error: 'id 不能为空' }); return; }
+    const t = store.getTasks().find(x => x.id === String(body.id));
+    if (t && t.worktree) {
+      require('./lib/worktree').removeForTask(t.worktree).catch(() => {});
+    }
     store.deleteTask(String(body.id));
     json(res, 200, { success: true, tasks: store.getTasks() });
     return;
   }
 
+  // ---------- Git 隔离区：改动查看 / 合并 / 丢弃 ----------
+  if (p === '/api/tasks/diff' && req.method === 'GET') {
+    const t = store.getTasks().find(x => x.id === String(parsed.query.id || ''));
+    if (!t || !t.worktree) { json(res, 404, { success: false, error: '任务不存在或无隔离区' }); return; }
+    try {
+      const d = await require('./lib/worktree').diff(t.worktree, { withPatch: true });
+      json(res, 200, { success: true, task: { id: t.id, title: t.title, status: t.status }, diff: d });
+    } catch (e) {
+      json(res, 500, { success: false, error: String((e && e.message) || e) });
+    }
+    return;
+  }
+
+  if (p === '/api/tasks/merge' && req.method === 'POST') {
+    const body = await readBody(req);
+    const t = store.getTasks().find(x => x.id === String(body.id || ''));
+    if (!t || !t.worktree) { json(res, 404, { success: false, error: '任务不存在或无隔离区' }); return; }
+    if (runLocks.tasks) { json(res, 409, { success: false, error: '任务批次执行中，暂不能合并' }); return; }
+    try {
+      const r = await require('./lib/worktree').mergeToMain(t.worktree, t.title);
+      if (r.ok) store.updateTask(t.id, { mergedAt: Date.now() });
+      json(res, 200, { success: r.ok, already: !!r.already, error: r.error || '' });
+    } catch (e) {
+      json(res, 500, { success: false, error: String((e && e.message) || e) });
+    }
+    return;
+  }
+
+  if (p === '/api/tasks/discard' && req.method === 'POST') {
+    // 丢弃隔离区：删除 worktree 与分支，任务保留（可重跑重建）
+    const body = await readBody(req);
+    const t = store.getTasks().find(x => x.id === String(body.id || ''));
+    if (!t || !t.worktree) { json(res, 404, { success: false, error: '任务不存在或无隔离区' }); return; }
+    if (runLocks.tasks) { json(res, 409, { success: false, error: '任务批次执行中，暂不能丢弃' }); return; }
+    try {
+      const r = await require('./lib/worktree').removeForTask(t.worktree);
+      if (r.ok) store.updateTask(t.id, { worktree: null });
+      json(res, 200, { success: r.ok, error: r.error || '' });
+    } catch (e) {
+      json(res, 500, { success: false, error: String((e && e.message) || e) });
+    }
+    return;
+  }
+
   if (p === '/api/tasks/run' && req.method === 'POST') {
     // 顺序执行任务：scope='solo' 时由 OpenCode 单体逐个执行（每个任务独立一次性对话）；
     // 默认（群聊）每个任务 = 独立会话 + 一次完整管家调度
@@ -1344,7 +1407,7 @@ async function executeTaskBatch(selected, send, myToken) {
   const persist = (m) => store.addMessage({ ...m, timestamp: new Date().toISOString() });
   await runTasks(
     selected, butler, subAgents,
-    { getHistory: (tid) => buildHistoryText(tid), resolveAssign, scope: 'tasks', isStopped: () => stopTokens.tasks !== myToken, approval: approvalSetting(), requestApproval: makeRequestApproval() },
+    { getHistory: (tid) => buildHistoryText(tid), resolveAssign, scope: 'tasks', isStopped: () => stopTokens.tasks !== myToken, approval: approvalSetting(), requestApproval: makeRequestApproval(), taskCwd: (task) => (task.worktree && task.worktree.dir) || '' },
     send, persist,
     // 任务会话首条消息：任务本身（用户视角）
     (task) => {
@@ -1397,7 +1460,11 @@ async function executeSoloTaskBatch(selected, send, myToken) {
     const order = [];
     let doneError = '';
     let sesId = ocSessionId || '';
-    await new Promise((resolve) => {
+    // 任务隔离 worktree：整任务执行期间注入 cwd 上下文（ALS，与并发请求互不干扰）
+    const worktreeMod = require('./lib/worktree');
+    const wtDir = task.worktree && task.worktree.dir ? task.worktree.dir : '';
+    if (wtDir) send({ type: 'notice', content: `🌿 本任务在 Git 隔离区执行：${wtDir}`, taskId: task.id });
+    await worktreeMod.runWithTaskCwd(wtDir, () => new Promise((resolve) => {
       const kind = runner.kind === 'demo' ? 'demo' : (runner.kind === 'opencode' ? 'opencode' : 'fallback');
       oc.chatSolo(kind, runner, {
         prompt: cont
@@ -1422,7 +1489,7 @@ async function executeSoloTaskBatch(selected, send, myToken) {
           resolve();
         }
       });
-    });
+    }));
 
     const finalText = order.map(id => texts.get(id)).join('\n\n').trim();
     if (finalText) {
@@ -1503,6 +1570,10 @@ const PRUNE_DAYS = Number(process.env.AGENTS_CHAT_PRUNE_DAYS) > 0 ? Number(proce
 function pruneOldDataQuiet() {
   try {
     const stat = store.pruneOldData(PRUNE_DAYS);
+    // Git 隔离区同步治理：无主（任务已删）或完结超期的 worktree 一并清理
+    require('./lib/worktree').pruneStale(PRUNE_DAYS, store.getTasks())
+      .then(ws => { if (ws.worktrees) { stat.worktrees = ws.worktrees; console.log('[maintenance] 清理过期 Git 隔离区:', ws.worktrees); } })
+      .catch(() => {});
     const touched = Object.values(stat).reduce((a, b) => a + b, 0);
     if (touched) console.log(`[maintenance] 自动清理超 ${PRUNE_DAYS} 天的历史数据：`, JSON.stringify(stat));
   } catch (e) { console.error('[maintenance] 自动清理失败:', e && (e.message || e)); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamsamyiok/agents-chat",
-  "version": "3.31.0",
+  "version": "3.33.0",
   "description": "多智能体群聊工具 - 支持 OpenCode/Claude Code/Codex/pi 内核，微信风格聊天界面",
   "main": "lib/start.js",
   "bin": {

package/scripts/build-exe.js

@@ -76,7 +76,9 @@ if (failed.length) {
 const { createHash } = require('crypto');
 const lines = [];
 for (const f of fs.readdirSync(DIST).sort()) {
+  if (!/^agents-chat-/.test(f)) continue; // 只计算产物文件（跳过 .data 等目录与旧清单）
   const fp = path.join(DIST, f);
+  try { if (!fs.statSync(fp).isFile()) continue; } catch { continue; }
   const h = createHash('sha256').update(fs.readFileSync(fp)).digest('hex');
   lines.push(`${h}  ${f}`);
 }