thincoder 0.7.0 → 0.7.2

package/src/provider.mjs

@@ -10,11 +10,109 @@ import { specForModel } from "./config.mjs"
 export const RETRYABLE_STATUS = new Set([408, 409, 425, 429, 500, 502, 503, 504])
 const MAX_RETRIES = 3
 const MAX_CONTINUATIONS = 3 // Partial Mode 截断续写上限（防异常的无限 length 循环）
+// 429 的专项退避：RPM/TPM 按 60s 窗口计（账户级独立计数器），通用退避的 1s/2s/4s 等不出窗口
+const RATE_LIMIT_BACKOFF_MS = [15_000, 30_000, 60_000]
 
 /**
- * 创建 provider。config: { baseURL, apiKey, model, maxTokens?, temperature?, thinking?, reasoningEffort? }
+ * 测试钩子：睡眠/时钟/窗口长度可替换（离线测试不能真等 60s）。
+ * 生产代码不要直接调 setTimeout/sleep，统一走这里。
+ */
+export const _rateHooks = {
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now: () => Date.now(),
+  windowMs: 60_000,
+}
+
+// ---------------------------------------------------------------- TPM/RPM 主动节流闸门
+
+/**
+ * 滑动窗口闸门：发请求前若 窗口内已耗 + 本次估算 超预算，就睡到最早的记录滑出窗口。
+ * 按 baseURL+apiKey 记账（限速是账户级）；预算来自 provider.tpm / provider.rpm，
+ * 不配则闸门关闭（429 反应式退避仍然生效）。主循环/压缩摘要/子 agent/截断续写全走这里。
+ */
+const rateWindows = new Map() // key → { tokens: [{ts, n}], requests: [ts] }
+
+function rateKey(provider) {
+  return `${provider.baseURL}|${provider.apiKey ?? ""}`
+}
+
+/** 粗估文本 token 数（与 context.mjs 同口径：ASCII/4 + 非 ASCII/1；context 依赖本模块，不能反向 import） */
+function estimateText(s) {
+  let nonAscii = 0
+  for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) > 0x7f) nonAscii++
+  return Math.ceil((s.length - nonAscii) / 4) + nonAscii
+}
+
+/** 本次请求的 prompt 估算：messages 正文 + 思考链 + tool_calls 参数 + tools schema */
+function estimateRequestTokens(body) {
+  let tokens = 0
+  for (const m of body.messages ?? []) {
+    if (typeof m.content === "string") tokens += estimateText(m.content)
+    if (typeof m.reasoning_content === "string") tokens += estimateText(m.reasoning_content)
+    for (const tc of m.tool_calls ?? []) {
+      tokens += estimateText(tc.function?.name ?? "") + estimateText(tc.function?.arguments ?? "")
+    }
+  }
+  if (body.tools) tokens += estimateText(JSON.stringify(body.tools))
+  return tokens
+}
+
+/** 闸门：超预算则睡到窗口腾出空间；onWait({phase:"gate", seconds}) 供 UI 展示等待 */
+async function rateGate(provider, estimated, onWait, signal) {
+  // 单次请求估算已超过 TPM 预算时闸门无意义（等到天荒地老也塞不下），放行由服务端裁决
+  const tpm = provider.tpm != null && estimated <= provider.tpm ? provider.tpm : null
+  const rpm = provider.rpm ?? null
+  if (tpm == null && rpm == null) return
+  const w = rateWindows.get(rateKey(provider)) ?? { tokens: [], requests: [] }
+  rateWindows.set(rateKey(provider), w)
+  for (;;) {
+    const now = _rateHooks.now()
+    const cutoff = now - _rateHooks.windowMs
+    w.tokens = w.tokens.filter((e) => e.ts > cutoff)
+    w.requests = w.requests.filter((ts) => ts > cutoff)
+    const usedTokens = w.tokens.reduce((s, e) => s + e.n, 0)
+    const overTokens = tpm != null ? usedTokens + estimated - tpm : 0
+    const overRequests = rpm != null ? w.requests.length + 1 - rpm : 0
+    if (overTokens <= 0 && overRequests <= 0) break
+    let waitMs = _rateHooks.windowMs
+    if (overTokens > 0) {
+      // tokens 按时间升序：累加最早若干条，过期量足够腾出空间时的过期时刻
+      let freed = 0
+      for (const e of w.tokens) {
+        freed += e.n
+        if (freed >= overTokens) {
+          waitMs = Math.min(waitMs, e.ts + _rateHooks.windowMs - now)
+          break
+        }
+      }
+    }
+    if (overRequests > 0) {
+      // 等第 overRequests-1 条（升序）滑出，窗口内请求数即降回 rpm-1
+      waitMs = Math.min(waitMs, w.requests[overRequests - 1] + _rateHooks.windowMs - now)
+    }
+    waitMs = Math.max(waitMs, 50)
+    onWait?.({ phase: "gate", seconds: Math.ceil(waitMs / 1000) })
+    await _rateHooks.sleep(waitMs)
+    if (signal?.aborted) return
+  }
+}
+
+/** 记账：响应回来后按实测 usage 记（无 usage 用发送前的估算兜底）；被拒的请求不记（服务端未处理） */
+function recordRate(provider, estimated, usage) {
+  if (provider.tpm == null && provider.rpm == null) return
+  const w = rateWindows.get(rateKey(provider)) ?? { tokens: [], requests: [] }
+  rateWindows.set(rateKey(provider), w)
+  const now = _rateHooks.now()
+  w.requests.push(now)
+  // TPM 按输入+输出总量计（Moonshot 口径）
+  w.tokens.push({ ts: now, n: usage ? (usage.prompt_tokens ?? estimated) + (usage.completion_tokens ?? 0) : estimated })
+}
+
+/**
+ * 创建 provider。config: { baseURL, apiKey, model, maxTokens?, temperature?, thinking?, reasoningEffort?, tpm?, rpm? }
  * thinking: { type: "enabled"|"disabled" }  思维模式开关
  * reasoningEffort: "low"|"high"|"max"       推理强度（DeepSeek/Kimi/GLM 通用）
+ * tpm / rpm: 主动节流预算（tokens/分钟、请求数/分钟，按账户限速等级自配），不配则闸门关闭
  */
 export function createProvider(config) {
   if (!config?.baseURL) throw new Error("provider config: baseURL is required")
@@ -28,6 +126,8 @@ export function createProvider(config) {
     temperature: config.temperature,
     thinking: config.thinking,
     reasoningEffort: config.reasoningEffort,
+    tpm: config.tpm,
+    rpm: config.rpm,
   }
 }
 
@@ -35,6 +135,7 @@ export function createProvider(config) {
  * 流式对话。
  * messages: OpenAI 格式数组; tools: OpenAI tools schema（可选）
  * onToken(text): 正文流式回调; onReasoning(text): 思考流回调（DeepSeek-R1 类模型）
+ * onWait({phase, seconds}): 节流等待回调（phase: "gate"=主动节流 / "retry"=429 退避）
  * signal: AbortSignal（可选）
  * 返回 { content, reasoning, toolCalls: [{id, name, arguments}], usage, finishReason }
  * 注意：toolCalls[i].arguments 是 JSON 字符串，调用方负责 parse
@@ -46,7 +147,7 @@ export function createProvider(config) {
  * - prefixMode（DeepSeek）：assistant 消息带 prefix:true，且须走 /beta 端点；
  *   思考模式不支持前缀续写，已产出 reasoning 时放弃续写
  */
-export async function chat(provider, { messages, tools, onToken, onReasoning, signal }) {
+export async function chat(provider, { messages, tools, onToken, onReasoning, onWait, signal }) {
   const spec = specForModel(provider.model)
   const body = {
     model: provider.model,
@@ -77,8 +178,13 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, si
   }
   if (tools?.length) body.tools = tools
 
-  const response = await requestWithRetry(provider, body, signal)
+  // TPM/RPM 主动节流：超预算先在本地睡到窗口腾出空间，不打 429 碰运气
+  const estimated = estimateRequestTokens(body)
+  await rateGate(provider, estimated, onWait, signal)
+
+  const response = await requestWithRetry(provider, body, signal, onWait)
   const result = await readSSE(response, { onToken, onReasoning })
+  recordRate(provider, estimated, result.usage)
 
   // 截断续写：仅规格表声明续写协议的模型（其他端点不认识 partial/prefix 字段，可能 400）
   if (!spec.partialMode && !spec.prefixMode) return result
@@ -101,26 +207,31 @@ export async function chat(provider, { messages, tools, onToken, onReasoning, si
       tools,
       onToken,
       onReasoning,
+      onWait,
       signal,
     })
     result.content += continued.content
     result.reasoning += continued.reasoning ?? ""
     for (const tc of continued.toolCalls ?? []) {
-    if (tc.index == null) { result.toolCalls = continued.toolCalls; break }
-    const s = result.toolCalls[tc.index] ??= { id: "", name: "", arguments: "" }
-    if (tc.id) s.id = tc.id
-    s.name += tc.name ?? ""
-    s.arguments += tc.arguments ?? ""
-  }
+      if (tc.index == null) { result.toolCalls = continued.toolCalls; break }
+      const s = result.toolCalls[tc.index] ??= { id: "", name: "", arguments: "" }
+      if (tc.id) s.id = tc.id
+      s.name += tc.name ?? ""
+      s.arguments += tc.arguments ?? ""
+    }
     result.finishReason = continued.finishReason
     if (continued.usage) {
-    result.usage = {
-      prompt_tokens: (result.usage?.prompt_tokens??0) + (continued.usage.prompt_tokens??0),
-      completion_tokens: (result.usage?.completion_tokens??0) + (continued.usage.completion_tokens??0),
-      total_tokens: (result.usage?.total_tokens??0) + (continued.usage.total_tokens??0),
+      const sum = (k) => (result.usage?.[k] ?? 0) + (continued.usage[k] ?? 0)
+      result.usage = {
+        prompt_tokens: sum("prompt_tokens"),
+        completion_tokens: sum("completion_tokens"),
+        total_tokens: sum("total_tokens"),
+        // 缓存命中/未命中也要累计（DeepSeek 计费与状态栏展示依赖这两个字段）
+        prompt_cache_hit_tokens: sum("prompt_cache_hit_tokens"),
+        prompt_cache_miss_tokens: sum("prompt_cache_miss_tokens"),
+      }
     }
   }
-  }
   return result
 }
 
@@ -141,11 +252,18 @@ export async function listModels(provider, { signal } = {}) {
   return (data.data ?? []).map((m) => m.id).filter(Boolean).sort()
 }
 
-/** 带重试的请求：网络错误与 429/5xx 指数退避（1s/2s/4s），其余 4xx 直接抛 */
-async function requestWithRetry(provider, body, signal) {
+/**
+ * 带重试的请求：网络错误与 5xx 指数退避（1s/2s/4s）；429 专项处理——
+ * 有 Retry-After 以它为准，没有按 15s/30s/60s 退避（RPM/TPM 是 60s 窗口，秒级退避等不出去）。
+ * 配额/余额错误（如 exceeded_current_quota_error）与限速同状态码但语义不同：重试无用，直接抛。
+ */
+async function requestWithRetry(provider, body, signal, onWait) {
   let lastError
+  let lastWas429 = false
+  let rateLimitHits = 0 // 连续 429 计数（退避档位用，与 attempt 解耦）
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    if (attempt > 0) await sleep(2 ** (attempt - 1) * 1000)
+    if (attempt > 0 && !lastWas429) await _rateHooks.sleep(2 ** (attempt - 1) * 1000)
+    lastWas429 = false
 
     let response
     try {
@@ -168,6 +286,21 @@ async function requestWithRetry(provider, body, signal) {
 
     const text = await response.text().catch(() => "")
     const message = `LLM API error ${response.status}: ${text}`
+    if (isQuotaError(text)) throw new Error(message)
+    if (response.status === 429) {
+      const retryAfter = Number(response.headers.get("retry-after"))
+      const waitMs =
+        Number.isFinite(retryAfter) && retryAfter > 0
+          ? retryAfter * 1000
+          : RATE_LIMIT_BACKOFF_MS[Math.min(rateLimitHits++, RATE_LIMIT_BACKOFF_MS.length - 1)]
+      lastError = new Error(message)
+      lastWas429 = true
+      if (attempt < MAX_RETRIES) {
+        onWait?.({ phase: "retry", seconds: Math.ceil(waitMs / 1000) })
+        await _rateHooks.sleep(waitMs)
+      }
+      continue
+    }
     if (RETRYABLE_STATUS.has(response.status)) {
       lastError = new Error(message)
       continue
@@ -177,6 +310,16 @@ async function requestWithRetry(provider, body, signal) {
   throw lastError
 }
 
+/** 配额/余额错误（重试无意义）：错误体 type 含 quota，如 Moonshot exceeded_current_quota_error */
+function isQuotaError(text) {
+  try {
+    const type = JSON.parse(text)?.error?.type
+    return typeof type === "string" && type.includes("quota")
+  } catch {
+    return false
+  }
+}
+
 /** 解析 SSE 流，累积正文/思考/tool_calls */
 async function readSSE(response, { onToken, onReasoning }) {
   const result = { content: "", reasoning: "", toolCalls: [], usage: null, finishReason: null }
@@ -233,10 +376,6 @@ async function readSSE(response, { onToken, onReasoning }) {
   return result
 }
 
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms))
-}
-
 /** DeepSeek Prefix Completion 只在 /beta 端点开放：.../v1 → .../beta */
 function betaBaseURL(baseURL) {
   return baseURL.replace(/\/v1$/, "/beta")

package/src/repomap.mjs

@@ -74,17 +74,15 @@ function parsePyOutline(lines) {
   for (const line of lines) {
     const fromRe = line.match(/^from\s+(\S+)\s+import\s+(.+)/)
     if (fromRe) {
-      const mod = fromRe[1]
-      if (!mod.startsWith(".")) continue // 只本地
-      imports.push(normalizeExt(mod.replace(/^\.+/, "")))
+      const rel = pyRelPath(fromRe[1])
+      if (rel) imports.push(rel)
       continue
     }
     const impRe = line.match(/^import\s+(.+)/)
     if (impRe) {
       for (const mod of impRe[1].split(",")) {
-        const m = mod.trim().split(/\s+/)[0]
-        if (!m.startsWith(".")) continue
-        imports.push(normalizeExt(m.replace(/^\.+/, "")))
+        const rel = pyRelPath(mod.trim().split(/\s+/)[0])
+        if (rel) imports.push(rel)
       }
       continue
     }
@@ -94,19 +92,32 @@ function parsePyOutline(lines) {
   return { imports: [...new Set(imports)], symbols: [...new Set(symbols)] }
 }
 
+/**
+ * Python 相对导入 → 相对文件路径：
+ * 前导 n 个点表示上溯 n-1 层（"."=当前包），模块点号转路径分隔符。
+ * 非相对导入（不以 . 开头）或纯包导入（"from . import x"）返回 null。
+ */
+function pyRelPath(mod) {
+  if (!mod?.startsWith(".")) return null
+  const dots = mod.match(/^\.+/)[0].length
+  const rest = mod.slice(dots).replaceAll(".", "/")
+  if (!rest) return null
+  return normalizeExt("../".repeat(dots - 1) + rest)
+}
+
 function normalizeExt(p) {
   return p.replace(/\.(m?js|jsx|tsx?)$/i, "")
 }
 
-/** 从 code_chunks 取已知文件列表（复用索引），按路径解析生成大纲文本 */
-export function buildOutline(db, cwd, focusPath) {
+/**
+ * 内部：扫描全量文件，构建正向依赖图 + 反向引用图。
+ * 返回 { deps, importers, fileCount } 供 buildOutline / buildSummary 共用。
+ */
+function _buildDepGraph(db, cwd) {
   const allFiles = db.prepare(`SELECT DISTINCT path FROM code_chunks ORDER BY path`).all().map((r) => r.path)
+  if (allFiles.length === 0) return null
 
-  if (allFiles.length === 0) return "(no indexed source files; run codeSync or /reindex first)"
-
-  // 构建正向（谁 import 谁）+ 反向（被谁 import）图——总是全量扫描，
-  // 因为聚焦一个文件也需要知道别的文件是否 import 了它
-  const deps = new Map()      // path → { imports: Set, exports: Set, size: number }
+  const deps = new Map()      // path → { imports: Set, exports: Set, size: number, dir: string }
   const importers = new Map() // importee → Set<importer>
 
   for (const rel of allFiles) {
@@ -129,7 +140,6 @@ export function buildOutline(db, cwd, focusPath) {
     // 把 import 路径解析成相对路径（处理 ./ ../）
     const resolved = []
     for (let imp of imports) {
-      // 去掉 ./ 前缀
       if (imp.startsWith("./")) imp = imp.slice(2)
       const dir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : ""
       const parts = imp.split("/")
@@ -143,7 +153,8 @@ export function buildOutline(db, cwd, focusPath) {
       }
     }
 
-    deps.set(rel, { imports: new Set(resolved), exports: new Set(exports), size: Math.floor(text.length / 1024) })
+    const dir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "."
+    deps.set(rel, { imports: new Set(resolved), exports: new Set(exports), size: Math.floor(text.length / 1024), dir })
 
     for (const r of resolved) {
       if (!importers.has(r)) importers.set(r, new Set())
@@ -151,7 +162,97 @@ export function buildOutline(db, cwd, focusPath) {
     }
   }
 
-  // 生成文本
+  return { deps, importers, fileCount: allFiles.length }
+}
+
+/**
+ * 生成紧凑架构摘要（替换旧的全量注入）。
+ * 三层信息，每层信息密度递减：
+ *  1. 目录级依赖（多目录项目才有意义，单目录跳过）
+ *  2. 枢纽文件 Top-12（被 import 最多的文件——架构骨架）
+ *  3. 入口文件（无人 import 的文件——启动/顶层入口）
+ * 输出天然有界（~1000-2000 字符），不再需要 OUTLINE_INJECT_MAX 硬截断。
+ */
+export function buildSummary(db, cwd) {
+  const graph = _buildDepGraph(db, cwd)
+  if (!graph) return "(no indexed source files; run codeSync or /reindex first)"
+  const { deps, importers, fileCount } = graph
+
+  const out = []
+  out.push(`${fileCount} source files indexed.`)
+
+  // 1) 目录级依赖
+  const dirDeps = new Map() // dir → Set<imported-dir>
+  const dirSet = new Set()
+  for (const [rel, d] of deps) {
+    dirSet.add(d.dir)
+    if (!dirDeps.has(d.dir)) dirDeps.set(d.dir, new Set())
+    for (const imp of d.imports) {
+      const targetDir = imp.includes("/") ? imp.slice(0, imp.lastIndexOf("/")) : "."
+      if (targetDir !== d.dir) dirDeps.get(d.dir).add(targetDir)
+    }
+  }
+  if (dirSet.size > 1) {
+    out.push("Directory dependencies:")
+    for (const dir of [...dirSet].sort()) {
+      const targets = dirDeps.get(dir)
+      if (targets?.size) {
+        out.push(`  ${dir}/ → ${[...targets].sort().join(", ")}/`)
+      } else {
+        out.push(`  ${dir}/ (leaf)`)
+      }
+    }
+  }
+
+  // 2) 枢纽文件 Top-12：按被 import 次数降序
+  const HUB_LIMIT = 12
+  const hubScores = []
+  for (const [rel] of deps) {
+    const key = rel.replace(/\.(m?js|jsx|tsx?)$/i, "")
+    const rev = importers.get(key)
+    if (rev?.size) hubScores.push({ path: rel, count: rev.size })
+  }
+  hubScores.sort((a, b) => b.count - a.count)
+  if (hubScores.length > 0) {
+    out.push(`Hub files (by inbound dependencies, top ${Math.min(hubScores.length, HUB_LIMIT)}):`)
+    for (const h of hubScores.slice(0, HUB_LIMIT)) {
+      const d = deps.get(h.path)
+      const kb = d?.size ? ` (${d.size} KB)` : ""
+      const key = h.path.replace(/\.(m?js|jsx|tsx?)$/i, "")
+      const rev = importers.get(key)
+      const shortRefs = rev.size <= 5
+        ? [...rev].join(", ")
+        : [...rev].slice(0, 4).join(", ") + ` +${rev.size - 4} more`
+      out.push(`  ${h.path}${kb} — imported by: ${shortRefs}`)
+    }
+  }
+
+  // 3) 入口文件：无人 import 的（叶子/入口）
+  const entries = []
+  for (const [rel] of deps) {
+    const key = rel.replace(/\.(m?js|jsx|tsx?)$/i, "")
+    if (!importers.has(key) || importers.get(key).size === 0) {
+      entries.push(rel)
+    }
+  }
+  if (entries.length > 0 && entries.length < fileCount) {
+    const limit = 8
+    const shown = entries.slice(0, limit)
+    out.push(`Entry points (not imported by others):`)
+    for (const e of shown) out.push(`  ${e}`)
+    if (entries.length > limit) out.push(`  ... +${entries.length - limit} more`)
+  }
+
+  out.push("For detailed per-file relationships, call repo_outline with a file path.")
+  return out.join("\n")
+}
+
+/** 从 code_chunks 取已知文件列表（复用索引），按路径解析生成大纲文本 */
+export function buildOutline(db, cwd, focusPath) {
+  const graph = _buildDepGraph(db, cwd)
+  if (!graph) return "(no indexed source files; run codeSync or /reindex first)"
+  const { deps, importers } = graph
+
   const files = focusPath ? [focusPath] : [...deps.keys()]
   const out = []
   const sorted = files.sort()

package/src/session.mjs

@@ -45,8 +45,8 @@ function saveManifest(cwd, m) {
   writeSessionFile(manifestPath(cwd), m)
 }
 
-/** 归档当前会话到空闲槽位——满了踢最老 */
-export function archiveCurrent(cwd) {
+/** 归档当前会话到空闲槽位——满了踢最老；exclude 指定一个不许被踢的槽位（switchToSlot 的目标槽） */
+export function archiveCurrent(cwd, { exclude } = {}) {
   const src = sessionPath(cwd)
   if (!existsSync(src)) return
   const m = loadManifest(cwd)
@@ -57,11 +57,20 @@ export function archiveCurrent(cwd) {
     slot = 1
     while (m.slots[slot]) slot++
   } else {
-    slot = Number(entries.sort((a, b) => a[1] - b[1])[0][0])
+    const candidates = entries.filter(([n]) => Number(n) !== exclude)
+    slot = Number((candidates.length ? candidates : entries).sort((a, b) => a[1] - b[1])[0][0])
   }
 
   const dst = slotPath(cwd, slot)
-  writeFileSync(dst, readFileSync(src, "utf8"), "utf8") // 复制（rename 会丢当前）
+  // 复制（rename 会丢当前）；走原子写，防中途崩溃留下截断的 JSON 丢归档
+  let data
+  try {
+    data = JSON.parse(readFileSync(src, "utf8"))
+  } catch {
+    // 会话文件损坏，放弃归档，下次保存会覆盖
+    return
+  }
+  writeSessionFile(dst, data)
   m.slots[slot] = Date.now()
   delete m.slots._currentName
   saveManifest(cwd, m)
@@ -82,16 +91,21 @@ export function switchToSlot(cwd, slot) {
   if (!m.slots[slot]) return null
 
   // 归档当前（内部写 manifest；之后我们的 m 已过期，需重读）
-  archiveCurrent(cwd)
+  // 满槽时排除目标槽：否则最老槽=目标槽，归档会把目标覆盖掉再复制回来，目标会话永久丢失
+  archiveCurrent(cwd, { exclude: slot })
 
   // 槽位文件 → 当前（copy+unlink，不用 rename：Windows rename 目标已存在会抛 EPERM）
   const src = slotPath(cwd, slot)
   const dst = sessionPath(cwd)
   if (!existsSync(src)) return null
-  // 先删当前文件（archiveCurrent 是复制不是移动，所以它还在）
-  try { unlinkSync(dst) } catch { /* 不存在就算了 */ }
-  copyFileSync(src, dst)
-  unlinkSync(src)
+  try {
+    try { unlinkSync(dst) } catch { /* 不存在就算了 */ }
+    copyFileSync(src, dst)
+    unlinkSync(src)
+  } catch {
+    // 文件操作失败（磁盘满/权限不足/锁文件），放弃切换
+    return null
+  }
 
   // 重读 manifest（archiveCurrent 改了它）
   const m2 = loadManifest(cwd)

package/src/skills.mjs

@@ -28,13 +28,17 @@ export async function loadSkills(cwd) {
     try {
       const s = await stat(p)
       if (!s.isFile()) continue
-      // 提取描述（前 400 字符里第一段非空、非标题行）
+      // 提取描述（前 400 字符里第一段非空、非标题行）；文件带 frontmatter 时整块跳过，
+      // 否则会把 frontmatter 字段行（如 "name: x"）误当描述
       const head = await readFile(p, "utf8")
       const body = head.slice(0, 400).split("\n")
       let desc = ""
+      let inFrontmatter = false
       for (const line of body) {
         const t = line.trim()
-        if (t && !t.startsWith("#") && !t.startsWith("---")) {
+        if (t === "---") { inFrontmatter = !inFrontmatter; continue }
+        if (inFrontmatter) continue
+        if (t && !t.startsWith("#")) {
           desc = t.slice(0, 120)
           break
         }

package/src/tools/apply_patch.md

@@ -0,0 +1,11 @@
+Apply a unified diff to one or more files, atomically: if any hunk fails to apply, nothing is written.
+
+Parameters:
+- patch (required): Unified diff text. One `--- a/path` / `+++ b/path` header pair per file, then `@@ -old,count +new,count @@` hunks. Use `--- /dev/null` to create a new file.
+
+Notes:
+- Use this for multi-file changes (e.g. rename an interface + update all callers) — one call, all-or-nothing
+- Hunks are located by their context/removed lines, not line numbers — but the context must match the file EXACTLY. Read the files first and generate the patch from actual content
+- If a hunk's context matches multiple locations it is rejected — add more surrounding context lines
+- Deleting files is not supported — use the delete tool
+- For single-file small edits, edit is simpler; for full rewrites, write is simpler

package/src/tools/checkpoint.md

@@ -0,0 +1,11 @@
+List, create, and restore workspace snapshots (checkpoints). Git repositories only.
+
+Parameters:
+- action (required): "list" | "create" | "rewind"
+- id: snapshot id (required for rewind)
+
+Notes:
+- A checkpoint is AUTO-CREATED before every user task. If uncommitted work was destroyed (by you, a git command, or a failed refactor), use action=list then action=rewind with the latest id to recover it
+- A checkpoint captures all uncommitted state: tracked-file changes (as a diff) plus copies of untracked files
+- Rewind first snapshots the current state, so rewinding is itself reversible
+- Create one manually before risky bulk operations