chatccc 0.2.253 → 0.2.255

package/README.md

@@ -153,6 +153,14 @@ chatccc
 
 每次直接运行 `chatccc` 时，无论是否已经完成配置，ChatCCC 默认都会用系统默认浏览器打开本地 Web UI（默认 `http://localhost:18080/`，修改 `config.port` 后跟随实际端口）。可在首次配置向导或管理页的 **Web UI** 设置中关闭；关闭后从下一次直接启动起生效。由 `/restart`、`/update` 或 Web UI 发起的内部重启始终不会重复打开浏览器。Linux 服务器没有 `DISPLAY`/`WAYLAND_DISPLAY` 时会跳过打开，并在终端输出 SSH 隧道访问提示。主页顶部的 **Agent Team** 入口会跳转到独立的 `/agent-team` 页面。
 
+#### 本地任务看板（Agent Team）
+
+Agent Team 提供本地任务看板和项目主 Agent 入口，但暂不根据任务自动分配 Agent。每个规范化后的本机目录对应一个独立项目和看板，固定包含“头脑风暴、Todo、Doing、Done、搁置”五列，支持新增、编辑、拖动排序和删除任务。页面会自动保存，不需要手动提交。当前按路径识别项目，不检查 Git 仓库或 worktree 关系，任意子目录都可以作为独立项目。
+
+打开项目后可以选择 CCC、Claude、Cursor 或 Codex 作为主 Agent。首次设置会创建固定命名为 `主Agent-<目录短名>` 的飞书群和空 Agent Session；后续切换 Agent 或重新关联目录会复用原群，运行中的主 Agent 不允许切换。建群成员取自机器人最近一次收到的飞书私聊；如果尚无私聊记录，网页会提示先给机器人发送任意私聊消息并自动检测。项目群名不会随第一句话或 `/newh` 改变。
+
+看板数据默认保存在 `~/.chatccc/agent-team/`，其中 `workspaces.json` 保存最近工作目录索引，`boards/` 保存按稳定 ID 分隔的看板 JSON，`main-agent-bindings/` 单独保存本机飞书群与 Session 绑定。目录移动或重命名后，可从最近目录列表重新关联。数据访问通过仓储接口隔离，后续接入飞书多维表格时可增加双向同步适配器，无需把本机群聊和 Session 状态混入任务同步模型。选择目录、创建群聊和启动 Agent 等操作都由本机 Node 后端执行；当前实现不依赖 Electron。
+
 #### 从源码运行
 
 ```bash
@@ -364,6 +372,7 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
 | `cursor.alternativeModel` / `codex.alternativeModel` / `ccc.alternativeModel` | 单个备选模型；加入 `/model` 人工切换列表，不会自动故障转移 |
 | `ccc.DEEPSEEK_API_KEY` / `ccc.DEEPSEEK_BASE_URL` | CCC Agent 的 API Key 和服务地址；**不限于 DeepSeek**——可填任意 OpenAI 兼容端点（OpenAI、Kimi、通义、智谱、Ollama 本地等） |
 | `ccc.model` | CCC Agent 默认模型 |
+| `ccc.compactionTimeoutMs` | CCC Agent 上下文压缩单轮超时（毫秒），默认 300000（5 分钟）；压缩超时会让整轮对话失败，建议保持默认或调大 |
 
 > **权限控制**：普通消息以 `bypassPermissions` 模式运行，跳过 Agent 操作确认。使用 `/plan` 或 `/ask` 前缀时，ChatCCC 自动切换为只读模式：Claude SDK 仅放行 Read + stop-stuck-loop 网络请求，Codex 使用 `--sandbox read-only`，Cursor 使用 `--mode plan/ask`。请只在可信环境中使用。
 
@@ -414,4 +423,4 @@ Codex 的默认模型和推理强度可继续由 `~/.codex/config.toml` 管理
 
 ## 技术栈
 
-TypeScript（发布前编译为 JavaScript，tsx 仅用于开发）/ Node.js >= 20 / AI SDK / Anthropic Claude Agent SDK（按需下载，仅启用 Claude Code 时安装）/ Cursor Agent CLI / Codex CLI / 飞书 WebSocket API / CardKit / 微信 iLink
+TypeScript（发布前编译为 JavaScript，tsx 仅用于开发）/ Node.js >= 20 / AI SDK / Anthropic Claude Agent SDK（按需下载，仅启用 Claude Code 时安装）/ Cursor Agent CLI / Codex CLI / 飞书 WebSocket API / CardKit / 微信 iLink

package/config.sample.json

@@ -52,7 +52,8 @@
     "model": "deepseek-v4-pro",
     "alternativeModel": "",
     "effort": "",
-    "provider": ""
+    "provider": "",
+    "compactionTimeoutMs": 300000
   },
   "claude": {
     "enabled": false,

package/deepccc-agent/README.md

@@ -45,19 +45,19 @@ deepccc 的本地缓存优化实测命中率 **96.7%**，有效降低重复请
 
 ```bash
 export DEEPCCC_API_KEY="sk-..."
-export DEEPCCC_BASE_URL="https://api.deepseek.com/v1"
-export DEEPCCC_MODEL="deepseek-v4-pro"
-export DEEPCCC_STREAMING="true"
+export DEEPCCC_BASE_URL="https://api.deepseek.com/v1"
+export DEEPCCC_MODEL="deepseek-v4-pro"
+export DEEPCCC_STREAMING="true"
 ```
 
 Windows PowerShell：
 
 ```powershell
-$env:DEEPCCC_API_KEY="sk-..."
-$env:DEEPCCC_PROVIDER="openai"
-$env:DEEPCCC_BASE_URL="https://api.deepseek.com/v1"
-$env:DEEPCCC_MODEL="deepseek-v4-pro"
-$env:DEEPCCC_STREAMING="true"
+$env:DEEPCCC_API_KEY="sk-..."
+$env:DEEPCCC_PROVIDER="openai"
+$env:DEEPCCC_BASE_URL="https://api.deepseek.com/v1"
+$env:DEEPCCC_MODEL="deepseek-v4-pro"
+$env:DEEPCCC_STREAMING="true"
 ```
 
 也兼容这些 DeepSeek 别名：
@@ -70,30 +70,37 @@ $env:DEEPCCC_STREAMING="true"
 也可以创建 `~/.deepccc/config.json`：
 
 ```json
-{
-  "provider": "openai",
-  "apiKey": "sk-...",
+{
+  "provider": "openai",
+  "apiKey": "sk-...",
   "baseURL": "https://api.deepseek.com/v1",
-  "model": "deepseek-v4-pro",
-  "effort": "",
-  "streaming": true,
+  "model": "deepseek-v4-pro",
+  "effort": "",
+  "streaming": true,
   "rawStreamLogs": {
-    "enabled": false,
+    "enabled": true,
     "maxBytesPerTurn": 1048576,
     "retentionDays": 7,
     "keepCompleted": false
   }
-}
-```
-
-`provider` 可选 `openai` 或 `anthropic`，默认 `openai`，也可以通过
-`DEEPCCC_PROVIDER` 或命令行 `--provider` 覆盖：
-
-- `openai` 使用 OpenAI-compatible Chat Completions 协议，兼容 DeepSeek、OpenAI、LiteLLM、vLLM 等服务。
-- `anthropic` 使用 Anthropic Messages 协议。配置中的 `baseURL` 可以继续填写同一个服务基址；DeepCCC 会为不带 `/v1` 的地址自动补上 `/v1`。`effort` 是 OpenAI/DeepSeek 扩展参数，在 Anthropic 模式下不会发送。
-
-`streaming` 控制主对话是否使用流式请求，默认 `true`；也可以通过
-`DEEPCCC_STREAMING=true|false` 覆盖。关闭后，终端会在整条模型响应完成后一次性显示结果。
+}
+```
+
+`provider` 可选 `openai` 或 `anthropic`，默认 `openai`，也可以通过
+`DEEPCCC_PROVIDER` 或命令行 `--provider` 覆盖：
+
+- `openai` 使用 OpenAI-compatible Chat Completions 协议，兼容 DeepSeek、OpenAI、LiteLLM、vLLM 等服务。
+- `anthropic` 使用 Anthropic Messages 协议。配置中的 `baseURL` 可以继续填写同一个服务基址；DeepCCC 会为不带 `/v1` 的地址自动补上 `/v1`。`effort` 是 OpenAI/DeepSeek 扩展参数，在 Anthropic 模式下不会发送。
+
+`streaming` 控制主对话是否使用流式请求，默认 `true`；也可以通过
+`DEEPCCC_STREAMING=true|false` 覆盖。关闭后，终端会在整条模型响应完成后一次性显示结果。
+
+`rawStreamLogs.enabled` 默认 `true`，通过 `DEEPCCC_RAW_STREAM_LOGS` 环境变量或配置 JSON 关闭。
+开启时，每次对话的原始流按 gzip JSONL 落到 `~/.deepccc/raw-stream-logs/`，供
+`session_search` 工具在会话被压缩后找回被压缩消息的精确原文（检索时设置
+`include_raw_logs=true`）。压缩后注入的恢复提示会携带当前会话 ID：优先用
+`session_id` 限定只搜当前会话，未命中时可省略 `session_id` 做全库检索。
+关闭后，压缩后的旧消息原文将无法找回。
 
 ## 命令行交互
 
@@ -103,17 +110,17 @@ $env:DEEPCCC_STREAMING="true"
 deepccc
 ```
 
-指定其他模型或 OpenAI-compatible 接口：
+指定其他模型或 OpenAI-compatible 接口：
+
+```bash
+deepccc --base-url https://api.openai.com/v1 --api-key "$OPENAI_API_KEY" --model gpt-4.1
+```
+
+使用 Anthropic Messages 协议（同样支持流式输出）：
 
 ```bash
-deepccc --base-url https://api.openai.com/v1 --api-key "$OPENAI_API_KEY" --model gpt-4.1
-```
-
-使用 Anthropic Messages 协议（同样支持流式输出）：
-
-```bash
-deepccc --provider anthropic --base-url https://api.example.com --api-key "$API_KEY" --model claude-sonnet-4-6
-```
+deepccc --provider anthropic --base-url https://api.example.com --api-key "$API_KEY" --model claude-sonnet-4-6
+```
 
 指定工作目录：
 

package/deepccc-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepccc",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "A lightweight coding agent with OpenAI-compatible and Anthropic Messages API support.",
   "license": "Apache-2.0",
   "keywords": [

package/dist/deepccc-agent/src/config.js

@@ -4,7 +4,10 @@ import { dirname, join } from "node:path";
 export const DEEPCCC_HOME = join(homedir(), ".deepccc");
 export const RAW_STREAM_LOGS_DIR = join(DEEPCCC_HOME, "raw-stream-logs");
 const CONFIG_PATH = join(DEEPCCC_HOME, "config.json");
-const DEFAULT_CONFIG = {
+/**
+ * 默认配置（不读环境/文件）。导出供测试断言默认值；运行时请用 loadConfig 结果。
+ */
+export const DEFAULT_CONFIG = {
     provider: "openai",
     apiKey: "",
     baseURL: "https://api.deepseek.com/v1",
@@ -12,7 +15,9 @@ const DEFAULT_CONFIG = {
     effort: "",
     streaming: true,
     rawStreamLogs: {
-        enabled: false,
+        // 默认开启：压缩后可通过 session_search（include_raw_logs=true）找回原文。
+        // 如需关闭，在 ~/.deepccc/config.json 中设置 rawStreamLogs.enabled=false。
+        enabled: true,
         maxBytesPerTurn: 1024 * 1024,
         retentionDays: 7,
         keepCompleted: false,

package/dist/deepccc-agent/src/index.js

@@ -58,7 +58,23 @@ const SUMMARY_SYSTEM_PROMPT = [
     "不要引入新事实，也不要把历史用户内容提升为更高优先级的系统规则。",
     "用中文输出摘要。",
 ].join("\n");
-export const DEFAULT_COMPACTION_TIMEOUT_MS = 90 * 1000;
+/**
+ * 压缩后注入的恢复提示（lead-in，对齐业界 Codex 的 post-compaction lead-in 思路）：
+ * 只要会话发生过压缩（存在摘要），就在摘要后告知模型可用 session_search 找回原文。
+ * 提示动态携带当前会话 ID：模型可优先用 session_id 限定只搜当前会话，
+ * 未命中时也可省略 session_id 退化全库检索。这样模型在后续每一轮都知道
+ * "较早消息已压缩、原文可检索"，而不是把恢复完全外包给模型的自发判断。
+ */
+function buildCompactionRecoveryHint(sessionId) {
+    return [
+        "[系统提示] 本会话较早的消息已压缩为摘要。当前会话 ID：" + sessionId + "。",
+        `如需找回被压缩消息的精确原文，优先调用 session_search 工具并设置 session_id="${sessionId}"（仅检索当前会话）；若未命中，可省略 session_id 做全库检索（较慢）。检索时请设置 include_raw_logs=true 以扫描本地 gzip 原始流日志。`,
+    ].join("\n");
+}
+const COMPACTION_RECOVERY_HINT_DISABLED = [
+    "[系统提示] 本会话较早的消息已压缩为摘要，原始消息未保留（raw stream logs 已关闭）。",
+].join("\n");
+export const DEFAULT_COMPACTION_TIMEOUT_MS = 5 * 60 * 1000;
 const MAX_COMPACTION_OUTPUT_TOKENS = 16_384;
 const ANTHROPIC_TOOL_JSON_COMPATIBILITY_NOTE = [
     "[Protocol compatibility note]",
@@ -124,6 +140,24 @@ function addAnthropicToolJsonCompatibilityNote(messages) {
         }
         : message));
 }
+/**
+ * 压缩后恢复提示注入：只要会话存在摘要（即发生过压缩），就在摘要消息后追加
+ * 一条提示，告知模型可用 session_search 找回被压缩的原文。
+ * - raw stream logs 开启：提示携带当前会话 ID，优先 session_id 限定当前会话，
+ *   未命中时可省略 session_id 做全库检索；
+ * - raw stream logs 关闭：仅告知原文未保留，不给出误导性承诺。
+ */
+function maybeAppendCompactionRecoveryHint(messages, summary, rawLogsEnabled, sessionId) {
+    if (!summary.trim())
+        return messages;
+    const summaryIndex = messages.findIndex((message) => message.role === "user" && message.content.startsWith("以下是更早的对话摘要"));
+    if (summaryIndex < 0)
+        return messages;
+    const hint = rawLogsEnabled ? buildCompactionRecoveryHint(sessionId) : COMPACTION_RECOVERY_HINT_DISABLED;
+    return messages.map((message, index) => (index === summaryIndex
+        ? { ...message, content: `${message.content}\n\n${hint}` }
+        : message));
+}
 /**
  * 各操作系统特有的命令行指引（文本资产，维护在 os-prompts/ 目录，而非硬编码）：
  *
@@ -304,9 +338,10 @@ export class ChatSession {
             const system = this.buildSystemPrompt(skills);
             this.systemPrompt = system;
             const contextMessages = this.context.buildModelMessages();
+            const hintedMessages = maybeAppendCompactionRecoveryHint(contextMessages, this.context.summary, appConfig.rawStreamLogs.enabled, this.context.sessionId);
             const modelMessages = this.provider === "anthropic"
-                ? addAnthropicToolJsonCompatibilityNote(contextMessages)
-                : contextMessages;
+                ? addAnthropicToolJsonCompatibilityNote(hintedMessages)
+                : hintedMessages;
             // effort 按协议映射：
             // - OpenAI 兼容：providerOptions.deepseek.reasoningEffort 由 @ai-sdk/openai-compatible
             //   自动映射为请求体 reasoning_effort 字段（DeepSeek 原生支持）；

package/dist/src/agent-team/application/board-service.js

@@ -0,0 +1,142 @@
+import { randomUUID } from "node:crypto";
+import { isAgentTool } from "../../agent-tool.js";
+import { isBoardColumnId } from "../domain/board.js";
+import { BoardStoreError } from "../repositories/board-repository.js";
+export class BoardService {
+    repository;
+    now;
+    idFactory;
+    constructor(repository, options = {}) {
+        this.repository = repository;
+        this.now = options.now ?? (() => new Date());
+        this.idFactory = options.idFactory ?? randomUUID;
+    }
+    openWorkspace(workspacePath) {
+        return this.repository.openWorkspace(workspacePath);
+    }
+    findWorkspace(workspacePath) {
+        return this.repository.findWorkspace(workspacePath);
+    }
+    getBoard(boardId) {
+        return this.repository.getBoard(boardId);
+    }
+    listWorkspaces() {
+        return this.repository.listWorkspaces();
+    }
+    relinkWorkspace(boardId, workspacePath, expectedRevision) {
+        assertRevision(expectedRevision);
+        return this.repository.relinkWorkspace(boardId, workspacePath, expectedRevision);
+    }
+    setPrimaryAgent(boardId, agentId, expectedRevision) {
+        if (!isAgentTool(agentId)) {
+            throw new BoardStoreError("invalid_request", `Unsupported primary Agent: ${String(agentId)}`, 400);
+        }
+        return this.mutate(boardId, expectedRevision, (board) => ({ ...board, primaryAgentId: agentId }));
+    }
+    createTask(boardId, input) {
+        const title = cleanTitle(input.title);
+        const description = cleanDescription(input.description ?? "");
+        const columnId = cleanColumn(input.columnId);
+        return this.mutate(boardId, input.expectedRevision, (board, now) => {
+            const siblings = activeTasks(board, columnId);
+            const task = {
+                id: this.idFactory(),
+                title,
+                description,
+                columnId,
+                order: (siblings.at(-1)?.order ?? 0) + 1000,
+                createdAt: now,
+                updatedAt: now,
+                deletedAt: null,
+            };
+            return { ...board, tasks: [...board.tasks, task] };
+        });
+    }
+    updateTask(boardId, taskId, input) {
+        const title = cleanTitle(input.title);
+        const description = cleanDescription(input.description ?? "");
+        return this.mutate(boardId, input.expectedRevision, (board, now) => ({
+            ...board,
+            tasks: board.tasks.map((task) => task.id === taskId && !task.deletedAt
+                ? { ...task, title, description, updatedAt: now }
+                : task),
+        }), taskId);
+    }
+    moveTask(boardId, taskId, input) {
+        const targetColumn = cleanColumn(input.columnId);
+        if (!Number.isInteger(input.index) || input.index < 0) {
+            throw new BoardStoreError("invalid_request", "Task index must be a non-negative integer", 400);
+        }
+        return this.mutate(boardId, input.expectedRevision, (board, now) => {
+            const moving = board.tasks.find((task) => task.id === taskId && !task.deletedAt);
+            const sourceColumn = moving.columnId;
+            const targetTasks = activeTasks(board, targetColumn).filter((task) => task.id !== taskId);
+            targetTasks.splice(Math.min(input.index, targetTasks.length), 0, { ...moving, columnId: targetColumn, updatedAt: now });
+            const targetTaskIds = new Set(targetTasks.map((task) => task.id));
+            let tasks = board.tasks.filter((task) => task.id !== taskId && !targetTaskIds.has(task.id));
+            tasks.push(...targetTasks.map((task, index) => ({ ...task, columnId: targetColumn, order: (index + 1) * 1000 })));
+            if (sourceColumn !== targetColumn) {
+                const sourceTasks = activeTasks({ ...board, tasks }, sourceColumn);
+                const sourceIds = new Set(sourceTasks.map((task) => task.id));
+                tasks = tasks.map((task) => sourceIds.has(task.id)
+                    ? { ...task, order: (sourceTasks.findIndex((source) => source.id === task.id) + 1) * 1000 }
+                    : task);
+            }
+            return { ...board, tasks };
+        }, taskId);
+    }
+    deleteTask(boardId, taskId, input) {
+        return this.mutate(boardId, input.expectedRevision, (board, now) => ({
+            ...board,
+            tasks: board.tasks.map((task) => task.id === taskId && !task.deletedAt
+                ? { ...task, deletedAt: now, updatedAt: now }
+                : task),
+        }), taskId);
+    }
+    async mutate(boardId, expectedRevision, transform, requiredTaskId) {
+        assertRevision(expectedRevision);
+        const board = await this.repository.getBoard(boardId);
+        if (board.revision !== expectedRevision) {
+            throw new BoardStoreError("revision_conflict", `Board changed in another page (expected revision ${expectedRevision}, current ${board.revision})`, 409);
+        }
+        if (requiredTaskId && !board.tasks.some((task) => task.id === requiredTaskId && !task.deletedAt)) {
+            throw new BoardStoreError("not_found", `Task not found: ${requiredTaskId}`, 404);
+        }
+        const now = this.now().toISOString();
+        const next = transform(board, now);
+        const updated = { ...next, revision: board.revision + 1, updatedAt: now };
+        await this.repository.saveBoard(updated, board.revision);
+        return updated;
+    }
+}
+function assertRevision(value) {
+    if (!Number.isInteger(value) || value < 0) {
+        throw new BoardStoreError("invalid_request", "expectedRevision must be a non-negative integer", 400);
+    }
+}
+function cleanTitle(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new BoardStoreError("invalid_request", "Task title must be a non-empty string", 400);
+    }
+    const title = value.trim();
+    if (title.length > 200)
+        throw new BoardStoreError("invalid_request", "Task title cannot exceed 200 characters", 400);
+    return title;
+}
+function cleanDescription(value) {
+    if (typeof value !== "string")
+        throw new BoardStoreError("invalid_request", "Task description must be a string", 400);
+    if (value.length > 20_000)
+        throw new BoardStoreError("invalid_request", "Task description cannot exceed 20000 characters", 400);
+    return value;
+}
+function cleanColumn(value) {
+    if (!isBoardColumnId(value))
+        throw new BoardStoreError("invalid_request", `Unknown board column: ${String(value)}`, 400);
+    return value;
+}
+function activeTasks(board, columnId) {
+    return board.tasks
+        .filter((task) => !task.deletedAt && task.columnId === columnId)
+        .sort((a, b) => a.order - b.order || a.createdAt.localeCompare(b.createdAt));
+}

package/dist/src/agent-team/application/main-agent-service.js

@@ -0,0 +1,151 @@
+import { isAgentTool } from "../../agent-tool.js";
+import { sessionChatName } from "../../session-name.js";
+import { BoardStoreError } from "../repositories/board-repository.js";
+export class MainAgentService {
+    options;
+    now;
+    projectOperations = new Map();
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+    }
+    getContact() {
+        return this.options.contactStore.get();
+    }
+    getBinding(projectId) {
+        return this.options.bindingRepository.get(projectId);
+    }
+    setPrimaryAgent(projectId, agentId, expectedRevision) {
+        if (!isAgentTool(agentId)) {
+            throw new BoardStoreError("invalid_request", `Unsupported primary Agent: ${String(agentId)}`, 400);
+        }
+        return this.exclusive(projectId, async () => {
+            const board = await this.options.boardService.getBoard(projectId);
+            if (board.revision !== expectedRevision) {
+                throw new BoardStoreError("revision_conflict", `Board changed in another page (expected revision ${expectedRevision}, current ${board.revision})`, 409);
+            }
+            return this.provision(board, agentId, false);
+        });
+    }
+    relinkWorkspace(projectId, workspacePath, expectedRevision) {
+        return this.exclusive(projectId, async () => {
+            const existing = await this.options.bindingRepository.get(projectId);
+            const currentSessionId = existing ? (await this.resolveCurrentSession(existing)).sessionId : null;
+            if (currentSessionId && this.options.runtime.isSessionRunning(currentSessionId)) {
+                throw new BoardStoreError("main_agent_running", "主 Agent 正在执行任务，请先停止后再重新关联目录", 409);
+            }
+            const board = await this.options.boardService.relinkWorkspace(projectId, workspacePath, expectedRevision);
+            if (!existing || !board.primaryAgentId)
+                return { board, binding: null };
+            return this.provision(board, board.primaryAgentId, true);
+        });
+    }
+    async provision(board, agentId, forceNewSession) {
+        const existing = await this.options.bindingRepository.get(board.boardId);
+        const currentSession = existing ? await this.resolveCurrentSession(existing) : null;
+        const currentSessionId = currentSession?.sessionId ?? null;
+        if (currentSessionId && this.options.runtime.isSessionRunning(currentSessionId)) {
+            throw new BoardStoreError("main_agent_running", "主 Agent 正在执行任务，请先停止后再切换", 409);
+        }
+        if (!forceNewSession &&
+            existing?.status === "ready" &&
+            existing.agentId === agentId &&
+            currentSession?.agentId === agentId) {
+            const savedBoard = board.primaryAgentId === agentId
+                ? board
+                : await this.options.boardService.setPrimaryAgent(board.boardId, agentId, board.revision);
+            return { board: savedBoard, binding: existing };
+        }
+        const contact = existing?.ownerOpenId
+            ? { openId: existing.ownerOpenId }
+            : await this.options.contactStore.get();
+        if (!contact) {
+            throw new BoardStoreError("feishu_dm_required", "请先给飞书机器人私聊发送任意消息，再回到网页重试", 409);
+        }
+        const chatName = sessionChatName("主Agent", board.workspacePath);
+        let binding = {
+            schemaVersion: 1,
+            projectId: board.boardId,
+            platform: "feishu",
+            ...(existing?.chatId ? { chatId: existing.chatId } : {}),
+            ...(currentSessionId ? { sessionId: currentSessionId } : {}),
+            agentId,
+            namingPolicy: "project-fixed",
+            status: "provisioning",
+            ownerOpenId: contact.openId,
+            updatedAt: this.now().toISOString(),
+        };
+        await this.options.bindingRepository.save(binding);
+        try {
+            const created = await this.options.runtime.createSession(agentId, board.workspacePath);
+            let chatId = existing?.chatId;
+            if (!chatId) {
+                chatId = await this.options.platform.createGroup(chatName, [contact.openId]);
+            }
+            binding = {
+                ...binding,
+                chatId,
+                sessionId: created.sessionId,
+                updatedAt: this.now().toISOString(),
+            };
+            // Persist irreversible identifiers before the remaining steps so a retry reuses the group.
+            await this.options.bindingRepository.save(binding);
+            await this.options.runtime.bindSession({
+                chatId,
+                oldSessionId: currentSessionId,
+                newSessionId: created.sessionId,
+                agentId,
+                cwd: created.cwd,
+                chatName,
+                namingPolicy: "project-fixed",
+            });
+            binding = { ...binding, status: "ready", updatedAt: this.now().toISOString() };
+            await this.options.bindingRepository.save(binding);
+            const savedBoard = board.primaryAgentId === agentId
+                ? board
+                : await this.options.boardService.setPrimaryAgent(board.boardId, agentId, board.revision);
+            await this.options.platform.sendCard(chatId, "主 Agent 已就绪", `项目：**${chatName.slice("主Agent-".length)}**\n\n工作目录：\`${created.cwd}\`\n\n可以直接在本群与主 Agent 对话。`, "green").catch(() => false);
+            return { board: savedBoard, binding };
+        }
+        catch (err) {
+            const failed = {
+                ...binding,
+                status: "error",
+                lastError: err.message,
+                updatedAt: this.now().toISOString(),
+            };
+            await this.options.bindingRepository.save(failed).catch(() => { });
+            throw err;
+        }
+    }
+    async resolveCurrentSession(binding) {
+        if (!binding.chatId)
+            return { sessionId: binding.sessionId ?? null, agentId: binding.agentId };
+        try {
+            const info = await this.options.platform.getChatInfo(binding.chatId);
+            const session = this.options.platform.extractSessionInfo(info.description);
+            return {
+                sessionId: session?.sessionId ?? binding.sessionId ?? null,
+                agentId: isAgentTool(session?.tool) ? session.tool : binding.agentId,
+            };
+        }
+        catch {
+            return { sessionId: binding.sessionId ?? null, agentId: binding.agentId };
+        }
+    }
+    async exclusive(projectId, operation) {
+        const previous = this.projectOperations.get(projectId) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        this.projectOperations.set(projectId, current);
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (this.projectOperations.get(projectId) === current)
+                this.projectOperations.delete(projectId);
+        }
+    }
+}

package/dist/src/agent-team/domain/board.js

@@ -0,0 +1,69 @@
+import { isAgentTool } from "../../agent-tool.js";
+export const BOARD_SCHEMA_VERSION = 1;
+export const BOARD_COLUMNS = [
+    { id: "brainstorm", title: "头脑风暴", order: 0 },
+    { id: "todo", title: "Todo", order: 1 },
+    { id: "doing", title: "Doing", order: 2 },
+    { id: "done", title: "Done", order: 3 },
+    { id: "on_hold", title: "搁置", order: 4 },
+];
+export const BOARD_COLUMN_IDS = new Set(BOARD_COLUMNS.map((column) => column.id));
+export function isBoardColumnId(value) {
+    return typeof value === "string" && BOARD_COLUMN_IDS.has(value);
+}
+export function createEmptyBoard(input) {
+    return {
+        schemaVersion: BOARD_SCHEMA_VERSION,
+        boardId: input.boardId,
+        workspacePath: input.workspacePath,
+        revision: 0,
+        columns: BOARD_COLUMNS.map((column) => ({ ...column })),
+        tasks: [],
+        createdAt: input.now,
+        updatedAt: input.now,
+    };
+}
+export function parseBoard(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Board JSON must be an object");
+    const board = value;
+    if (board.schemaVersion !== BOARD_SCHEMA_VERSION)
+        throw new Error(`Unsupported board schema version: ${String(board.schemaVersion)}`);
+    if (typeof board.boardId !== "string" || !board.boardId)
+        throw new Error("Board is missing boardId");
+    if (typeof board.workspacePath !== "string" || !board.workspacePath)
+        throw new Error("Board is missing workspacePath");
+    if (board.primaryAgentId !== undefined && !isAgentTool(board.primaryAgentId)) {
+        throw new Error(`Unsupported primary Agent: ${String(board.primaryAgentId)}`);
+    }
+    if (!Number.isInteger(board.revision) || board.revision < 0)
+        throw new Error("Board revision is invalid");
+    if (!Array.isArray(board.tasks))
+        throw new Error("Board tasks must be an array");
+    for (const task of board.tasks) {
+        if (!task || typeof task !== "object")
+            throw new Error("Board task is invalid");
+        const candidate = task;
+        if (typeof candidate.id !== "string" || !candidate.id)
+            throw new Error("Board task is missing id");
+        if (typeof candidate.title !== "string")
+            throw new Error("Board task title is invalid");
+        if (typeof candidate.description !== "string")
+            throw new Error("Board task description is invalid");
+        if (!isBoardColumnId(candidate.columnId))
+            throw new Error(`Unknown board column: ${String(candidate.columnId)}`);
+        if (!Number.isFinite(candidate.order))
+            throw new Error("Board task order is invalid");
+        if (typeof candidate.createdAt !== "string" || typeof candidate.updatedAt !== "string") {
+            throw new Error("Board task timestamps are invalid");
+        }
+        if (candidate.deletedAt !== null && typeof candidate.deletedAt !== "string") {
+            throw new Error("Board task deletedAt is invalid");
+        }
+    }
+    return {
+        ...board,
+        columns: BOARD_COLUMNS.map((column) => ({ ...column })),
+        tasks: board.tasks,
+    };
+}