chatccc 0.2.292 → 0.2.294

package/deepccc-agent/README.md

@@ -198,7 +198,11 @@ API 拒绝（context length exceeded），实际窗口以模型与所用服务
 
 `task` 子代理工具：主模型可把边界清晰的独立子任务（仓库调研、长文档阅读、独立模块生成）
 委派给子代理执行——子代理使用子模型、独立上下文，不污染主对话上下文；结果截断回传。
-子代理**不能再次委派**（禁止嵌套），单轮最多 20 个工具步，超时与主会话压缩超时一致。
+子代理**不能再次委派**（禁止嵌套）。每次调用默认最多 20 步，也可用 `maxSteps` 在
+1–100 步内指定预算；若在工具调用后耗尽预算，内核会追加一次禁止调用工具的强制总结，
+避免只返回过程性开场白。设置 `runInBackground=true` 可让主代理继续工作，并通过
+`task_output` 查看状态，或通过 `task_stop` 停止继续调查并要求子代理基于已有证据总结。
+超时与主会话压缩超时一致。
 仅在配置了子模型时建议使用（未配置时子代理跟随主模型，节省有限）。
 
 `rawStreamLogs.enabled` 默认 `true`，通过 `DEEPCCC_RAW_STREAM_LOGS` 环境变量或配置 JSON 关闭。

package/deepccc-agent/package.json

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

package/dist/deepccc-agent/src/file-tools.js

@@ -25,14 +25,27 @@ const SEARCH_TIMEOUT_MS = 15_000;
 const MAX_COMMAND_OUTPUT_BYTES = 256 * 1024;
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 const MAX_COMMAND_TIMEOUT_MS = 900_000;
-/** 让位注入的轮询间隔：run_command 执行期以此频率检查是否有待注入的用户消息 */
-const YIELD_POLL_INTERVAL_MS = 250;
+/**
+ * 让位注入的轮询间隔：run_command 执行期以此频率检查是否有待注入的用户消息。
+ * 取 1s 而非更小值：轮询本身不花 token（只读内存队列，无模型调用），但更密的
+ * 定时器唤醒有可测的 CPU 开销（实测 250ms 档约 0.27ms/s，1s 档低于计时精度）。
+ * 让位延迟从 250ms 放宽到 1s 对用户无感，却把长任务期间的定时器唤醒降低到
+ * 约 1/4，因此取 1s 作为响应速度与空转成本的平衡点。
+ */
+const YIELD_POLL_INTERVAL_MS = 1000;
 /** command_output 单次等待上限，避免代理用等待把 step 又堵死 */
 const MAX_COMMAND_OUTPUT_WAIT_MS = 30_000;
 /** 后台命令句柄上限；超出时优先回收已结束的句柄 */
 const MAX_BACKGROUND_COMMANDS = 32;
 /** task 子代理工具：子任务结果回传主会话前的最大字符数（防止子代理长输出撑爆主上下文） */
 export const MAX_TASK_OUTPUT_CHARS = 32_000;
+/** task 子代理工具：调用方可选 step 预算的安全边界。 */
+export const MIN_TASK_MAX_STEPS = 1;
+export const MAX_TASK_MAX_STEPS = 100;
+/** task_stop 用此 abort reason 区分“主代理要求收尾”和整个父会话被取消。 */
+export const TASK_STOP_ABORT_REASON = "deepccc_task_stop";
+const MAX_BACKGROUND_TASKS = 32;
+const MAX_TASK_OUTPUT_WAIT_MS = 30_000;
 const requireFromHere = createRequire(import.meta.url);
 /** Adds DeepCCC attribution to git commit commands without replacing the user's author. */
 export function withGitCoAuthor(command, coAuthor) {
@@ -1182,6 +1195,114 @@ export async function applyPatchForTool(cwd, input) {
     }
     return { changedFiles };
 }
+const backgroundTasks = new Map();
+let backgroundTaskSeq = 0;
+function normalizeTaskOutputWaitMs(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return 0;
+    return Math.min(Math.trunc(value), MAX_TASK_OUTPUT_WAIT_MS);
+}
+function snapshotBackgroundTask(entry) {
+    return {
+        taskId: entry.taskId,
+        running: !entry.done,
+        stopped: entry.stopped,
+        ...(entry.result !== undefined ? { result: entry.result } : {}),
+        ...(entry.error !== undefined ? { error: entry.error } : {}),
+        durationMs: Date.now() - entry.startedAt,
+    };
+}
+function wakeBackgroundTaskWaiters(entry) {
+    for (const wake of entry.waiters.splice(0))
+        wake();
+}
+function pruneBackgroundTasks() {
+    if (backgroundTasks.size <= MAX_BACKGROUND_TASKS)
+        return;
+    for (const [id, entry] of backgroundTasks) {
+        if (!entry.done)
+            continue;
+        backgroundTasks.delete(id);
+        if (backgroundTasks.size <= MAX_BACKGROUND_TASKS)
+            return;
+    }
+}
+function waitForBackgroundTask(entry, waitMs) {
+    if (entry.done || waitMs <= 0)
+        return Promise.resolve();
+    return new Promise((resolvePromise) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const index = entry.waiters.indexOf(finish);
+            if (index >= 0)
+                entry.waiters.splice(index, 1);
+            resolvePromise();
+        };
+        const timer = setTimeout(finish, waitMs);
+        timer.unref?.();
+        entry.waiters.push(finish);
+    });
+}
+function startBackgroundTask(runTask, input, parentSignal) {
+    const controller = new AbortController();
+    const taskId = `agent-${Date.now().toString(36)}-${(++backgroundTaskSeq).toString(36)}-${randomBytes(3).toString("hex")}`;
+    const entry = {
+        taskId,
+        startedAt: Date.now(),
+        controller,
+        done: false,
+        stopped: false,
+        waiters: [],
+        promise: Promise.resolve(),
+    };
+    const signal = parentSignal
+        ? AbortSignal.any([parentSignal, controller.signal])
+        : controller.signal;
+    entry.promise = runTask(input, signal)
+        .then((result) => {
+        entry.result = result;
+    })
+        .catch((error) => {
+        entry.error = error instanceof Error ? error.message : String(error);
+    })
+        .finally(() => {
+        entry.done = true;
+        wakeBackgroundTaskWaiters(entry);
+    });
+    backgroundTasks.set(taskId, entry);
+    pruneBackgroundTasks();
+    return { taskId, running: true };
+}
+export async function taskOutputForTool(input) {
+    const entry = backgroundTasks.get(input.taskId);
+    if (!entry)
+        throw new Error(`未知的后台子代理：${input.taskId}`);
+    await waitForBackgroundTask(entry, normalizeTaskOutputWaitMs(input.waitMs));
+    return snapshotBackgroundTask(entry);
+}
+export async function taskStopForTool(input) {
+    const entry = backgroundTasks.get(input.taskId);
+    if (!entry)
+        throw new Error(`未知的后台子代理：${input.taskId}`);
+    if (!entry.done) {
+        entry.stopped = true;
+        entry.controller.abort(TASK_STOP_ABORT_REASON);
+        await entry.promise;
+    }
+    return snapshotBackgroundTask(entry);
+}
+/** 中止并清空全部后台子代理句柄（测试收尾或进程退出）。 */
+export function killAllBackgroundTasks() {
+    for (const entry of backgroundTasks.values()) {
+        if (!entry.done)
+            entry.controller.abort();
+    }
+    backgroundTasks.clear();
+}
 export function createBuiltinFileTools(cwd, options = {}) {
     const gate = options.permissionGate;
     const runTask = options.runTask;
@@ -1334,13 +1455,23 @@ export function createBuiltinFileTools(cwd, options = {}) {
             execute: (input) => commandKillForTool(input.taskId),
         }),
         task: tool({
-            description: "把独立子任务委派给子代理执行：子代理使用子模型、拥有独立上下文，不污染主对话上下文。适合边界清晰、可独立交付的调研/代码生成子任务（如扫描整个仓库、阅读长文档、生成独立模块）。子代理不能再次委派任务（禁止嵌套），结果会截断回传。",
+            description: `把独立子任务委派给子代理执行：子代理使用子模型、拥有独立上下文，不污染主对话上下文。可用 maxSteps 指定 ${MIN_TASK_MAX_STEPS}-${MAX_TASK_MAX_STEPS} 步预算。默认同步等待；runInBackground=true 时立即返回 taskId，之后用 task_output 查看或 task_stop 要求其停止调查并总结。子代理不能再次委派任务（禁止嵌套），结果会截断回传。`,
             inputSchema: jsonSchema({
                 type: "object",
                 additionalProperties: false,
                 properties: {
                     description: { type: "string", description: "子任务描述：目标、约束与交付物。请写清楚子代理需要返回什么。" },
                     cwd: { type: "string", description: "可选子任务工作目录（绝对路径或相对主会话 cwd），默认继承主会话工作目录。" },
+                    maxSteps: {
+                        type: "number",
+                        minimum: MIN_TASK_MAX_STEPS,
+                        maximum: MAX_TASK_MAX_STEPS,
+                        description: `可选的子代理最大步骤数，范围 ${MIN_TASK_MAX_STEPS}-${MAX_TASK_MAX_STEPS}；复杂全仓调查应显式提高。`,
+                    },
+                    runInBackground: {
+                        type: "boolean",
+                        description: "设为 true 后立即返回 taskId，使主代理能继续工作、查看进度或主动结束该子代理。",
+                    },
                 },
                 required: ["description"],
             }),
@@ -1348,10 +1479,43 @@ export function createBuiltinFileTools(cwd, options = {}) {
                 if (!runTask) {
                     throw new Error("task 工具不可用：当前环境未启用子代理执行器");
                 }
-                const result = await runTask(input, execOptions.abortSignal);
+                if (input.runInBackground === true) {
+                    return startBackgroundTask(runTask, input, execOptions?.abortSignal);
+                }
+                const result = await runTask(input, execOptions?.abortSignal);
                 return { result };
             },
         }),
+        task_output: tool({
+            description: "查看后台子代理的状态和最终总结。waitMs 可最多等待 30 秒；running=true 时稍后再查。",
+            inputSchema: jsonSchema({
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    taskId: { type: "string", description: "task(runInBackground=true) 返回的子代理句柄。" },
+                    waitMs: {
+                        type: "number",
+                        minimum: 0,
+                        maximum: MAX_TASK_OUTPUT_WAIT_MS,
+                        description: `可选等待毫秒数，最大 ${MAX_TASK_OUTPUT_WAIT_MS}。`,
+                    },
+                },
+                required: ["taskId"],
+            }),
+            execute: (input) => taskOutputForTool(input),
+        }),
+        task_stop: tool({
+            description: "结束一个后台子代理。子代理会停止继续调查，并基于停止前已收集的证据生成最终总结后返回。",
+            inputSchema: jsonSchema({
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    taskId: { type: "string", description: "task(runInBackground=true) 返回的子代理句柄。" },
+                },
+                required: ["taskId"],
+            }),
+            execute: (input) => taskStopForTool(input),
+        }),
         edit_file: tool({
             description: "通过精确的 oldText -> newText 替换编辑现有 UTF-8 文本文件。可行时使用 SHA-256 前置条件以避免覆盖并发编辑。",
             inputSchema: jsonSchema({

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

@@ -13,7 +13,7 @@ import { fileURLToPath } from "node:url";
 import { config as appConfig, normalizeDeepCccProvider, RAW_STREAM_LOGS_DIR, } from "./config.js";
 import { createRawStreamLog, } from "./raw-stream-log.js";
 import { buildPersistedAssistantMessage, buildSummaryPrompt, BuiltinContextManager, defaultBuiltinSessionId, } from "./context.js";
-import { createBuiltinFileTools, MAX_TASK_OUTPUT_CHARS } from "./file-tools.js";
+import { createBuiltinFileTools, MAX_TASK_MAX_STEPS, MAX_TASK_OUTPUT_CHARS, MIN_TASK_MAX_STEPS, TASK_STOP_ABORT_REASON, } from "./file-tools.js";
 import { PermissionGate } from "./permissions.js";
 import { hasMalformedToolProtocolText, TOOL_PROTOCOL_RECOVERY_PROMPT, } from "./tool-protocol.js";
 import { buildDefaultSkillDirs, buildSkillsIndexPrompt, scanSkillsDirs, } from "./skills.js";
@@ -88,8 +88,26 @@ const COMPACTION_RECOVERY_HINT_DISABLED = [
 export const DEFAULT_COMPACTION_TIMEOUT_MS = 5 * 60 * 1000;
 const MAX_COMPACTION_OUTPUT_TOKENS = 16_384;
 const OPENAI_COMPATIBLE_PROVIDER_NAME = "deepccc";
-/** task 子代理工具：子代理单轮对话的最大工具步数（防失控循环，结果收敛后即结束） */
-const TASK_MAX_STEPS = 20;
+/** task 子代理工具：未指定 maxSteps 时的默认步骤预算。 */
+const DEFAULT_TASK_MAX_STEPS = 20;
+const MAX_TASK_SUMMARY_OUTPUT_TOKENS = 16_384;
+const TASK_FINAL_SUMMARY_SYSTEM_PROMPT = [
+    "你是 DeepCCC 子代理的最终总结器。",
+    "只能依据消息中已经收集的证据作答，不得调用工具、继续调查或引入新事实。",
+    "直接交付原子任务要求的最终结果；说明关键证据、结论、局限和未完成项。",
+    "不要输出“我将开始”“接下来调查”等过程性开场白。",
+].join("\n");
+function normalizeTaskMaxSteps(value) {
+    if (value === undefined)
+        return DEFAULT_TASK_MAX_STEPS;
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+        throw new Error("task maxSteps 必须是整数");
+    }
+    if (value < MIN_TASK_MAX_STEPS || value > MAX_TASK_MAX_STEPS) {
+        throw new Error(`task maxSteps 必须在 ${MIN_TASK_MAX_STEPS}-${MAX_TASK_MAX_STEPS} 之间`);
+    }
+    return value;
+}
 /** 子代理最终输出截断：保留前 MAX_TASK_OUTPUT_CHARS 字符，尾部注明截断信息 */
 function truncateTaskOutput(text) {
     if (text.length <= MAX_TASK_OUTPUT_CHARS)
@@ -283,6 +301,43 @@ export class ChatSession {
     customSystemPrompt;
     /** 最近一次 chat() 使用的 system prompt（供 history 等读取） */
     systemPrompt = "";
+    /** 最近一轮底层模型的结束原因；用于识别 step 上限截停在工具调用之后的情况。 */
+    lastTurnFinishReason;
+    async summarizeTaskResult(child, reason) {
+        const summaryController = new AbortController();
+        const timeout = setTimeout(() => summaryController.abort(), this.compactionTimeoutMs);
+        timeout.unref?.();
+        try {
+            const reasonText = reason === "step_limit"
+                ? "子代理已用完步骤预算"
+                : reason === "stopped"
+                    ? "主代理已要求子代理停止继续调查"
+                    : "子代理已达到执行时限";
+            const result = await generateText({
+                model: child.model,
+                system: TASK_FINAL_SUMMARY_SYSTEM_PROMPT,
+                messages: [
+                    ...child.context.buildModelMessages(),
+                    {
+                        role: "user",
+                        content: `${reasonText}。不要再调用工具；请立即根据以上已有证据生成最终总结。`,
+                    },
+                ],
+                abortSignal: summaryController.signal,
+                temperature: 0,
+                maxOutputTokens: Math.min(child.maxOutputTokens ?? MAX_TASK_SUMMARY_OUTPUT_TOKENS, MAX_TASK_SUMMARY_OUTPUT_TOKENS),
+                providerOptions: child.provider === "openai"
+                    ? { [OPENAI_COMPATIBLE_PROVIDER_NAME]: { reasoningEffort: "none" } }
+                    : { anthropic: { effort: "low" } },
+            });
+            if (!result.text.trim())
+                throw new Error("task 子代理最终总结为空");
+            return result.text;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
     /**
      * task 子代理工具执行器：用子模型开独立子会话（独立上下文、独立 cwd）执行子任务，
      * 回传最终文本（截断 + 隐私替换）。单层：子会话的工具集不包含 runTask，天然禁止嵌套。
@@ -290,8 +345,9 @@ export class ChatSession {
     runTask = async (input, signal) => {
         const rawCwd = input.cwd?.trim();
         const taskCwd = rawCwd ? (isAbsolute(rawCwd) ? rawCwd : resolve(this.cwd, rawCwd)) : this.cwd;
+        const maxSteps = normalizeTaskMaxSteps(input.maxSteps);
         const timeoutController = new AbortController();
-        const timeout = setTimeout(() => timeoutController.abort(), this.compactionTimeoutMs);
+        const timeout = setTimeout(() => timeoutController.abort("deepccc_task_timeout"), this.compactionTimeoutMs);
         timeout.unref?.();
         const taskSignal = signal
             ? AbortSignal.any([signal, timeoutController.signal])
@@ -309,7 +365,7 @@ export class ChatSession {
                 persist: false,
                 permissionMode: this.permissionMode,
                 permissionResolver: this.permissionResolver,
-                maxSteps: TASK_MAX_STEPS,
+                maxSteps,
                 compactionTimeoutMs: this.compactionTimeoutMs,
                 skillsDirs: this.skillDirs.map((s) => s.dir),
             });
@@ -322,6 +378,14 @@ export class ChatSession {
                     throw new Error(`task 子代理执行失败: ${event.message}`);
                 }
             }
+            const explicitlyStopped = signal?.aborted === true && signal.reason === TASK_STOP_ABORT_REASON;
+            const parentCancelled = signal?.aborted === true && !explicitlyStopped;
+            const timedOut = timeoutController.signal.aborted;
+            const stepLimitReached = child.lastTurnFinishReason === "tool-calls";
+            if (!parentCancelled && (explicitlyStopped || timedOut || stepLimitReached)) {
+                const reason = explicitlyStopped ? "stopped" : timedOut ? "timeout" : "step_limit";
+                full = await this.summarizeTaskResult(child, reason);
+            }
             if (!full.trim())
                 return "(子代理未返回文本内容)";
             return applyPrivacy(truncateTaskOutput(full));
@@ -411,6 +475,7 @@ export class ChatSession {
         return systemContent.join("\n");
     }
     async *chat(userMessage, signal, drainInput) {
+        this.lastTurnFinishReason = undefined;
         this.context.appendMessage({ role: "user", content: userMessage });
         let fullText = "";
         let safeAccumulated = "";
@@ -664,6 +729,7 @@ export class ChatSession {
                             if (!fullText.trim() && toolCallOrder.length === 0)
                                 throw new Error("DeepCCC 本轮未产生有效回复");
                         }
+                        this.lastTurnFinishReason = finishReason;
                         if (hasMalformedToolProtocolText(fullText)) {
                             console.warn(`[DeepCCC] malformed tool protocol text detected for ${this.context.sessionId} `
                                 + `(attempt ${attempt + 1}/2, structuredToolCalls=${toolCallOrder.length})`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "chatccc",
-  "version": "0.2.292",
+  "version": "0.2.294",
   "description": "Feishu bot bridge for Claude Code",
   "license": "Apache-2.0",
   "type": "module",