@iamsamyiok/agents-chat 3.32.0 → 3.34.0

package/.env.example

@@ -24,3 +24,5 @@
 # AGENTS_CHAT_OPENCODE_CMD=
 # 单任务超时毫秒（默认 10 分钟）
 # AGENTS_CHAT_TIMEOUT_MS=600000
+# AI 组队生成超时（毫秒，默认 120000；真实内核生成整队提示词耗时较长）
+# AGENTS_CHAT_SUGGEST_TIMEOUT_MS=120000

package/README.md

@@ -1,42 +1,95 @@
-# @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`
+## 核心玩法
 
-## 快速开始
+| 能力 | 说明 |
+|---|---|
+| 群聊编排 | 直接输入需求，管家智能体拆解成阶段计划，调度子智能体并行执行，自动验收不合格返工 |
+| AI 组队 | 一句话描述需求，执行内核自动生成整套智能体团队（名称/图标/技能/提示词），预览后合并或替换应用 |
+| 批量任务 | 粘贴一段文本一次导入多条任务（`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                       # 81 个测试用例
+```
+
+零运行时依赖，Node 原生模块实现（HTTP/SSE/存储均为自研轻量层）。
+
+## License
 
-详见原始项目文档。
+MIT

package/app/lib/teamgen.js

@@ -0,0 +1,138 @@
+// AI 智能组队：由执行内核根据用户需求生成子智能体团队配置
+// 纯函数模块（buildPrompt/extractTeamJSON/cleanSuggestedTeam）可独立单测；
+// suggestTeam 注入 runAgentFn 便于测试内核交互链路
+const agentMod = require('./agent');
+
+const LIMITS = { name: 20, icon: 8, desc: 100, systemPrompt: 8000 };
+const TEAM_MIN = 2;
+const TEAM_MAX = 6;
+const REQ_MAX = 2000;
+const SUGGEST_TIMEOUT_MS = Number(process.env.AGENTS_CHAT_SUGGEST_TIMEOUT_MS) > 0
+  ? Number(process.env.AGENTS_CHAT_SUGGEST_TIMEOUT_MS)
+  : 120000; // 真实内核生成整队提示词输出量大，60s 偏紧；.env 可覆盖
+
+// 结构化生成提示词：要求内核输出纯 JSON 数组（容错解析见 extractTeamJSON）
+function buildPrompt(requirements, existingNames) {
+  const avoid = (Array.isArray(existingNames) ? existingNames : [])
+    .map(n => String(n || '').trim()).filter(Boolean);
+  return [
+    '你是一位资深多智能体系统团队设计师。请根据用户需求，设计一支协作完成该需求的智能体团队。',
+    '',
+    '【用户需求】',
+    String(requirements || '').trim(),
+    '',
+    '【输出要求】只输出一个 JSON 数组，不要输出任何其他文字、解释或 markdown 代码块标记。数组包含 2 到 6 个对象，每个对象字段：',
+    '- name：智能体名称，简短（不超过 8 个字），团队内不得重名',
+    '- icon：单个 emoji 图标',
+    '- desc：一句话技能说明（不超过 50 字），明确该智能体的能力边界，供调度者据此分派任务',
+    '- systemPrompt：自定义提示词，包含角色定位、专业技能与输出要求，100 到 300 字，具体可执行',
+    '',
+    avoid.length ? `【命名避让】以下名称已被现有智能体占用，生成的 name 不得与之重复：${avoid.join('、')}` : '',
+    '',
+    '【设计原则】',
+    '1. 按需求拆解出真正需要的分工，每个智能体职责单一且清晰，避免出现职责重叠的成员',
+    '2. 语言与用户需求语言一致（用户用中文则全部用中文）',
+    '3. systemPrompt 要具体可执行，写清楚该角色拿到任务后应该怎么做、输出什么格式的成果',
+    '4. 若需求较简单，团队从简（2 到 3 个）；需求复杂才增加分工'
+  ].filter(line => line !== '').join('\n');
+}
+
+// 容错提取 JSON 数组：裸数组 → ```json 代码块 → 首个 [ 到最后一个 ] 的子串
+function extractTeamJSON(text) {
+  const raw = String(text || '').trim();
+  if (!raw) return null;
+  // 1. 整体就是合法 JSON
+  try { const v = JSON.parse(raw); if (Array.isArray(v)) return v; } catch { /* 继续尝试 */ }
+  // 2. markdown 代码块（```json ... ``` 或 ``` ... ```）
+  const fence = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fence) {
+    try { const v = JSON.parse(fence[1].trim()); if (Array.isArray(v)) return v; } catch { /* 继续尝试 */ }
+  }
+  // 3. 首个 [ 到最后一个 ] 之间（容忍前后杂文；字符串中含 ] 不影响，因为取最后一个 ]）
+  const start = raw.indexOf('[');
+  const end = raw.lastIndexOf(']');
+  if (start >= 0 && end > start) {
+    try { const v = JSON.parse(raw.slice(start, end + 1)); if (Array.isArray(v)) return v; } catch { /* 放弃 */ }
+  }
+  return null;
+}
+
+// 清洗生成结果：字段类型归一 + 长度截断 + 空名补名 + 重名后缀 + 数量上限
+// existingNames：现有智能体名（含管家），重名自动加序号，保证 @ 点名无歧义
+function cleanSuggestedTeam(arr, existingNames) {
+  if (!Array.isArray(arr)) return [];
+  const names = new Set(['管家', 'butler']);
+  for (const n of existingNames || []) {
+    const s = String(n || '').trim();
+    if (s) names.add(s);
+  }
+  const clean = [];
+  for (const a of arr) {
+    if (!a || typeof a !== 'object') continue;
+    let name = String(a.name || '').replace(/\s+/g, '').slice(0, LIMITS.name);
+    if (!name) name = `智能体${clean.length + 1}`;
+    let final = name;
+    let i = 2;
+    while (names.has(final)) final = `${name}${i++}`;
+    names.add(final);
+    clean.push({
+      name: final,
+      icon: String(a.icon || '').trim().slice(0, LIMITS.icon),
+      desc: String(a.desc || '').slice(0, LIMITS.desc),
+      systemPrompt: String(a.systemPrompt || '').slice(0, LIMITS.systemPrompt)
+    });
+    if (clean.length >= TEAM_MAX) break;
+  }
+  return clean;
+}
+
+// 完整生成链路：调内核一次 → 容错解析 → 清洗 → 数量校验
+// 返回 { success, agents, error }；任何失败都不影响现有配置（调用方不落盘）
+async function suggestTeam({ requirements, existingNames, runAgentFn, timeoutMs }) {
+  const run = runAgentFn || agentMod.runAgent;
+  const timeout = Number(timeoutMs) > 0 ? Number(timeoutMs) : SUGGEST_TIMEOUT_MS;
+  const scope = 'teamgen';
+  const prompt = buildPrompt(requirements, existingNames);
+
+  let settled = false;
+  let content = '';
+  let runError = '';
+  const done = new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      runError = `生成超时（${Math.round(timeout / 1000)} 秒），请稍后重试或简化需求描述`;
+      try { agentMod.stopScope(scope); } catch { /* ignore */ }
+      resolve();
+    }, timeout);
+    try {
+      run(
+        { id: scope, name: scope, model: '', behavior: 'echo', systemPrompt: '' },
+        prompt,
+        (chunk) => {
+          if (chunk && chunk.content) content += chunk.content;
+          if (chunk && chunk.error) runError = runError || String(chunk.error);
+          if (chunk && chunk.done && !settled) { settled = true; clearTimeout(timer); resolve(); }
+        },
+        scope
+      );
+    } catch (e) {
+      if (!settled) { settled = true; clearTimeout(timer); runError = `调用内核失败：${e.message}`; resolve(); }
+    }
+  });
+  await done;
+
+  if (runError) return { success: false, agents: [], error: runError };
+
+  const parsed = extractTeamJSON(content);
+  if (!parsed) {
+    return { success: false, agents: [], error: '生成结果无法解析为团队配置，请换个说法重试（例如补充更多分工细节）' };
+  }
+  const agents = cleanSuggestedTeam(parsed, existingNames);
+  if (agents.length < TEAM_MIN) {
+    return { success: false, agents: [], error: `生成结果只有 ${agents.length} 个智能体，至少需要 ${TEAM_MIN} 个，请补充更多分工细节后重试` };
+  }
+  return { success: true, agents };
+}
+
+module.exports = { buildPrompt, extractTeamJSON, cleanSuggestedTeam, suggestTeam, LIMITS, TEAM_MIN, TEAM_MAX, REQ_MAX };

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, #diffMask { 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, #suggestMask { 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, #diffMask.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, #suggestMask.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,15 @@
   .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; }
@@ -516,6 +525,24 @@
   </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">
@@ -561,6 +588,7 @@
     <div class="tip">每个智能体都是一个独立的 AI Agent：执行内核由顶部下拉框统一选择（OpenCode / Claude Code / Codex / pi），<b>图标</b>用于辨认，<b>名称</b>用于 @ 点名，<b>技能说明</b>供管家调度参考，<b>自定义提示词</b>会在任务下发时附加在用户提示词前面。所有智能体使用所选内核的默认模型。「管家」为内置调度智能体，不可修改。</div>
     <div class="butler-ro" id="butlerRo"></div>
     <div class="ag-row" style="margin:8px 0 2px">
+      <button class="add-agent" style="flex:1" onclick="openSuggest()">🪄 AI 组队 · 一句话生成团队</button>
       <button class="add-agent" style="flex:1" onclick="openTeams()">📦 团队仓库 · 一键换经典团队</button>
     </div>
     <div class="global-cwd-box">
@@ -631,6 +659,25 @@
     </div>
   </div>
 </div>
+<!-- AI 智能组队弹窗 -->
+<div id="suggestMask">
+  <div class="modal wide">
+    <h3>🪄 AI 组队</h3>
+    <div class="tip">用一句话描述你的需求，AI 扮演团队设计师，生成一套分工明确的智能体团队（名称/图标/技能说明/提示词）。先预览再应用，应用后仍可自由增删改，点配置页「保存」才生效。</div>
+    <div class="ta-wrap"><textarea id="sgReqInput" style="min-height:88px" placeholder="例如：我要从零做一个跨境电商独立站，需要市场调研、选品分析、网站前后端开发、内容文案和上线测试，帮我组建一支能覆盖全流程的团队"></textarea></div>
+    <div class="ag-row" style="margin:8px 0">
+      <button id="sgRunBtn" class="primary" style="flex:1" onclick="runSuggest()">✨ 生成团队</button>
+    </div>
+    <div id="sgResult"></div>
+    <div class="modal-actions">
+      <button class="mini-btn" onclick="runSuggest()">🔄 重新生成</button>
+      <span style="flex:1"></span>
+      <button onclick="closeSuggest()">放弃</button>
+      <button class="mini-btn" style="background:#07c160;color:#fff" onclick="applySuggest('append')">＋ 应用（合并到现有团队）</button>
+      <button class="primary" onclick="applySuggest('replace')">应用（替换全部子智能体）</button>
+    </div>
+  </div>
+</div>
 <!-- 聊天历史弹窗 -->
 <div id="historyMask">
   <div class="modal wide">
@@ -675,6 +722,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>
@@ -720,7 +769,7 @@
 </div>
 
 <script>
-const PAGE_VERSION = '3.32.0'; // 与服务端 /api/health.version 互检，不一致说明页面缓存过期
+const PAGE_VERSION = '3.34.0'; // 与服务端 /api/health.version 互检，不一致说明页面缓存过期
 const AV_COLORS = ['#5b8def','#07c160','#fa9d3b','#10aeff','#8a6fe8','#fa5151','#e8a33d','#3aa7a3'];
 const PHASE_LABEL = { plan: '调度规划', work: '执行', review: '验收', report: '汇总', talk: '圆桌发言', task: '任务执行' };
 // 职业图标库（智能体配置可选）
@@ -839,6 +888,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));
   // 消息区滚动：贴底时收起「新消息」悬浮按钮
@@ -1483,7 +1541,7 @@ function renderTasks() {
           ${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;
@@ -1531,7 +1589,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' ? '▶' : '•';
@@ -1974,6 +2032,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';
@@ -2693,6 +2763,41 @@ async function discardTaskDiff() {
   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' });
@@ -3269,6 +3374,94 @@ function applyTeamPreset(i, mode) {
   toast(`已应用「${t.name}」（${mode === 'replace' ? '替换' : '追加'} ${incoming.length} 个智能体），点「保存」后生效`);
 }
 
+// ---------- AI 智能组队：一句话需求 → 内核生成团队 → 预览应用 ----------
+let sgDraft = []; // 预览态候选（仅前端内存，应用才进 editing）
+
+function openSuggest() {
+  document.getElementById('sgResult').innerHTML = '';
+  sgDraft = [];
+  document.getElementById('suggestMask').classList.add('show');
+  setTimeout(() => document.getElementById('sgReqInput').focus(), 50);
+}
+function closeSuggest() { document.getElementById('suggestMask').classList.remove('show'); }
+
+async function runSuggest() {
+  const reqEl = document.getElementById('sgReqInput');
+  const requirements = String(reqEl.value || '').trim();
+  if (!requirements) { toast('先描述一下你的需求，AI 才知道要组什么团队'); reqEl.focus(); return; }
+  const btn = document.getElementById('sgRunBtn');
+  const out = document.getElementById('sgResult');
+  btn.disabled = true;
+  btn.textContent = '⏳ 生成中…（AI 正在设计团队分工，最长约 2 分钟）';
+  out.innerHTML = '<div class="task-empty" style="padding:16px">AI 正在根据你的需求设计团队分工，请稍候…</div>';
+  sgDraft = [];
+  try {
+    const r = await api('/api/agents/suggest', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ requirements }) });
+    if (r.success) {
+      sgDraft = r.agents || [];
+      renderSuggestCards();
+      toast(`已生成 ${sgDraft.length} 个智能体，确认后点下方「应用」`);
+    } else {
+      out.innerHTML = `<div class="task-empty" style="padding:16px;color:#c0392b">❌ ${esc(r.error || '生成失败，请稍后重试')}</div>`;
+    }
+  } catch (e) {
+    out.innerHTML = `<div class="task-empty" style="padding:16px;color:#c0392b">❌ 生成失败：${esc(e.message)}</div>`;
+  } finally {
+    btn.disabled = false;
+    btn.textContent = '✨ 生成团队';
+  }
+}
+
+function renderSuggestCards() {
+  const el = document.getElementById('sgResult');
+  if (!sgDraft.length) {
+    el.innerHTML = '<div class="task-empty" style="padding:16px">暂无生成结果，输入需求后点「生成团队」</div>';
+    return;
+  }
+  el.innerHTML = sgDraft.map((a, i) => `
+    <div class="ag-card">
+      <div class="ag-row">
+        <span style="font-size:20px;align-self:center">${esc(a.icon || '🤖')}</span>
+        <b style="align-self:center;flex:1">${esc(a.name)}</b>
+        <button class="mini-btn gray" onclick="sgDraft.splice(${i},1);renderSuggestCards()">删除</button>
+      </div>
+      <input value="${escAttr(a.desc || '')}" placeholder="技能说明" oninput="sgDraft[${i}].desc=this.value">
+      <details>
+        <summary style="font-size:12px;color:#666;cursor:pointer;margin:4px 0">自定义提示词（点击展开查看，可直接修改）</summary>
+        <textarea oninput="sgDraft[${i}].systemPrompt=this.value">${esc(a.systemPrompt || '')}</textarea>
+      </details>
+    </div>`).join('');
+}
+
+// 应用候选：append=合并到现有名单（重名自动加序号）；replace=替换全部子智能体
+function applySuggest(mode) {
+  if (!sgDraft.length) { toast('还没有可应用的生成结果'); return; }
+  const incoming = sgDraft.map(a => ({
+    id: '', behavior: 'echo',
+    name: String(a.name || '').trim(),
+    icon: String(a.icon || ''),
+    desc: String(a.desc || ''),
+    systemPrompt: String(a.systemPrompt || '')
+  })).filter(a => a.name);
+  if (!incoming.length) { toast('候选智能体缺少名称，无法应用'); return; }
+  if (mode === 'replace') {
+    editing = incoming;
+  } else {
+    const names = new Set(['管家', 'butler', ...editing.map(a => String(a.name || '').trim())]);
+    for (const a of incoming) {
+      let final = a.name, n = 2;
+      while (names.has(final)) final = `${a.name}${n++}`;
+      a.name = final;
+      names.add(final);
+      editing.push(a);
+    }
+  }
+  sgDraft = [];
+  renderAgentCards();
+  closeSuggest();
+  toast(`已应用 AI 生成的团队（${mode === 'replace' ? '替换' : '合并'} ${incoming.length} 个智能体），点配置页「保存」后生效`);
+}
+
 function iconPicker(i) {
   const cur = editing[i].icon || '';
   return '<div class="icon-row">' + ICON_PRESETS.map(ic =>
@@ -3520,6 +3713,7 @@ function openHelp() {
       <li>本机安装任一执行内核并登录模型（模型与密钥由内核自己管理，本程序不做任何 API 配置）：<br>
         <code>${KERNEL_INSTALL.opencode}</code><br><code>${KERNEL_INSTALL.claude}</code><br><code>${KERNEL_INSTALL.codex}</code><br><code>${KERNEL_INSTALL.pi}</code></li>
       <li>启动本程序后浏览器打开 <code>http://localhost:3456</code>，会自动识别已安装的内核</li>
+      <li>不知道配什么团队？「⚙ 智能体配置」里点「🪄 AI 组队」，一句话描述需求，AI 自动生成整套智能体团队（先预览再应用）；也可从「📦 团队仓库」一键换经典团队</li>
       <li>直接在输入框说话即可开始；粘贴任务清单可批量执行</li>
     </ol>
   </div>

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 ----------
@@ -64,7 +69,9 @@ process.on('unhandledRejection', (err) => {
 const PORT = Number(process.argv.includes('--port') ? process.argv[process.argv.indexOf('--port') + 1] : (process.env.PORT || 3456));
 const PUBLIC_DIR = path.join(__dirname, 'public');
 const store = require('./lib/store');
-const { runAgent, stopScope, stopAllChildren } = require('./lib/agent');
+const { runAgent, resolveRunner, missingHint, stopScope, stopAllChildren } = require('./lib/agent');
+const teamgen = require('./lib/teamgen');
+let suggestInFlight = false; // AI 组队生成互斥：同刻仅一个（内核单次调用，防并发浪费）
 const { runButler, runMentioned, runRoundtable, runTasks, prepareRerun } = require('./lib/orchestrator');
 const oc = require('./lib/oc');
 const memoryMod = require('./lib/memory');
@@ -593,6 +600,39 @@ const server = http.createServer(async (req, res) => {
     return;
   }
 
+  if (p === '/api/agents/suggest' && req.method === 'POST') {
+    // AI 智能组队：需求文本 → 执行内核生成团队配置（预览态，不落盘；应用走 /api/agents 保存链路）
+    const body = await readBody(req);
+    const requirements = String(body.requirements || '').trim();
+    if (!requirements || requirements.length > teamgen.REQ_MAX) {
+      json(res, 400, { success: false, error: `需求描述不能为空且不超过 ${teamgen.REQ_MAX} 字` });
+      return;
+    }
+    if (suggestInFlight) {
+      json(res, 409, { success: false, error: '上一次生成还在进行中，请稍候' });
+      return;
+    }
+    const runner = resolveRunner();
+    if (runner.kind === 'demo' || runner.kind === 'missing') {
+      const why = runner.kind === 'demo'
+        ? '当前为演示模式（AGENTS_CHAT_MOCK=1），删除 .env 中该配置并重启本程序后即可使用真实生成'
+        : missingHint(runner);
+      json(res, 200, { success: false, error: `AI 组队需要真实执行内核：${why}` });
+      return;
+    }
+    suggestInFlight = true;
+    try {
+      const r = await teamgen.suggestTeam({
+        requirements,
+        existingNames: store.getAgents().map(a => a.name)
+      });
+      json(res, 200, r);
+    } finally {
+      suggestInFlight = false;
+    }
+    return;
+  }
+
   if (p === '/api/tasks' && req.method === 'GET') {
     // 按 seq（拖拽可调）排序返回
     json(res, 200, { success: true, tasks: store.getTasks() });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iamsamyiok/agents-chat",
-  "version": "3.32.0",
+  "version": "3.34.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}`);
 }