deepccc 0.1.7 → 0.1.9

package/README.md

@@ -180,7 +180,9 @@ deepccc --dangerously-bypass-permissions
 
 ## 终端过程区块
 
-交互模式下，每轮回复渲染为固定"过程区块"：状态行（生成中/完成/已停止/异常结束）+ 折叠工具行 + 原地更新正文，不滚屏刷 JSON。生成中有心跳点号动画；完成/停止/异常后区块定型留在屏幕上。
+交互模式下，每轮回复渲染为固定"过程区块"：状态行（压缩上下文中/生成回复中/完成/已停止/异常结束）+ 折叠工具行 + 原地更新正文，不滚屏刷 JSON。活动状态有心跳点号动画；完成/停止/异常后区块定型留在屏幕上。
+
+持久化上下文达到 token 阈值时，deepccc 会先按 token 预算保留最近消息，再压缩较早内容；超长历史消息、工具记录和压缩输入会被限长，避免单次摘要请求反复吞入巨量文本。一次压缩最多等待 5 分钟，超时或摘要失败会给出明确错误，不会自动重放用户请求。
 
 如果终端渲染出现异常，可以强制回退为纯文本流式输出：
 
@@ -205,8 +207,11 @@ echo "运行测试并解释失败原因" | deepccc --stream-json
 输出是逐行 JSON：
 
 ```jsonl
-{"type":"start","session_id":"session-...","mode":"new","cwd":"/repo","model":"deepseek-v4-pro"}
-{"type":"text_delta","text":"...","accumulated":"..."}
+{"type":"start","session_id":"session-...","mode":"new","cwd":"/repo","model":"deepseek-v4-pro"}
+{"type":"status","phase":"compacting"}
+{"type":"compact","compactedMessages":12}
+{"type":"status","phase":"generating"}
+{"type":"text_delta","text":"...","accumulated":"..."}
 {"type":"tool_call","id":"call_...","name":"read_file","input":{"path":"package.json"}}
 {"type":"tool_result","tool_call_id":"call_...","name":"read_file","content":{},"is_error":false}
 {"type":"done","text":"..."}

package/dist/cli.js

@@ -192,7 +192,13 @@ function writeJsonLine(event) {
     process.stdout.write(`${JSON.stringify(event)}\n`);
 }
 function streamJsonEvent(event) {
-    if (event.type === "text") {
+    if (event.type === "status") {
+        writeJsonLine({
+            type: "status",
+            phase: event.phase,
+        });
+    }
+    else if (event.type === "text") {
         writeJsonLine({
             type: "text_delta",
             text: event.text,
@@ -446,13 +452,16 @@ async function runRepl(args) {
             for await (const event of session.chat(input, signal)) {
                 if (renderer && view) {
                     view = reduceProgress(view, event);
-                    if (event.type === "text" || event.type === "compact") {
+                    if (event.type === "text" || event.type === "compact" || event.type === "status") {
                         renderer.render(view);
                     }
                     else {
                         renderer.flush();
                     }
                 }
+                else if (event.type === "status") {
+                    console.log(`${C.dim}[${event.phase === "compacting" ? "compacting context" : "generating reply"}]${C.reset}`);
+                }
                 else if (event.type === "text") {
                     const newText = event.accumulated.slice(lastAccumulated.length);
                     process.stdout.write(newText);

package/dist/context.d.ts

@@ -46,6 +46,11 @@ export declare function newBuiltinSessionId(now?: Date, suffix?: string): string
 export declare function getBuiltinContextSession(sessionId: string, contextDir?: string): BuiltinContextSessionInfo | null;
 export declare function listBuiltinContextSessions(contextDir?: string): BuiltinContextSessionInfo[];
 export declare function latestBuiltinSessionForCwd(cwd: string, contextDir?: string): BuiltinContextSessionInfo | null;
+/**
+ * 估算上下文的 token 数（用于决定何时压缩）。
+ * 按字符类型加权，比旧版 chars/3 更接近真实：CJK 字符 ≈ 1 token/字，
+ * 其他字符 ≈ 3.5 chars/token。避免中文长上下文被严重低估导致压缩过晚。
+ */
 export declare function estimateBuiltinContextTokens(summary: string, messages: readonly BuiltinContextMessage[]): number;
 export declare function serializeMessagesForSummary(messages: readonly BuiltinContextMessage[]): string;
 export declare function buildSummaryPrompt(plan: BuiltinCompactionPlan): string;

package/dist/context.js

@@ -5,6 +5,10 @@ import { join } from "node:path";
 export const DEFAULT_BUILTIN_CONTEXT_DIR = join(homedir(), ".deepccc", "sessions");
 export const DEFAULT_COMPACT_AT_TOKENS = 48_000;
 export const DEFAULT_KEEP_RECENT_MESSAGES = 16;
+const RECENT_CONTEXT_BUDGET_RATIO = 0.6;
+const MAX_COMPACTION_SUMMARY_CHARS = 16_000;
+const MAX_COMPACTION_MESSAGE_CHARS = 24_000;
+const MAX_COMPACTION_SOURCE_CHARS = 64_000;
 export function normalizeBuiltinSessionId(value) {
     return value.replace(/[^a-zA-Z0-9_.-]+/g, "_").replace(/^_+|_+$/g, "") || "default";
 }
@@ -121,15 +125,52 @@ export function latestBuiltinSessionForCwd(cwd, contextDir = DEFAULT_BUILTIN_CON
     const legacySessionId = defaultBuiltinSessionId(cwd);
     return listBuiltinContextSessions(contextDir).find((session) => session.cwd === cwd || session.sessionId === legacySessionId) ?? null;
 }
+/**
+ * 估算上下文的 token 数（用于决定何时压缩）。
+ * 按字符类型加权，比旧版 chars/3 更接近真实：CJK 字符 ≈ 1 token/字，
+ * 其他字符 ≈ 3.5 chars/token。避免中文长上下文被严重低估导致压缩过晚。
+ */
 export function estimateBuiltinContextTokens(summary, messages) {
-    const chars = summary.length + messages.reduce((sum, m) => sum + m.role.length + m.content.length, 0);
-    return Math.ceil(chars / 3);
+    const text = summary + messages.reduce((sum, m) => sum + `${m.role}\n${m.content}\n`, "");
+    let cjk = 0;
+    for (const ch of text) {
+        if (/[\u3400-\u4DBF\u4E00-\u9FFF\uF900-\uFAFF\u3000-\u303F\uFF00-\uFFEF]/.test(ch))
+            cjk++;
+    }
+    const other = text.length - cjk;
+    return Math.ceil(cjk + other / 3.5);
 }
 export function serializeMessagesForSummary(messages) {
     return messages
         .map((message, index) => `### ${index + 1}. ${message.role}\n${message.content}`)
         .join("\n\n");
 }
+function truncateMiddle(value, maxChars, marker) {
+    if (value.length <= maxChars)
+        return value;
+    const available = Math.max(0, maxChars - marker.length - 2);
+    const headChars = Math.ceil(available / 2);
+    const tailChars = Math.floor(available / 2);
+    return `${value.slice(0, headChars)}\n${marker}\n${value.slice(-tailChars)}`;
+}
+function serializeMessagesForCompaction(messages) {
+    const sections = [];
+    let remaining = MAX_COMPACTION_SOURCE_CHARS;
+    for (let index = 0; index < messages.length && remaining > 0; index += 1) {
+        const message = messages[index];
+        const header = `### ${index + 1}. ${message.role}\n`;
+        if (header.length >= remaining)
+            break;
+        const maxContentChars = Math.min(MAX_COMPACTION_MESSAGE_CHARS, remaining - header.length);
+        const content = truncateMiddle(message.content, maxContentChars, "...[truncated for compaction]...");
+        sections.push(`${header}${content}`);
+        remaining -= header.length + content.length + 2;
+    }
+    if (sections.length < messages.length) {
+        sections.push(`...[${messages.length - sections.length} additional messages omitted for compaction]...`);
+    }
+    return sections.join("\n\n");
+}
 export function buildSummaryPrompt(plan) {
     const sections = [
         "Compress the older DeepCCC conversation context.",
@@ -142,9 +183,9 @@ export function buildSummaryPrompt(plan) {
         "",
     ];
     if (plan.previousSummary.trim()) {
-        sections.push("## Existing Summary", plan.previousSummary.trim(), "");
+        sections.push("## Existing Summary", truncateMiddle(plan.previousSummary.trim(), MAX_COMPACTION_SUMMARY_CHARS, "...[existing summary truncated for compaction]..."), "");
     }
-    sections.push("## Messages To Compress", serializeMessagesForSummary(plan.oldMessages));
+    sections.push("## Messages To Compress", serializeMessagesForCompaction(plan.oldMessages));
     return sections.join("\n");
 }
 export class BuiltinContextManager {
@@ -204,9 +245,23 @@ export class BuiltinContextManager {
         const estimated = estimateBuiltinContextTokens(this.state.summary, this.state.messages);
         if (estimated <= this.compactAtTokens)
             return null;
-        const splitAt = this.state.messages.length - this.keepRecentMessages;
-        if (splitAt <= 0)
+        const messages = this.state.messages;
+        if (messages.length <= 1)
             return null;
+        const earliestAllowed = Math.max(0, messages.length - this.keepRecentMessages);
+        const recentTokenBudget = Math.max(1, Math.floor(this.compactAtTokens * RECENT_CONTEXT_BUDGET_RATIO));
+        let splitAt = messages.length - 1;
+        for (let index = messages.length - 2; index >= earliestAllowed; index -= 1) {
+            const candidate = messages.slice(index);
+            if (estimateBuiltinContextTokens("", candidate) > recentTokenBudget)
+                break;
+            splitAt = index;
+        }
+        // A large existing summary can put the total over budget even when every raw
+        // message fits. Always leave at least one old message to re-summarize so the
+        // compaction pass can still make progress.
+        if (splitAt <= 0)
+            splitAt = 1;
         return {
             previousSummary: this.state.summary,
             oldMessages: this.state.messages.slice(0, splitAt),

package/dist/file-tools.d.ts

@@ -132,6 +132,12 @@ export interface ApplyPatchFileChange {
 export interface ApplyPatchOutput {
     changedFiles: ApplyPatchFileChange[];
 }
+/**
+ * 把 `~` / `~/x`（含反斜杠 `~\\x`）展开为用户主目录绝对路径。
+ * `~user/x` 形式不展开（Node 无内置支持），保持原样交给后续解析。
+ * 供路径工具共用：技能索引里 `~/...` 路径可直接传给 read_file 等工具。
+ */
+export declare function expandHomePath(value: string): string;
 export declare function readFileForTool(cwd: string, input: ReadFileInput): Promise<ReadFileOutput>;
 export declare function listDirForTool(cwd: string, input?: ListDirInput): Promise<ListDirOutput>;
 export declare function searchCodeForTool(cwd: string, input: SearchCodeInput, signal?: AbortSignal, runtimeOptions?: SearchCodeRuntimeOptions): Promise<SearchCodeOutput>;

package/dist/file-tools.js

@@ -3,7 +3,8 @@ import { createHash, randomBytes } from "node:crypto";
 import { createReadStream } from "node:fs";
 import { copyFile, mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
-import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { createInterface } from "node:readline";
 import { jsonSchema, tool } from "ai";
 import { isDangerousCommand } from "./permissions.js";
@@ -22,11 +23,25 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 const MAX_COMMAND_TIMEOUT_MS = 900_000;
 const requireFromHere = createRequire(import.meta.url);
 const FALLBACK_SKIPPED_DIRECTORIES = new Set([".git", "node_modules"]);
+/**
+ * 把 `~` / `~/x`（含反斜杠 `~\\x`）展开为用户主目录绝对路径。
+ * `~user/x` 形式不展开（Node 无内置支持），保持原样交给后续解析。
+ * 供路径工具共用：技能索引里 `~/...` 路径可直接传给 read_file 等工具。
+ */
+export function expandHomePath(value) {
+    if (value === "~")
+        return homedir();
+    if (value.startsWith("~/") || value.startsWith("~\\")) {
+        return join(homedir(), value.slice(2));
+    }
+    return value;
+}
 function resolveToolPath(cwd, value) {
     const raw = value?.trim();
     if (!raw)
         return resolve(cwd);
-    return isAbsolute(raw) ? resolve(raw) : resolve(cwd, raw);
+    const expanded = expandHomePath(raw);
+    return isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded);
 }
 function toPositiveInt(value) {
     if (value === undefined)

package/dist/index.d.ts

@@ -4,6 +4,7 @@
  * ChatSession 是程序化入口，既可以被 CLI 调用，也可以被其他模块调用。
  */
 import { type PermissionMode, type PermissionResolver } from "./permissions.js";
+export declare const DEFAULT_COMPACTION_TIMEOUT_MS: number;
 export interface ChatSessionConfig {
     /** OpenAI-compatible service base URL. Defaults to DEEPCCC_BASE_URL/config. */
     baseURL?: string;
@@ -32,6 +33,8 @@ export interface ChatSessionOptions {
     compactAtTokens?: number;
     /** Number of recent raw messages retained after compaction. */
     keepRecentMessages?: number;
+    /** Hard deadline for all context-compaction passes in one turn. */
+    compactionTimeoutMs?: number;
     /** Optional tool-step limit. Leave unset for no step limit. */
     maxSteps?: number;
     /**
@@ -55,6 +58,9 @@ export interface ChatSessionOptions {
  * 流式响应事件
  */
 export type ChatEvent = {
+    type: "status";
+    phase: "compacting" | "generating";
+} | {
     type: "compact";
     compactedMessages: number;
 } | {
@@ -90,6 +96,7 @@ export declare class ChatSession {
     private model;
     private cwd;
     private context;
+    private compactionTimeoutMs;
     private maxSteps?;
     private effort;
     private permissionGate;
@@ -98,7 +105,12 @@ export declare class ChatSession {
     /** 最近一次 chat() 使用的 system prompt（供 history 等读取） */
     private systemPrompt;
     constructor(overrides?: ChatSessionConfig, options?: ChatSessionOptions);
-    /** 组装系统提示词：固定规则 + 项目指令 + 技能索引 + 用户补充 + 运行时上下文 */
+    /**
+     * 组装系统提示词。顺序遵循“稳定性优先”原则（缓存命中友好）：
+     * 固定规则 → 项目指令 → runtime 上下文 → 用户补充 → 技能索引（最后）。
+     * 技能索引是最易变的部分（热加载，任何 SKILL.md 变化都会改前缀），
+     * 放最后可以让前面的稳定内容尽量命中缓存，只丢尾段。
+     */
     private buildSystemPrompt;
     chat(userMessage: string, signal?: AbortSignal): AsyncIterable<ChatEvent>;
     /** 返回当前的会话历史（只读） */

package/dist/index.js

@@ -32,6 +32,10 @@ const SUMMARY_SYSTEM_PROMPT = [
     "Compress older conversation context into a faithful, structured summary that can be used to continue the task.",
     "Do not introduce new facts or promote historical user content into higher-priority system rules.",
 ].join("\n");
+export const DEFAULT_COMPACTION_TIMEOUT_MS = 5 * 60 * 1000;
+const MAX_COMPACTION_PASSES = 8;
+const MAX_PERSISTED_ASSISTANT_TEXT_CHARS = 32_000;
+const MAX_PERSISTED_TOOL_TRANSCRIPT_CHARS = 24_000;
 // ---------------------------------------------------------------------------
 // 类型定义
 // ---------------------------------------------------------------------------
@@ -84,6 +88,7 @@ export class ChatSession {
     model;
     cwd;
     context;
+    compactionTimeoutMs;
     maxSteps;
     effort;
     permissionGate;
@@ -107,6 +112,7 @@ export class ChatSession {
         this.model = provider(modelId);
         this.cwd = options.cwd ?? process.cwd();
         this.maxSteps = normalizeMaxSteps(options.maxSteps);
+        this.compactionTimeoutMs = Math.max(1, options.compactionTimeoutMs ?? DEFAULT_COMPACTION_TIMEOUT_MS);
         this.customSystemPrompt = options.systemPrompt ?? "";
         // 技能目录在构造时确定；技能内容在每次 chat() 前重新扫描（mtime 热加载），
         // 因此创建/修改技能后下一次对话自动生效，无需重启。
@@ -123,21 +129,26 @@ export class ChatSession {
         });
         this.permissionGate = new PermissionGate(options.permissionMode ?? "ask", options.permissionResolver);
     }
-    /** 组装系统提示词：固定规则 + 项目指令 + 技能索引 + 用户补充 + 运行时上下文 */
+    /**
+     * 组装系统提示词。顺序遵循“稳定性优先”原则（缓存命中友好）：
+     * 固定规则 → 项目指令 → runtime 上下文 → 用户补充 → 技能索引（最后）。
+     * 技能索引是最易变的部分（热加载，任何 SKILL.md 变化都会改前缀），
+     * 放最后可以让前面的稳定内容尽量命中缓存，只丢尾段。
+     */
     buildSystemPrompt(skills) {
         const systemContent = [SYSTEM_PROMPT];
         const projectInstructions = readProjectInstructionFiles(this.cwd);
         if (projectInstructions) {
             systemContent.push("", projectInstructions);
         }
+        systemContent.push("", buildRuntimeWorkspacePrompt(this.cwd));
+        if (this.customSystemPrompt) {
+            systemContent.push("", this.customSystemPrompt);
+        }
         const skillsPrompt = buildSkillsIndexPrompt(skills);
         if (skillsPrompt) {
             systemContent.push("", skillsPrompt);
         }
-        if (this.customSystemPrompt) {
-            systemContent.push("", this.customSystemPrompt);
-        }
-        systemContent.push("", buildRuntimeWorkspacePrompt(this.cwd));
         return systemContent.join("\n");
     }
     async *chat(userMessage, signal) {
@@ -147,10 +158,14 @@ export class ChatSession {
         let rawLog = null;
         let completed = false;
         try {
-            const compactedMessages = await this.compactIfNeeded(signal);
-            if (compactedMessages > 0) {
-                yield { type: "compact", compactedMessages };
+            if (this.context.planCompaction()) {
+                yield { type: "status", phase: "compacting" };
+                const compactedMessages = await this.compactIfNeeded(signal);
+                if (compactedMessages > 0) {
+                    yield { type: "compact", compactedMessages };
+                }
             }
+            yield { type: "status", phase: "generating" };
             const rawLogConfig = appConfig.rawStreamLogs;
             try {
                 rawLog = await createRawStreamLog({
@@ -232,9 +247,10 @@ export class ChatSession {
                 }
             }
             completed = true;
+            const persistedAssistantText = truncateMiddle(fullText, MAX_PERSISTED_ASSISTANT_TEXT_CHARS, "...[assistant response truncated in context]...");
             const persistedText = toolContext.length > 0
-                ? `${fullText}\n\n[Tool transcript]\n${toolContext.join("\n")}`
-                : fullText;
+                ? `${persistedAssistantText}\n\n[Tool transcript]\n${truncateMiddle(toolContext.join("\n"), MAX_PERSISTED_TOOL_TRANSCRIPT_CHARS, "...[tool transcript truncated]...")}`
+                : persistedAssistantText;
             this.context.appendMessage({ role: "assistant", content: persistedText });
             yield { type: "done", text: safeAccumulated };
         }
@@ -283,19 +299,47 @@ export class ChatSession {
         this.context.reset();
     }
     async compactIfNeeded(signal) {
-        const plan = this.context.planCompaction();
-        if (!plan)
+        if (!this.context.planCompaction())
             return 0;
-        const result = await generateText({
-            model: this.model,
-            system: SUMMARY_SYSTEM_PROMPT,
-            messages: [{ role: "user", content: buildSummaryPrompt(plan) }],
-            abortSignal: signal,
-        });
-        if (!result.text.trim())
-            return 0;
-        this.context.applyCompaction(result.text, plan);
-        return plan.oldMessages.length;
+        const timeoutController = new AbortController();
+        const timeout = setTimeout(() => timeoutController.abort(), this.compactionTimeoutMs);
+        timeout.unref?.();
+        const compactionSignal = signal
+            ? AbortSignal.any([signal, timeoutController.signal])
+            : timeoutController.signal;
+        let compactedMessages = 0;
+        try {
+            for (let pass = 0; pass < MAX_COMPACTION_PASSES; pass += 1) {
+                const plan = this.context.planCompaction();
+                if (!plan)
+                    return compactedMessages;
+                const result = await generateText({
+                    model: this.model,
+                    system: SUMMARY_SYSTEM_PROMPT,
+                    messages: [{ role: "user", content: buildSummaryPrompt(plan) }],
+                    abortSignal: compactionSignal,
+                    temperature: 0,
+                });
+                if (!result.text.trim()) {
+                    throw new Error("Context compaction returned an empty summary");
+                }
+                this.context.applyCompaction(result.text, plan);
+                compactedMessages += plan.oldMessages.length;
+            }
+            if (this.context.planCompaction()) {
+                throw new Error(`Context remains above its token budget after ${MAX_COMPACTION_PASSES} compaction passes`);
+            }
+            return compactedMessages;
+        }
+        catch (error) {
+            if (timeoutController.signal.aborted && !signal?.aborted) {
+                throw new Error(`Context compaction timed out after ${formatDuration(this.compactionTimeoutMs)}`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
     }
 }
 async function* textStreamToFullStream(stream) {
@@ -334,6 +378,21 @@ function safeRawStreamJson(value) {
 function truncateToolContext(value) {
     return value.length > 8000 ? `${value.slice(0, 8000)}...[truncated]` : value;
 }
+function truncateMiddle(value, maxChars, marker) {
+    if (value.length <= maxChars)
+        return value;
+    const available = Math.max(0, maxChars - marker.length - 2);
+    const headChars = Math.ceil(available / 2);
+    const tailChars = Math.floor(available / 2);
+    return `${value.slice(0, headChars)}\n${marker}\n${value.slice(-tailChars)}`;
+}
+function formatDuration(ms) {
+    if (ms % 60_000 === 0)
+        return `${ms / 60_000} minutes`;
+    if (ms % 1_000 === 0)
+        return `${ms / 1_000} seconds`;
+    return `${ms} ms`;
+}
 function errorMessage(value) {
     return value instanceof Error ? value.message : String(value);
 }

package/dist/progress/reducer.js

@@ -50,6 +50,10 @@ export function summarizeToolResult(content, maxChars = 120) {
  */
 export function reduceProgress(prev, event) {
     switch (event.type) {
+        case "status":
+            return withProgressView(prev, {
+                headerTitle: event.phase === "compacting" ? "压缩上下文中..." : "生成回复中...",
+            });
         case "text":
             // accumulated 是全文累积，直接全量替换，天然幂等
             return withProgressView(prev, { text: event.accumulated });

package/dist/skills.d.ts

@@ -46,11 +46,18 @@ export declare function scanSkillsDirs(dirs: SkillDirSpec[]): Promise<BuiltinSki
  * 其中 codex 全局包含 ~/.codex/skills（CLI 旧路径）与 ~/.agents/skills（标准全局目录）。
  */
 export declare function buildDefaultSkillDirs(cwd: string): SkillDirSpec[];
+/**
+ * 把技能绝对路径转成 prompt 展示形式：主目录下的路径缩写为 `~/...`（跨机器、
+ * 跨用户稳定，避免用户名/盘符差异导致 system 前缀变化破坏缓存命中）；
+ * 分隔符统一为 `/`。主目录外的路径保持绝对路径（仅统一分隔符）。
+ */
+export declare function normalizeSkillPathForPrompt(skillPath: string): string;
 /**
  * 生成 skill 索引提示词（注入 system prompt）。
  * 索引只含 name + description + 来源 + 路径，并指示模型在任务匹配时
  * 先用 read_file 读取 SKILL.md 全文再执行；同时声明"创建技能"约定
  * （模型在对话中应把新技能创建到 ~/.deepccc/skills 或项目 .deepccc/skills）。
+ * 路径经 normalizeSkillPathForPrompt 缩写，保持跨机器前缀稳定。
  */
 export declare function buildSkillsIndexPrompt(skills: BuiltinSkill[]): string;
 /** 生成 Codex 结构的新技能 SKILL.md 模板（供 CLI skill create / 对话创建约定共用） */

package/dist/skills.js

@@ -113,11 +113,27 @@ export function buildDefaultSkillDirs(cwd) {
         { dir: join(cwd, ".deepccc", "skills"), source: "deepccc", scope: "project" },
     ];
 }
+/**
+ * 把技能绝对路径转成 prompt 展示形式：主目录下的路径缩写为 `~/...`（跨机器、
+ * 跨用户稳定，避免用户名/盘符差异导致 system 前缀变化破坏缓存命中）；
+ * 分隔符统一为 `/`。主目录外的路径保持绝对路径（仅统一分隔符）。
+ */
+export function normalizeSkillPathForPrompt(skillPath) {
+    const home = homedir().replace(/[\\/]+$/, "").replace(/\\/g, "/");
+    const normalized = skillPath.replace(/\\/g, "/");
+    if (normalized === home)
+        return "~";
+    if (normalized.startsWith(home + "/")) {
+        return "~" + normalized.slice(home.length);
+    }
+    return normalized;
+}
 /**
  * 生成 skill 索引提示词（注入 system prompt）。
  * 索引只含 name + description + 来源 + 路径，并指示模型在任务匹配时
  * 先用 read_file 读取 SKILL.md 全文再执行；同时声明"创建技能"约定
  * （模型在对话中应把新技能创建到 ~/.deepccc/skills 或项目 .deepccc/skills）。
+ * 路径经 normalizeSkillPathForPrompt 缩写，保持跨机器前缀稳定。
  */
 export function buildSkillsIndexPrompt(skills) {
     if (skills.length === 0)
@@ -128,7 +144,7 @@ export function buildSkillsIndexPrompt(skills) {
         "On name conflicts: DeepCCC > Codex > Cursor > Claude wins; within one source, project scope wins over global.",
         "When a user request matches a skill's description, first read its full SKILL.md with read_file, then follow the instructions in it exactly.",
         "",
-        ...skills.map((s) => `- **${s.name}** [${s.source}:${s.scope}] (\`${s.skillPath}\`): ${s.description || "(no description)"}`),
+        ...skills.map((s) => `- **${s.name}** [${s.source}:${s.scope}] (\`${normalizeSkillPathForPrompt(s.skillPath)}\`): ${s.description || "(no description)"}`),
         "",
         "## Creating Skills",
         "When the user asks to create a skill, create it as a Codex-style directory skill at",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepccc",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "A lightweight DeepSeek-optimized coding agent with OpenAI-compatible model support.",
   "license": "Apache-2.0",
   "keywords": [