mingdao-harness 0.2.4 → 0.2.6

package/src/providers/index.js

@@ -16,7 +16,7 @@ import { modelPreset, providerPreset } from '../models.js';
 import { mingdaoHome } from '../config.js';
 import { resolveApiKey } from '../credentials.js';
 
-export function resolveProviderConfig(cfg, modelName) {
+export function resolveProviderConfig(/** @type {any} */ cfg, /** @type {any} */ modelName) {
   // 自定义模型（config.customModels，WebUI 可增删改）：优先于内置预设
   const cm = cfg?.customModels?.[modelName];
   if (cm) {
@@ -47,16 +47,16 @@ export function resolveProviderConfig(cfg, modelName) {
   };
 }
 
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const sleep = (/** @type {any} */ ms) => new Promise((r) => setTimeout(r, ms));
 
-function isTransient(err) {
+function isTransient(/** @type {any} */ err) {
   const status = err?.status;
   if (status === 429 || (status >= 500 && status <= 504)) return true;
   // 注意：不含 abort —— 用户 Ctrl+C 主动中断不应触发重试
   return /timeout|超时|ECONNRESET|fetch failed/i.test(String(err?.message || ''));
 }
 
-export async function createProvider(cfg, modelName, { timeoutMs = 300000, retries = 2 } = {}) {
+export async function createProvider(/** @type {any} */ cfg, /** @type {any} */ modelName, { timeoutMs = 300000, retries = 2 } = {}) {
   const pc = resolveProviderConfig(cfg, modelName);
 
   // 自定义 Provider 模块优先（仅普通自定义端点；custom:<模型名> 走 OpenAI 兼容直连）
@@ -77,7 +77,7 @@ export async function createProvider(cfg, modelName, { timeoutMs = 300000, retri
   return {
     name: pc.name,
     config: pc,
-    async chat(opts) {
+    async chat(/** @type {any} */ opts) {
       let attempt = 0;
       for (;;) {
         const ac = new AbortController();
@@ -105,7 +105,7 @@ export async function createProvider(cfg, modelName, { timeoutMs = 300000, retri
           attempt += 1;
           // 指数退避 + 尊重 Retry-After（评估 P3-1）：基础 1s/2s，服务端指定时取其值（封顶 30s）
           let backoff = 1000 * attempt;
-          const ra = Number(err?.headers?.get?.('retry-after'));
+          const ra = Number((/** @type {any} */ (err))?.headers?.get?.('retry-after'));
           if (Number.isFinite(ra) && ra > 0) backoff = Math.max(backoff, ra * 1000);
           backoff = Math.min(backoff, 30000);
           await sleep(backoff);
@@ -121,7 +121,7 @@ export async function createProvider(cfg, modelName, { timeoutMs = 300000, retri
 // 辅助调用（标题生成/记忆提取等）的 provider 解析（评估 P2-2）：辅助模型与当前模型
 // 分属不同服务商时单独创建 provider——避免拿 deepseek-v4-flash 模型名去自定义网关请求
 // 而 404 被静默吞掉（标题缺失、记忆永不沉淀且零感知）。
-export async function helperProvider(cfg, helperModel, currentProvider) {
+export async function helperProvider(/** @type {any} */ cfg, /** @type {any} */ helperModel, /** @type {any} */ currentProvider) {
   try {
     const curName = String(currentProvider?.name || '');
     const helperName = String(resolveProviderConfig(cfg, helperModel)?.name || '');

package/src/providers/openai-compatible.js

@@ -6,9 +6,9 @@
  * @typedef {Error & { status?: number, headers?: Headers }} ApiError
  */
 
-export async function chat({ baseUrl, apiKey, model, messages, tools, temperature, maxTokens, signal, onDelta, includeUsage = true, responseFormat, reasoningEffort }) {
+export async function chat(/** @type {any} */ { baseUrl, apiKey, model, messages, tools, temperature, maxTokens, signal, onDelta, includeUsage = true, responseFormat, reasoningEffort }) {
   const url = String(baseUrl).replace(/\/+$/, '') + '/chat/completions';
-  const payload = { model, messages };
+  const payload = /** @type {Record<string, any>} */ ({ model, messages });
   if (temperature != null) payload.temperature = temperature;
   if (tools && tools.length) {
     payload.tools = tools;
@@ -16,7 +16,8 @@ export async function chat({ baseUrl, apiKey, model, messages, tools, temperatur
   }
   if (maxTokens) payload.max_tokens = maxTokens;
   if (responseFormat) payload.response_format = responseFormat;
-  if (reasoningEffort) payload.reasoning_effort = reasoningEffort; // 思考强度（官方 thinking_mode）
+  if (reasoningEffort === 'off') payload.thinking = { type: 'disabled' }; // /think off：显式关闭思考（官方 thinking_mode）
+  else if (reasoningEffort) payload.reasoning_effort = reasoningEffort; // 思考强度（官方 thinking_mode）
   payload.stream = true;
   // 流式响应默认不带 usage，显式请求以便展示 token/费用统计
   // （部分网关不支持该字段，可在 config.json 设 "includeUsage": false 关闭）
@@ -36,7 +37,7 @@ export async function chat({ baseUrl, apiKey, model, messages, tools, temperatur
     });
   } catch (err) {
     /** @type {ApiError} */
-    const e = new Error(`网络请求失败：${err?.message || err}`);
+    const e = new Error(`网络请求失败：${(/** @type {any} */ (err))?.message || err}`);
     e.status = 0;
     throw e;
   }
@@ -64,7 +65,7 @@ export async function chat({ baseUrl, apiKey, model, messages, tools, temperatur
   return parseStream(res.body, onDelta);
 }
 
-export function parseNonStream(json, onDelta) {
+export function parseNonStream(/** @type {any} */ json, /** @type {any} */ onDelta) {
   const choice = json?.choices?.[0];
   const msg = choice?.message ?? {};
   if (msg.content) onDelta?.({ text: msg.content });
@@ -80,7 +81,7 @@ export function parseNonStream(json, onDelta) {
 }
 
 // 解析 SSE 流：处理跨 chunk 断行、增量 content / reasoning_content / tool_calls。
-export async function parseStream(body, onDelta) {
+export async function parseStream(/** @type {any} */ body, /** @type {any} */ onDelta) {
   const reader = body.getReader();
   const decoder = new TextDecoder();
   let buf = '';
@@ -90,15 +91,15 @@ export async function parseStream(body, onDelta) {
   const indexKeys = new Map(); // index -> key（id 只在首片出现，后续分片按 index 找回同一条目）
   let autoKey = 0;
   let usage = null;
-  let finish = null;
+  let /** @type {any} */ finish = null;
 
   let doneFlag = false;
-  const handleLine = (lineRaw) => {
+  const handleLine = (/** @type {any} */ lineRaw) => {
     const line = lineRaw.trim();
     if (!line.startsWith('data:')) return;
     const data = line.slice(5).trim();
     if (data === '[DONE]') {
-      finish = finish || 'stop';
+      finish = /** @type {any} */ finish || 'stop';
       doneFlag = true;
       return true; // 通知外层终止读取（审计 P2-4：[DONE] 后不再消费残帧、不挂到超时）
     }
@@ -153,8 +154,9 @@ export async function parseStream(body, onDelta) {
       if (handleLine(line)) break;
     }
   }
-  // 收尾：残行（网关最后一帧不带换行）与多字节字符冲刷
-  content += decoder.decode();
+  // 收尾：残行（网关最后一帧不带换行）与多字节字符冲刷——decode 残余并入 buf 统一走行解析，
+  // 不再直接拼进 content（此前尾字节绕过 doneFlag/行解析，流中途截断时正文混入杂质）
+  buf += decoder.decode();
   if (buf.trim()) handleLine(buf); // [DONE] 后残留 usage 尾帧仍吸收（正文/推理已被 doneFlag 拦截）
 
   const toolCalls = [...calls.entries()]

package/src/routing.js

@@ -9,7 +9,7 @@
 import crypto from 'node:crypto';
 import { modelPreset } from './models.js';
 
-export function routingConfig(cfg) {
+export function routingConfig(/** @type {any} */ cfg) {
   const r = cfg?.routing;
   if (!r || r.enabled === false) return null;
   const planner = r.planner || 'deepseek-v4-pro';
@@ -19,19 +19,19 @@ export function routingConfig(cfg) {
 }
 
 const PLAN_HINTS =
-  /设计|架构|重构|审查|规划|分析|方案|评估|优化|排查|疑难|报错|怎么修|修复|设计模式|选型|技术债|roadmap|review|design|refactor|plan|architecture|方案设计|评审/;
+  /设计|架构|重构|审查|规划|分析|方案|评估|优化|排查|疑难|报错|怎么修|修复|设计模式|选型|技术债|roadmap|review|design|refactor|plan|architecture|方案设计|评审|fix|analyze|analyse|evaluate|audit|optimize|bug|issue|error|performance/i;
 
 // 生成类任务（游戏/网页/文档等）需要大输出（planner 32K vs executor 8K），即使短句也路由 planner
 const GENERATION_HINTS =
-  /(生成|制作|编写|创建|写|开发|实现|做).{0,30}(游戏|网页|页面|网站|应用|程序|文档|报告|简历|PPT|演示|完整|详细|小工具)|网页版|游戏/;
+  /(生成|制作|编写|创建|写|开发|实现|做|make|build|create|generate|write|implement|develop).{0,30}(游戏|网页|页面|网站|应用|程序|文档|报告|简历|PPT|演示|完整|详细|小工具|game|website|page|site|app|program|document|report|resume|ppt|tool)|网页版|游戏|webpage|website/i;
 
-export function heuristicRoute(text, rc) {
+export function heuristicRoute(/** @type {any} */ text, /** @type {any} */ rc) {
   const s = String(text ?? '');
   if (GENERATION_HINTS.test(s)) return rc.planner; // 生成类：大输出优先
   if (PLAN_HINTS.test(s)) {
     // 规划类关键词优先（审计：此前要求 length>=40，导致「设计一个缓存方案」这类
     // 13 字短句被误路由到 flash 硬扛——关键词强度优先于文本长度）
-    return s.length >= 40 || /设计|规划|分析|评估|审查|架构|重构|方案|优化|报错|修复/.test(s) ? rc.planner : null;
+    return s.length >= 40 || /设计|规划|分析|评估|审查|架构|重构|方案|优化|报错|修复|fix|analy|review|design|plan|optimiz|refactor|evaluat|audit|error|bug/i.test(s) ? rc.planner : null;
   }
   if (s.length <= 60) return rc.executor;
   return null; // 需要分类器
@@ -41,7 +41,7 @@ export function heuristicRoute(text, rc) {
 const ROUTE_CACHE_MAX = 100;
 const routeCache = new Map();
 
-export async function routeTask({ cfg, provider, currentModel, text, sticky = null, sessionStats = null }) {
+export async function routeTask(/** @type {any} */ { cfg, provider, currentModel, text, sticky = null, sessionStats = null }) {
   const rc = routingConfig(cfg);
   if (!rc) return { model: currentModel, reason: null };
   // 当前模型已在路由池外（用户手动指定）：不干预
@@ -59,7 +59,7 @@ export async function routeTask({ cfg, provider, currentModel, text, sticky = nu
   // 会话粘滞 + 升级检测（Hermes C2）：执行类会话不再逐轮分类（生成类关键词已在启发式拦截），
   // 但会话内复杂度信号累积（工具步数/截断次数）时允许升级 planner——「开头简单、中途复杂」不再被 flash 硬扛。
   if (sticky === rc.executor) {
-    const stats = sessionStats || {};
+    const stats = /** @type {any} */ (sessionStats || {});
     const steps = Number(stats.steps) || 0;
     const truncated = Number(stats.truncated) || 0;
     const UPGRADE_STEPS = Number(cfg?.routing?.upgradeSteps) || 10;
@@ -140,7 +140,7 @@ export async function routeTask({ cfg, provider, currentModel, text, sticky = nu
 }
 
 // 子代理模型选择：路由开启时固定 executor
-export function subagentModel(cfg, currentModel) {
+export function subagentModel(/** @type {any} */ cfg, /** @type {any} */ currentModel) {
   const rc = routingConfig(cfg);
   if (!rc) return currentModel;
   return modelPreset(rc.executor) ? rc.executor : currentModel;

package/src/schedule.js

@@ -11,7 +11,7 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { startTask, readTask, killTask } from './tasks.js';
 
-function isRunningTask(home, taskId) {
+function isRunningTask(/** @type {any} */ home, /** @type {any} */ taskId) {
   const t = readTask(home, taskId);
   return Boolean(t && t.status === 'running');
 }
@@ -21,21 +21,21 @@ const CLI_PATH = fileURLToPath(new URL('./cli.js', import.meta.url));
 import { isPeakHour, deferToOffpeak } from './pricing.js';
 import { atomicWriteFileSync, withFileLockSync } from './atomic-write.js';
 
-export function scheduleDir(home) {
+export function scheduleDir(/** @type {any} */ home) {
   return path.join(home, 'schedule');
 }
 
-export function parseInterval(s) {
+export function parseInterval(/** @type {any} */ s) {
   const m = /^(\d+)(s|m|h|d)$/.exec(String(s).trim());
   if (!m) return null;
   const n = Number(m[1]);
-  const unit = { s: 1000, m: 60000, h: 3600000, d: 86400000 }[m[2]];
+  const unit = /** @type {Record<string, number>} */ ({ s: 1000, m: 60000, h: 3600000, d: 86400000 })[m[2]];
   if (!(n > 0)) return null;
   return n * unit;
 }
 
 // 解析 --at：'YYYY-MM-DD HH:MM' 或 'HH:MM'（今天；已过则明天）
-export function parseAt(s) {
+export function parseAt(/** @type {any} */ s) {
   const t = String(s).trim();
   const full = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2})$/.exec(t);
   if (full) {
@@ -56,7 +56,7 @@ export function parseAt(s) {
   return null;
 }
 
-export function listSchedules(home) {
+export function listSchedules(/** @type {any} */ home) {
   const dir = scheduleDir(home);
   let files;
   try {
@@ -74,11 +74,11 @@ export function listSchedules(home) {
   return out.sort((a, b) => (a.nextRunAt || 0) - (b.nextRunAt || 0));
 }
 
-function isValidScheduleId(id) {
+function isValidScheduleId(/** @type {any} */ id) {
   return typeof id === 'string' && /^[a-z0-9]+$/.test(id) && id.length >= 2 && id.length <= 40;
 }
 
-export function readSchedule(home, id) {
+export function readSchedule(/** @type {any} */ home, /** @type {any} */ id) {
   if (!isValidScheduleId(id)) return null; // 防 id 路径穿越
   try {
     return JSON.parse(fs.readFileSync(path.join(scheduleDir(home), id + '.json'), 'utf8'));
@@ -87,7 +87,7 @@ export function readSchedule(home, id) {
   }
 }
 
-export function writeSchedule(home, job) {
+export function writeSchedule(/** @type {any} */ home, /** @type {any} */ job) {
   if (!isValidScheduleId(job?.id)) return null;
   fs.mkdirSync(scheduleDir(home), { recursive: true });
   const target = path.join(scheduleDir(home), job.id + '.json');
@@ -96,7 +96,7 @@ export function writeSchedule(home, job) {
 }
 
 /** 新建调度任务；after: 依赖的任务 ID（全部成功后才启动，任一失败则跳过） */
-export function addSchedule(home, question, /** @type {any} */ { at, every, after, permission, model, cwd, anchor, offpeak }) {
+export function addSchedule(/** @type {any} */ home, /** @type {any} */ question, /** @type {any} */ { at, every, after, permission, model, cwd, anchor, offpeak }) {
   const id = 'sc' + Date.now().toString(36) + Math.random().toString(36).slice(2, 5);
   const interval = every != null ? parseInterval(every) : null;
   const afterList = Array.isArray(after) ? after.filter(Boolean).map(String) : after ? String(after).split(',').map((x) => x.trim()).filter(Boolean) : [];
@@ -147,7 +147,7 @@ export function addSchedule(home, question, /** @type {any} */ { at, every, afte
 // 质检 H2（pause 失效确定性回归）：runOnce 返回后的状态决策抽为纯函数——
 // 用户在执行期间 pause/remove 的指令（paused/failed/文件已删）绝不被 pending 覆盖；
 // 连续失败 3 次熔断；否则排下一次（锚点对齐避免逐日漂移）。
-export function postRunStatus(cur2, result) {
+export function postRunStatus(/** @type {any} */ cur2, /** @type {any} */ result) {
   if (!cur2) return null;
   if (cur2.status === 'paused' || cur2.status === 'failed') return null;
   if (result !== 'done' && (cur2.consecutiveFailures || 0) >= 3) {
@@ -157,14 +157,14 @@ export function postRunStatus(cur2, result) {
   return { status: 'pending', nextRunAt: next };
 }
 
-export function removeSchedule(home, id) {
+export function removeSchedule(/** @type {any} */ home, /** @type {any} */ id) {
   // 质检 H3：读-改-写序列加锁，与 sleeper 循环的状态写互斥（防丢更新）
   return withFileLockSync(path.join(scheduleDir(home), '.lock'), () => {
     const job = readSchedule(home, id);
     if (!job) return false;
     if (job.pid) {
       const owned = pidOwnedBy(job.pid, id); // 质检 M11：cmdline 含调度 id 才 kill
-      if (owned !== false) {
+      if (owned === true) { // 非 Linux/无法校验（null）不盲杀（CodeBuddy 报告：PID 复用误杀风险）
         try {
           process.kill(job.pid, 'SIGTERM');
         } catch {}
@@ -179,14 +179,14 @@ export function removeSchedule(home, id) {
   });
 }
 
-export function pauseSchedule(home, id) {
+export function pauseSchedule(/** @type {any} */ home, /** @type {any} */ id) {
   // 质检 H3：读-改-写序列加锁（pause 与 sleeper 的 postRunStatus 写互斥，杜绝 pause 被覆盖）
   return withFileLockSync(path.join(scheduleDir(home), '.lock'), () => {
     const job = readSchedule(home, id);
     if (!job) return false;
     if (job.pid) {
       const owned = pidOwnedBy(job.pid, id); // 质检 M11：cmdline 含调度 id 才 kill
-      if (owned !== false) {
+      if (owned === true) { // 非 Linux/无法校验（null）不盲杀（CodeBuddy 报告：PID 复用误杀风险）
         try {
           process.kill(job.pid, 'SIGTERM');
         } catch {}
@@ -198,7 +198,7 @@ export function pauseSchedule(home, id) {
   });
 }
 
-export function resumeSchedule(home, id) {
+export function resumeSchedule(/** @type {any} */ home, /** @type {any} */ id) {
   const job = readSchedule(home, id);
   if (!job || job.status !== 'paused') return false;
   let next = job.nextRunAt;
@@ -215,7 +215,7 @@ export function resumeSchedule(home, id) {
 }
 
 // 每日锚点：锚点时刻（HH:MM）对齐到 now 之后的最近一次
-function nextAnchorAfter(anchor, interval) {
+function nextAnchorAfter(/** @type {any} */ anchor, /** @type {any} */ interval) {
   const a = parseAt(anchor);
   if (a == null) return null;
   let n = a;
@@ -224,7 +224,7 @@ function nextAnchorAfter(anchor, interval) {
 }
 
 // 链式编排：A→B→C，后者依赖前者成功
-export function chainSchedules(home, questions, opts = {}) {
+export function chainSchedules(/** @type {any} */ home, /** @type {any} */ questions, opts = {}) {
   const ids = [];
   let prev = null;
   for (const q of questions) {
@@ -237,7 +237,7 @@ export function chainSchedules(home, questions, opts = {}) {
   return { ids };
 }
 
-export function sleeperAlive(pid) {
+export function sleeperAlive(/** @type {any} */ pid) {
   if (!pid) return false;
   try {
     process.kill(pid, 0);
@@ -247,7 +247,7 @@ export function sleeperAlive(pid) {
   }
 }
 
-function spawnSleeper(home, job) {
+function spawnSleeper(/** @type {any} */ home, /** @type {any} */ job) {
   const child = spawn(process.execPath, [CLI_PATH, 'schedule-worker', job.id], {
     detached: true,
     stdio: 'ignore',
@@ -260,12 +260,12 @@ function spawnSleeper(home, job) {
 }
 
 // —— 单守护进程调度器（评估 P3-5）：一进程监督全部任务 ——
-export function daemonPidFile(home) {
+export function daemonPidFile(/** @type {any} */ home) {
   return path.join(scheduleDir(home), 'daemon.pid');
 }
 // pid 文件内容 "pid nonce"：校验进程存在 + 命令行含同一 nonce，防止陈旧 PID 被无关进程复用而误判（审计 P2-7）
 // 质检 M11：kill 前校验 PID 归属（/proc/<pid>/cmdline 含 needle 才动手，防 PID 复用误杀）
-function pidOwnedBy(pid, needle) {
+function pidOwnedBy(/** @type {any} */ pid, /** @type {any} */ needle) {
   try {
     const cmdline = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf8');
     return cmdline.includes(needle);
@@ -274,7 +274,7 @@ function pidOwnedBy(pid, needle) {
   }
 }
 
-export function daemonAlive(home) {
+export function daemonAlive(/** @type {any} */ home) {
   try {
     const [pidStr, nonce] = fs.readFileSync(daemonPidFile(home), 'utf8').trim().split(/\s+/);
     const pid = Number(pidStr);
@@ -291,7 +291,7 @@ export function daemonAlive(home) {
     return false;
   }
 }
-export function stopDaemon(home) {
+export function stopDaemon(/** @type {any} */ home) {
   try {
     const pid = Number(fs.readFileSync(daemonPidFile(home), 'utf8'));
     if (pid) {
@@ -305,7 +305,7 @@ export function stopDaemon(home) {
   } catch {}
   return true;
 }
-export function spawnDaemon(home) {
+export function spawnDaemon(/** @type {any} */ home) {
   if (daemonAlive(home)) return true;
   const nonce = Math.random().toString(36).slice(2, 10);
   const child = spawn(process.execPath, [CLI_PATH, 'schedule-daemon', nonce], {
@@ -324,7 +324,7 @@ export function spawnDaemon(home) {
 }
 
 // 重启自愈：有非终态任务且 daemon 不在 → 拉起单守护（失败才回退旧式逐任务 sleeper）
-export function reconcileSchedules(home) {
+export function reconcileSchedules(/** @type {any} */ home) {
   const jobs = listSchedules(home);
   const hasPending = jobs.some((j) => j.status === 'pending' || j.status === 'running');
   if (!hasPending) return;
@@ -343,14 +343,14 @@ export function reconcileSchedules(home) {
   spawnDaemon(home);
 }
 // —— sleeper 主循环（schedule-worker 进程内运行）——
-export async function runSleeper(home, id) {
+export async function runSleeper(/** @type {any} */ home, /** @type {any} */ id) {
   const job = readSchedule(home, id);
   if (!job) return;
 
-  const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+  const wait = (/** @type {any} */ ms) => new Promise((r) => setTimeout(r, ms));
 
   // 依赖检查：支持两种依赖——调度任务 id（chain 编排）或后台任务 id（mingdao run 输出）
-  async function depsSatisfied(deps) {
+  async function depsSatisfied(/** @type {any} */ deps) {
     for (const dep of deps) {
       const sch = readSchedule(home, dep);
       if (sch) {
@@ -476,7 +476,7 @@ export async function runSleeper(home, id) {
   }
 }
 
-export function formatScheduleRow(j) {
+export function formatScheduleRow(/** @type {any} */ j) {
   const mark = j.status === 'pending' ? '⏳' : j.status === 'running' ? '▶' : j.status === 'paused' ? '⏸' : j.status === 'done' ? '✓' : '✖';
   const when =
     j.kind === 'every'

package/src/session-index.js

@@ -25,6 +25,7 @@ export function loadSessionIndex() {
   }
 }
 
+/** @param {any} idx */
 export function saveSessionIndex(idx) {
   try {
     ensureHome();
@@ -34,9 +35,10 @@ export function saveSessionIndex(idx) {
 }
 
 // 分词：ASCII 词（小写）+ 中文 bigram + 中文单字；返回 Map<词, 次数>
+/** @param {any} text */
 export function tokenize(text) {
   const terms = new Map();
-  const add = (t) => {
+  const add = (/** @type {any} */ t) => {
     if (t) terms.set(t, (terms.get(t) || 0) + 1);
   };
   const s = String(text ?? '');
@@ -61,6 +63,7 @@ export function tokenize(text) {
 }
 
 // 从会话文件提取可检索文本（user/assistant 内容拼接）
+/** @param {any} file */
 export function extractSessionText(file) {
   const parts = [];
   for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
@@ -79,6 +82,7 @@ export function extractSessionText(file) {
 }
 
 // 增量同步索引（对比 mtime/size，只重算变化的文件；清理已删除条目）
+/** @param {any} home @param {any} sessions */
 export function syncSessionIndex(home, sessions) {
   const idx = loadSessionIndex();
   const dir = path.join(home, 'sessions');

package/src/session.js

@@ -4,6 +4,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+/** @param {any} home */
 export function listSessions(home) {
   const dir = path.join(home, 'sessions');
   try {
@@ -20,10 +21,12 @@ export function listSessions(home) {
   }
 }
 
+/** @param {any} home */
 export function latestSession(home) {
   return listSessions(home)[0] || null;
 }
 
+/** @param {any} home */
 export function createSession(home) {
   const dir = path.join(home, 'sessions');
   fs.mkdirSync(dir, { recursive: true });
@@ -33,18 +36,21 @@ export function createSession(home) {
   return { file, name: path.basename(file) };
 }
 
+/** @param {any} file @param {any} messages */
 export function appendMessages(file, messages) {
   if (!messages?.length) return;
-  const lines = messages.map((m) => JSON.stringify(m)).join('\n') + '\n';
+  const lines = messages.map((/** @type {any} */ m) => JSON.stringify(m)).join('\n') + '\n';
   fs.appendFileSync(file, lines);
 }
 
 // 整文件原子重写：自动压缩后把会话文件同步为压缩形态（否则每次加载历史都会重新触发压缩）
+/** @param {any} file @param {any} messages */
 export function rewriteSession(file, messages) {
-  const lines = messages.map((m) => JSON.stringify(m)).join('\n');
+  const lines = messages.map((/** @type {any} */ m) => JSON.stringify(m)).join('\n');
   atomicWriteFileSync(file, lines + (lines ? '\n' : ''), { mode: 0o600 }); // 质检 H4：会话文件原子写
 }
 
+/** @param {any} file */
 export function loadSession(file) {
   const raw = fs.readFileSync(file, 'utf8');
   const messages = [];
@@ -61,6 +67,7 @@ export function loadSession(file) {
 }
 
 // 会话预览：第一条用户消息（用于会话选择器）
+/** @param {any} file */
 export function sessionPreview(file) {
   try {
     const raw = fs.readFileSync(file, 'utf8');
@@ -79,6 +86,7 @@ export function sessionPreview(file) {
   }
 }
 
+/** @param {any} mtime */
 export function relativeTime(mtime) {
   const diff = Date.now() - mtime;
   if (diff < 60000) return '刚刚';
@@ -92,6 +100,7 @@ export function relativeTime(mtime) {
 import { syncSessionIndex, tokenize, extractSessionText } from './session-index.js';
 import { atomicWriteFileSync } from './atomic-write.js';
 
+/** @param {any} home @param {any} keyword */
 export function searchSessions(home, keyword, { limit = 20 } = {}) {
   const kw = String(keyword ?? '').trim();
   if (!kw) return listSessions(home).slice(0, limit);