weaver-work-cli 0.1.38 → 0.1.40

package/dist/shortcuts/workflow/operations/todoSmartConvert/aigroupRules.js

@@ -12,7 +12,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { stateRoot } from '../../../../core/state.js';
-import { cacheRoots } from './summaryCache.js';
+import { resolveSkillDir } from './summaryCache.js';
 export const AIGROUP_DIR_NAME = 'aigroup';
 export const DEFAULT_RULE_FILE = 'default.json';
 export const USER_INTENT_RULE_FILE = 'user-intents.json';
@@ -30,6 +30,7 @@ export const FALLBACK_DEFAULTS = {
     summaryMaxChars: 150,
     groupSummaryMaxChars: 100,
     groupSummaryTail: '可展开逐条查看或直接汇总处理',
+    excludeOriginFormDataFields: [],
 };
 export function emptyRuleFile(error = null) {
     return {
@@ -66,16 +67,79 @@ function validateFocusKeyword(raw, index) {
         return `focusKeyword[${index}] 必须是 [指标, 算子, 值] 三元组`;
     return null;
 }
+/** 校验排除字段清单：缺省放行；给了就必须是字符串或字符串数组（允许空数组）。 */
+function validateExcludeFields(raw, where) {
+    if (raw === undefined)
+        return null;
+    if (typeof raw === 'string') {
+        return raw.trim() === '' ? `${where} 不能是空字符串（不排除就别给这个键）` : null;
+    }
+    if (!Array.isArray(raw))
+        return `${where} 必须是字符串数组`;
+    for (const item of raw) {
+        if (typeof item !== 'string' || item.trim() === '')
+            return `${where} 的每一项都必须是非空字符串`;
+    }
+    return null;
+}
 /** 校验整份规则文件；返回错误列表（空数组 = 合法）。 */
 export function validateRuleFile(raw) {
     const errors = [];
     const file = raw;
     if (!file || typeof file !== 'object')
         return ['规则文件必须是 JSON 对象'];
+    // schemaVersion：不能是废字段。给值时必须受支持（2 = aigroup set 写入的意图文件，3 = default.json）；缺省允许（规则级校验兼容）。
+    if (file.schemaVersion !== undefined && file.schemaVersion !== 2 && file.schemaVersion !== 3) {
+        errors.push(`schemaVersion 只支持 2 或 3，收到 ${JSON.stringify(file.schemaVersion ?? null)}`);
+    }
     if (!Array.isArray(file.rules)) {
         errors.push('rules 必须是数组');
         return errors;
     }
+    // generalRules（2026-11-03）：可选区块，只做宽松类型校验；未知键忽略（向后兼容预留扩展）。
+    if (file.generalRules !== undefined) {
+        if (!file.generalRules || typeof file.generalRules !== 'object' || Array.isArray(file.generalRules)) {
+            errors.push('generalRules 必须是对象');
+        }
+        else {
+            const identity = file.generalRules.identityFilter;
+            if (identity !== undefined) {
+                if (!identity || typeof identity !== 'object' || Array.isArray(identity)) {
+                    errors.push('generalRules.identityFilter 必须是对象');
+                }
+                else if (identity.defaultIsremarks !== undefined
+                    && !/^\d+(,\d+)*$/.test(String(identity.defaultIsremarks).trim())) {
+                    errors.push('generalRules.identityFilter.defaultIsremarks 必须是「数字逗号拼接」格式，如 0,1,2');
+                }
+                if (identity?.excludedCodes !== undefined
+                    && (!Array.isArray(identity.excludedCodes)
+                        || identity.excludedCodes.some((c) => !/^\d+$/.test(String(c))))) {
+                    errors.push('generalRules.identityFilter.excludedCodes 必须是数字码数组');
+                }
+            }
+            const priority = file.generalRules.priorityGroup;
+            if (priority !== undefined) {
+                if (!priority || typeof priority !== 'object' || Array.isArray(priority)) {
+                    errors.push('generalRules.priorityGroup 必须是对象');
+                }
+                else {
+                    if (priority.title !== undefined && (typeof priority.title !== 'string' || !priority.title.trim())) {
+                        errors.push('generalRules.priorityGroup.title 必须是非空字符串');
+                    }
+                    if (priority.rules !== undefined) {
+                        const KNOWN_PRIORITY_RULES = ['overdue', 'levelFallback'];
+                        if (!Array.isArray(priority.rules) || priority.rules.length === 0
+                            || priority.rules.some((r) => !KNOWN_PRIORITY_RULES.includes(String(r)))) {
+                            errors.push(`generalRules.priorityGroup.rules 只支持 ${KNOWN_PRIORITY_RULES.join('、')}`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    const defaultsExclude = validateExcludeFields(file.defaults?.excludeOriginFormDataFields, 'defaults.excludeOriginFormDataFields');
+    if (defaultsExclude)
+        errors.push(defaultsExclude);
     const seen = new Set();
     file.rules.forEach((rule, index) => {
         if (!rule || typeof rule !== 'object') {
@@ -98,6 +162,16 @@ export function validateRuleFile(raw) {
         if (rule.summaryMaxChars !== undefined && (typeof rule.summaryMaxChars !== 'number' || rule.summaryMaxChars <= 0)) {
             errors.push(`rules[${index}].summaryMaxChars 必须是正数`);
         }
+        const excludeReason = validateExcludeFields(rule.excludeOriginFormDataFields, `rules[${index}].excludeOriginFormDataFields`);
+        if (excludeReason)
+            errors.push(excludeReason);
+        if (rule.summaryRequiredFields !== undefined) {
+            if (!Array.isArray(rule.summaryRequiredFields) || rule.summaryRequiredFields.length === 0
+                || rule.summaryRequiredFields.some((f) => typeof f !== 'string' || !f.trim() || f.trim().length > 50)
+                || rule.summaryRequiredFields.length > 20) {
+                errors.push(`rules[${index}].summaryRequiredFields 必须是非空字符串数组（1~20 项、每项 1~50 字）`);
+            }
+        }
         const groupRule = rule.aiGroup?.groupRule;
         if (groupRule) {
             if (typeof groupRule.focus !== 'boolean')
@@ -162,47 +236,42 @@ export function loadRuleFile(file) {
         return emptyRuleFile(`规则文件校验失败：${errors.join('；')}`);
     return { file: parsed, error: null };
 }
-/** 默认规则目录（**随 skill 分发、只读**）：`WEAVER_WORK_CLI_AIGROUP_DIR` → skill 目录下的 `aigroup/` → CLI 状态目录。 */
-export function aigroupDir(ctx) {
-    const explicit = process.env.WEAVER_WORK_CLI_AIGROUP_DIR?.trim();
-    if (explicit)
-        return join(explicit);
-    const roots = cacheRoots(ctx);
-    return roots.skillDir ? join(roots.skillDir, AIGROUP_DIR_NAME) : join(stateRoot(ctx), AIGROUP_DIR_NAME);
-}
 /**
- * 用户意图目录（**运行时产物，绝不写进 skill 目录**）：`WEAVER_WORK_CLI_AIGROUP_DIR` → CLI 状态目录。
- *
- * 刻意与 `aigroupDir()` 分开：意图文件是本机产生的，一旦落在 skill 目录里，
- * 打包/安装时会跟着 skill 跑到别人机器上（既是泄漏，也会污染别人的分组口径）。
+ * 当前 skill 的 aigroup 目录（`default.json` 与 `user-intents.json` 同目录；
+ * 2026-11-01 用户定稿：规则与意图都锚定**当前 agent 的 skill 目录**）。
+ * 裸 CLI（无当前 skill 上下文）返回 null ⇒ 规则不加载、意图不可读写。
  */
+export function aigroupDir(ctx) {
+    const skillDir = resolveSkillDir();
+    return skillDir ? join(skillDir, AIGROUP_DIR_NAME) : null;
+}
+/** 用户意图目录：与 `default.json` 同目录（见 `aigroupDir`）。 */
 export function aigroupUserDir(ctx) {
-    const explicit = process.env.WEAVER_WORK_CLI_AIGROUP_DIR?.trim();
-    if (explicit)
-        return join(explicit);
-    return join(stateRoot(ctx), AIGROUP_DIR_NAME);
+    return aigroupDir(ctx);
 }
 /**
  * 加载并合并规则：默认文件 +（可选）用户意图文件（**同 workflowName 整条覆盖**，系统默认不被覆盖）。
  * 用户意图文件里的条目按 `workflowName` 粒度替换默认条目，缺字段由 defaults 补。
+ * 裸 CLI（无当前 skill 上下文）⇒ 按无规则处理 + warning（缓存与规则都拒绝，见 cacheRoots）。
  */
 export function loadRules(options = {}) {
-    const dir = options.dir ?? aigroupDir(options.ctx);
-    // 显式 `dir` 时（测试/现场）默认文件与意图文件放一起；否则意图文件只从状态目录读。
-    const userDir = options.dir ?? aigroupUserDir(options.ctx);
     const warnings = [];
+    const dir = options.dir ?? aigroupDir(options.ctx);
+    if (!dir) {
+        warnings.push('无当前 skill 上下文（WEAVER_WORK_CLI_SKILL_DIR 未设置）：aigroup 规则未加载，按无规则处理');
+        return { file: emptyRuleFile(null).file, warnings, dir: null };
+    }
     const base = loadRuleFile(join(dir, DEFAULT_RULE_FILE));
     if (base.error)
         warnings.push(base.error);
     const rules = [...base.file.rules];
-    // 兼容迁移：意图文件原先写在 skill 目录里，改到状态目录后老文件不会被自动搬走；
-    // 状态目录没有时就回读老位置，避免用户已有的意图「凭空消失」。
-    const userIntentFile = join(userDir, USER_INTENT_RULE_FILE);
-    const legacyIntentFile = join(dir, USER_INTENT_RULE_FILE);
+    // 意图文件与 default.json 同目录；兼容迁移：老位置（CLI 状态目录）若存在且新位置没有 ⇒ 回读 + 提示
+    const userIntentFile = join(dir, USER_INTENT_RULE_FILE);
+    const legacyIntentFile = join(stateRoot(options.ctx), AIGROUP_DIR_NAME, USER_INTENT_RULE_FILE);
     let intentFile = userIntentFile;
     if (!options.dir && !existsSync(userIntentFile) && existsSync(legacyIntentFile)) {
         intentFile = legacyIntentFile;
-        warnings.push(`用户意图仍读自 skill 目录（${legacyIntentFile}）：新位置是 ${userIntentFile}，重新执行 aigroup set 即可迁移`);
+        warnings.push(`用户意图仍读自 CLI 状态目录（${legacyIntentFile}）：新位置是 ${userIntentFile}，重新执行 aigroup set 即可迁移`);
     }
     const intent = loadRuleFile(intentFile);
     if (intent.error) {
@@ -225,7 +294,13 @@ export function loadRules(options = {}) {
         }
     }
     return {
-        file: { schemaVersion: base.file.schemaVersion, defaults: { ...FALLBACK_DEFAULTS, ...base.file.defaults }, rules },
+        file: {
+            schemaVersion: base.file.schemaVersion,
+            defaults: { ...FALLBACK_DEFAULTS, ...base.file.defaults },
+            rules,
+            // 通用规则区（2026-11-03）：仅取 default.json 的定义；用户意图文件不参与通用规则
+            ...(base.file.generalRules ? { generalRules: base.file.generalRules } : {}),
+        },
         warnings,
         dir,
     };
@@ -274,13 +349,16 @@ export function resolveRule(file, workflowName) {
             summaryMaxChars: raw.summaryMaxChars ?? defaults.summaryMaxChars,
             groupSummaryMaxChars: defaults.groupSummaryMaxChars,
             groupSummaryTail: defaults.groupSummaryTail,
+            // 显式给 `[]` = 规则级覆盖（清空 defaults 的清单）；未给才落 defaults
+            excludeOriginFormDataFields: raw.excludeOriginFormDataFields === undefined
+                ? defaults.excludeOriginFormDataFields
+                : asStringArray(raw.excludeOriginFormDataFields) ?? [],
             aiGroup: raw.aiGroup
                 ? {
                     groupSummary: {
                         needAI: groupSummary?.needAI ?? false,
                         ...(groupSummary?.prompt === undefined ? {} : { prompt: groupSummary.prompt }),
                         ...(groupSummary?.template === undefined ? {} : { template: groupSummary.template }),
-                        maxChars: defaults.groupSummaryMaxChars,
                         tail: defaults.groupSummaryTail,
                     },
                     groupRule: groupRule ?? EMPTY_GROUP_RULE,
@@ -441,8 +519,32 @@ export function activeRuleFor(workflowName) {
         return null;
     return resolveRule(activeRules(), name)?.rule ?? null;
 }
+/** 通用规则区（2026-11-03）：未配置返回 null，消费方按内置默认兜底。 */
+export function generalRules() {
+    return activeRules().generalRules ?? null;
+}
 /** 清空进程内缓存（单测用）。 */
 export function resetActiveRules() {
     activeFile = null;
     activeDir = null;
 }
+// ---------------------------------------------------------------------------
+// formData 排除字段（2026-10-30 用户定稿：excludeOriginFormDataFields）
+// ---------------------------------------------------------------------------
+/**
+ * 当前生效规则的 formData 排除字段清单（空数组 = 不排除）。
+ *
+ * 消费方：`todoDetailFetcher.fetchOneDetail` —— 拿到接口 formData 后按 fieldName 精确匹配剔除；
+ * 详情缓存用 `excludeTagFor()` 做**口径失效**：清单一变，旧缓存条目整体 miss。
+ */
+export function excludeFieldsFor(workflowName) {
+    return activeRuleFor(workflowName)?.excludeOriginFormDataFields ?? [];
+}
+/** 排除清单的特征串（原文拼接）。规则没配 = 空串，与「无口径」条目互相匹配。 */
+export function excludeTagOf(fields) {
+    return [...fields].join('\u0001');
+}
+/** 便捷组合：某流程当前生效的排除口径特征串。 */
+export function excludeTagFor(workflowName) {
+    return excludeTagOf(excludeFieldsFor(workflowName));
+}

package/dist/shortcuts/workflow/operations/todoSmartConvert/aigroupStore.js

@@ -44,6 +44,8 @@ function namesOf(rule) {
  */
 export function saveUserIntents(payload, options = {}) {
     const dir = options.dir ?? aigroupUserDir(options.ctx);
+    if (!dir)
+        throw workflowValidationError('aigroup_no_skill_context', '无当前 skill 上下文（WEAVER_WORK_CLI_SKILL_DIR 未设置）：用户意图不可读写');
     const warnings = [];
     const entries = normalizeIntentPayload(payload);
     if (entries.length === 0)
@@ -86,6 +88,8 @@ export function saveUserIntents(payload, options = {}) {
 /** 读用户意图文件（诊断/展示用）。 */
 export function readUserIntents(options = {}) {
     const dir = options.dir ?? aigroupUserDir(options.ctx);
+    if (!dir)
+        return { dir: null, file: '', exists: false, error: '无当前 skill 上下文（WEAVER_WORK_CLI_SKILL_DIR 未设置）', rules: [] };
     const file = join(dir, USER_INTENT_RULE_FILE);
     if (!existsSync(file))
         return { dir, file, exists: false, error: null, rules: [] };
@@ -95,6 +99,8 @@ export function readUserIntents(options = {}) {
 /** 清空用户意图（只删内容、不删文件，保持目录结构）。 */
 export function clearUserIntents(options = {}) {
     const dir = options.dir ?? aigroupUserDir(options.ctx);
+    if (!dir)
+        throw workflowValidationError('aigroup_no_skill_context', '无当前 skill 上下文（WEAVER_WORK_CLI_SKILL_DIR 未设置）：用户意图不可读写');
     const file = join(dir, USER_INTENT_RULE_FILE);
     mkdirSync(dir, { recursive: true, mode: 0o700 });
     writeFileSync(file, `${JSON.stringify({ schemaVersion: 2, rules: [] }, null, 2)}\n`, { mode: 0o600 });

package/dist/shortcuts/workflow/operations/todoSmartConvert/summaryCache.js

@@ -1,8 +1,6 @@
-import { existsSync, readdirSync, statSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { stateRoot } from '../../../../core/state.js';
 /**
  * `todoSmartConvert` 的**单条摘要缓存**（放在 Agent 真实 skill 目录下）。
  *
@@ -18,21 +16,13 @@ import { stateRoot } from '../../../../core/state.js';
  * 流程有了新反馈（lastFeedBackDateTime 变化）key 就变了，摘要自然失效、重新生成——
  * 用业务时间做版本号，比记录「摘要生成时间」更准。
  *
- * 目录定位顺序：`WEAVER_WORK_CLI_CACHE_DIR`（直接指定缓存目录，测试用）→
- * `WEAVER_WORK_CLI_SKILL_DIR`（直接指定 skill 目录）→ 已知 Agent 的全局 skill 根目录
- * （`~/.workbuddy/skills`、`~/.claude/skills` …）→ 全部不存在时退回 CLI 状态目录（并在 warnings 里说明）。
+ * 目录定位（2026-11-01 用户定稿：**缓存的生成与提取都取自当前 skill 自己的 `cache/`**）：
+ * `WEAVER_WORK_CLI_SKILL_DIR`（tools 脚本把自身所在 skill 目录显式指进来）⇒ 直接用 `<该目录>/cache`；
+ * 未设置（裸 CLI，无当前 skill 上下文）⇒ **拒绝读写缓存**（refused），调用方按「没有缓存」处理。
+ * 用户已不要求多安装发现与排名——各自 agent 独立安装一份 skill，脚本锚定自身目录即可。
  */
-/** 与 `skills/` 下发布的目录名一致。 */
-const SKILL_DIR_NAME = 'weaver-e10-workflow';
 /** skill 内的缓存子目录。 */
 const CACHE_DIR_NAME = 'cache';
-/**
- * 已知 Agent 产物的用户级根目录（按优先级）。
- *
- * 只看 `~/<agent>/skills/<skill>/SKILL.md` 是否存在——存在即认为「这个 Agent 装了这个 skill」。
- * **不看工作区里的 `.workbuddy/skills`**：项目内目录属于「本地项目」，用户明确不让缓存放那儿。
- */
-const AGENT_HOME_DIRS = ['.workbuddy', '.claude', '.codebuddy', '.codex', '.cursor', '.gemini'];
 /** 单条摘要缓存（跨任务，7 天）。 */
 export const SUMMARY_CACHE_FILE_NAME = 'todo-summary-cache.json';
 /**
@@ -42,105 +32,31 @@ export const SUMMARY_CACHE_FILE_NAME = 'todo-summary-cache.json';
  */
 export const SUMMARY_CACHE_VERSION = 2;
 function uniqueDirs(dirs) {
-    return [...new Set(dirs.filter(Boolean))];
-}
-function stateCacheDir(ctx) {
-    return resolve(stateRoot(ctx), CACHE_DIR_NAME);
+    return [...new Set(dirs.filter((dir) => Boolean(dir)))];
 }
 /**
- * 扫已知 Agent 的 skills 根，找「本 skill 的目录」——判据是 `references/todo-smart-convert.md` 存在。
- * 用于 skill 目录被改名（例如本地测试副本）后仍能定位到已攒的摘要缓存。
+ * 解析「当前 skill 目录」：只认 `WEAVER_WORK_CLI_SKILL_DIR`（tools 脚本锚定自身目录）；
+ * 未设置 = 裸 CLI，无当前 skill 上下文。
  */
-function discoverThisSkillDirs(home) {
-    const marker = join('references', 'todo-smart-convert.md');
-    const found = [];
-    for (const agent of AGENT_HOME_DIRS) {
-        const root = join(home, agent, 'skills');
-        const entries = (() => {
-            try {
-                return readdirSync(root, { withFileTypes: true });
-            }
-            catch {
-                return [];
-            }
-        })();
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            const dir = join(root, entry.name);
-            if (existsSync(join(dir, marker)))
-                found.push(dir);
-        }
-    }
-    return found;
-}
-/** 读文件 mtime（毫秒）；读不到（不存在/无权限）返回 0。 */
-function mtimeOf(file) {
-    try {
-        return statSync(file).mtimeMs;
-    }
-    catch {
-        return 0;
-    }
-}
-/**
- * 多个候选 skill 目录同时存在时，优先选择已有缓存且安装完整的目录。
- *
- * 排序键（依次比较，越小越优先）：
- *  1. 目录里**已有摘要缓存** ⇒ 优先（连续性：别把攒好的摘要换到另一份安装上）
- *  2. 有 `references/todo-smart-convert.md` ⇒ 优先（完整安装优于半解压的残目录）
- *  3. `SKILL.md` 的 mtime 更新 ⇒ 优先（刚复制/刚升级的那份大概率就是正在用的）
- *  4. 原始顺序（`WEAVER_WORK_CLI_SKILL_DIR` 指定的永远排最前）
- */
-function rankSkillDirs(dirs) {
-    const scored = dirs.map((dir, index) => ({
-        dir,
-        index,
-        hasCache: existsSync(join(dir, CACHE_DIR_NAME, SUMMARY_CACHE_FILE_NAME)) ? 1 : 0,
-        cacheMtime: mtimeOf(join(dir, CACHE_DIR_NAME, SUMMARY_CACHE_FILE_NAME)),
-        hasMarker: existsSync(join(dir, 'references', 'todo-smart-convert.md')) ? 1 : 0,
-        skillMtime: mtimeOf(join(dir, 'SKILL.md')),
-    }));
-    scored.sort((a, b) => b.hasCache - a.hasCache
-        || b.cacheMtime - a.cacheMtime
-        || b.hasMarker - a.hasMarker
-        || b.skillMtime - a.skillMtime
-        || a.index - b.index);
-    return scored.map((item) => item.dir);
+export function resolveSkillDir() {
+    const explicit = process.env.WEAVER_WORK_CLI_SKILL_DIR?.trim();
+    return explicit ? resolve(explicit) : null;
 }
 /** 定位缓存目录（不创建目录，纯路径计算）。 */
 export function cacheRoots(ctx) {
-    const fallback = stateCacheDir(ctx);
-    const explicitCache = process.env.WEAVER_WORK_CLI_CACHE_DIR?.trim();
-    if (explicitCache) {
-        const dir = resolve(explicitCache);
-        return { preferred: dir, fallback: dir, inSkillDir: false, skillDir: null };
-    }
-    const home = homedir();
-    const explicitSkill = process.env.WEAVER_WORK_CLI_SKILL_DIR?.trim();
-    const candidates = [];
-    if (explicitSkill)
-        candidates.push(resolve(explicitSkill));
-    for (const agent of AGENT_HOME_DIRS) {
-        candidates.push(join(home, agent, 'skills', SKILL_DIR_NAME));
+    void ctx;
+    const skillDir = resolveSkillDir();
+    if (!skillDir) {
+        // 裸 CLI：无当前 skill 上下文 ⇒ 缓存拒绝读写（用户 2026-11-01 定稿：拒绝执行）
+        return { preferred: null, fallback: null, inSkillDir: false, skillDir: null, refused: true };
     }
-    // 目录名可能被改（如本地测试副本 `todoSmartGroupTest`）：再按「本 skill 的特征文件」扫一遍，
-    // 避免改名后缓存落到 CLI 状态目录、把已攒的摘要全丢掉。
-    candidates.push(...discoverThisSkillDirs(home));
-    // 只认「装了本 skill」的目录，再在多份安装之间择优（见 rankSkillDirs）。
-    const installed = uniqueDirs(candidates).filter((dir) => existsSync(join(dir, 'SKILL.md')));
-    const [skillDir] = rankSkillDirs(installed);
-    if (skillDir) {
-        return {
-            preferred: join(skillDir, CACHE_DIR_NAME),
-            fallback,
-            inSkillDir: true,
-            skillDir,
-        };
-    }
-    return { preferred: fallback, fallback, inSkillDir: false, skillDir: null };
+    const cacheDir = join(skillDir, CACHE_DIR_NAME);
+    return { preferred: cacheDir, fallback: cacheDir, inSkillDir: true, skillDir, refused: false };
 }
 export async function readCacheFile(roots, fileName) {
+    // 裸 CLI（无当前 skill 上下文）：拒绝读缓存（用户 2026-11-01 定稿）
+    if (roots.refused || !roots.preferred)
+        return null;
     for (const dir of uniqueDirs([roots.preferred, roots.fallback])) {
         const file = join(dir, fileName);
         if (!existsSync(file))
@@ -161,6 +77,9 @@ export async function readCacheFile(roots, fileName) {
  * 缓存是加速设施，写不进去也绝不能让主流程失败。
  */
 export async function writeCacheFile(roots, fileName, payload) {
+    // 裸 CLI（无当前 skill 上下文）：拒绝写缓存（用户 2026-11-01 定稿）；目录不可写时静默放弃（不另设兜底）
+    if (roots.refused || !roots.preferred)
+        return null;
     for (const dir of uniqueDirs([roots.preferred, roots.fallback])) {
         const file = join(dir, fileName);
         try {
@@ -199,15 +118,29 @@ export function summaryCacheKey(requestId, lastFeedBackDateTime) {
     const stamp = String(lastFeedBackDateTime ?? '').trim();
     return `${requestId}__${stamp}`;
 }
+/** 口径提示的入库形式：trim 后原样存储；空口径返回空串（条目不落 pk 字段）。 */
+export function promptTagOf(prompt) {
+    return String(prompt ?? '').trim();
+}
 /**
- * 缓存条目是否与当前目标字数口径匹配。
+ * 缓存条目是否与当前口径/素材匹配。
  *
- * 不传 `maxChars` 时不按字数过滤；传入后必须与写入口径一致。
+ * **失效条件（2026-11-02 用户定稿）：只由 `requestSummaryPrompt`（default.json / 用户意图）调整触发**——
+ *  - `pk`：双方都存在时才比对；**条目缺 pk = 旧口径条目，兼容命中**（无法证明口径变过就不作废）；
+ *  - `maxChars`：双方都存在时才比对，且调用方只在用户**显式**传字数时才传入
+ *    （`summary.ts` 的 `explicitMaxCharsFor`）——规则/默认字数变化不作废历史摘要；
+ *    用户显式要求「10 字以内」时仍会重写（2026-10-22 实测踩坑的保护保留）；
+ *  - `dv`：详情素材特征值仍比对——素材升级 / 排除清单调整后旧摘要缺信息（如安全工单缺行号），
+ *    不能继续命中；条目缺 dv = 旧条目，兼容命中。
  */
-function entryMatchesMaxChars(entry, maxChars) {
-    if (maxChars === undefined)
-        return true;
-    return (entry.maxChars ?? 50) === maxChars;
+function entryMatches(entry, maxChars, pk, dv) {
+    if (pk !== undefined && entry.pk !== undefined && entry.pk !== pk)
+        return false;
+    if (maxChars !== undefined && entry.maxChars !== undefined && entry.maxChars !== maxChars)
+        return false;
+    if (entry.dv !== undefined && entry.dv !== dv)
+        return false;
+    return true;
 }
 function normalizeSummaryEntry(raw) {
     if (!raw || typeof raw !== 'object')
@@ -218,7 +151,15 @@ function normalizeSummaryEntry(raw) {
     if (typeof entry.cachedAt !== 'number' || !Number.isFinite(entry.cachedAt))
         return null;
     const maxChars = typeof entry.maxChars === "number" && Number.isFinite(entry.maxChars) ? entry.maxChars : undefined;
-    return { summary: entry.summary, cachedAt: entry.cachedAt, ...(maxChars === undefined ? {} : { maxChars }) };
+    const pk = typeof entry.pk === 'string' && entry.pk !== '' ? entry.pk : undefined;
+    const dv = typeof entry.dv === 'string' && entry.dv !== '' ? entry.dv : undefined;
+    return {
+        summary: entry.summary,
+        cachedAt: entry.cachedAt,
+        ...(maxChars === undefined ? {} : { maxChars }),
+        ...(pk === undefined ? {} : { pk }),
+        ...(dv === undefined ? {} : { dv }),
+    };
 }
 /**
  * 打开摘要缓存（读 + 按需清理）。
@@ -273,21 +214,21 @@ export async function openSummaryCache(ctx) {
         misses: 0,
         pruned,
         dirty: false,
-        get(requestId, lastFeedBackDateTime, maxChars) {
+        get(requestId, lastFeedBackDateTime, maxChars, pk, dv) {
             const key = summaryCacheKey(requestId, lastFeedBackDateTime);
             const entry = entries.get(key);
-            if (entry && now - entry.cachedAt <= SUMMARY_CACHE_TTL_MS && entryMatchesMaxChars(entry, maxChars)) {
+            if (entry && now - entry.cachedAt <= SUMMARY_CACHE_TTL_MS && entryMatches(entry, maxChars, pk, dv)) {
                 cache.hits += 1;
                 return entry.summary;
             }
             cache.misses += 1;
             return null;
         },
-        has(requestId, lastFeedBackDateTime, maxChars) {
+        has(requestId, lastFeedBackDateTime, maxChars, pk, dv) {
             const entry = entries.get(summaryCacheKey(requestId, lastFeedBackDateTime));
-            return entry !== undefined && entryMatchesMaxChars(entry, maxChars);
+            return entry !== undefined && entryMatches(entry, maxChars, pk, dv);
         },
-        set(requestId, lastFeedBackDateTime, summary, maxChars) {
+        set(requestId, lastFeedBackDateTime, summary, maxChars, pk, dv) {
             const text = String(summary ?? '').trim();
             if (!requestId || !text)
                 return false;
@@ -295,6 +236,8 @@ export async function openSummaryCache(ctx) {
                 summary: text,
                 cachedAt: Date.now(),
                 ...(maxChars === undefined ? {} : { maxChars }),
+                ...(pk === undefined || pk === '' ? {} : { pk }),
+                ...(dv === undefined || dv === '' ? {} : { dv }),
             });
             dirty = true;
             cache.dirty = true;

package/dist/shortcuts/workflow/operations/todoSmartConvert/todoDetailCache.js

@@ -2,11 +2,12 @@ import { cacheRoots, readCacheFile, writeCacheFile, SUMMARY_CACHE_PRUNE_INTERVAL
 /**
  * **流程详情数据缓存**（与摘要缓存并存，互不替代）。
  *
- * 规则（用户 2026-10-26 定稿）：
+ * 规则（用户 2026-10-26 定稿；条目格式 2026-10-30 升 v2）：
  *  - 键：`requestId__lastFeedBackDateTime`（与该条待办的业务时间绑定——流程一动就换键）；
  *  - 有效期：7 天，与摘要缓存一致；读的时候逻辑过期，超过清理间隔（3 天）时物理剔除；
- *  - **不设版本号**：过期条目逐条剔除、新条目直接加入，不做整份失效；
- *  - 详情为空的条目**也写**（`contextAvailable:false`），否则这类条目每次都要重拉；
+ *  - **条目带格式版本 `v`**：v2 起素材 = 排除清单过滤后的 formData + 全量 basicInfo；
+ *    旧格式条目（无 `v`）读取时视为无效，被新条目逐步覆盖；排除清单变化靠 `excludeTag` 失效；
+ *  - 详情为空的条目**也写**（`fields: []`），否则这类条目每次都要重拉；
  *  - 缓存文件缺失 ⇒ 视为从未缓存过，正常走接口。
  *
  * 位置：与摘要缓存同一个 `cache/` 目录（skill 目录优先，不可写时退回 CLI 状态目录）。
@@ -16,18 +17,53 @@ export const DETAIL_CACHE_FILE_NAME = 'todo-detail-cache.json';
 export const DETAIL_CACHE_TTL_MS = SUMMARY_CACHE_TTL_MS;
 /** 与摘要缓存一致：清理间隔 3 天。 */
 export const DETAIL_CACHE_PRUNE_INTERVAL_MS = SUMMARY_CACHE_PRUNE_INTERVAL_MS;
+/**
+ * 缓存条目格式版本。v2（2026-10-30）：
+ *  - 素材改为「排除清单过滤后的 formData `fieldName:value` + 全量 basicInfo」，
+ *    取代旧版「selectSummaryFields 投影 + 8 字段/80 字截断」；
+ *  - 新增 `excludeTag`（排除清单原文拼接）——清单一变旧条目整体失效；
+ *  - v1 条目（无 `v` 键）读取时直接视为无效并逐步被覆盖。
+ */
+export const DETAIL_CACHE_ENTRY_VERSION = 3;
 export function detailCacheKey(requestId, lastFeedBackDateTime) {
     const stamp = String(lastFeedBackDateTime ?? '').trim();
     return `${requestId}__${stamp}`;
 }
+/**
+ * 详情素材特征值（2026-11-01 根治「素材升级后旧摘要继续命中」）：对 `basicInfo + fields`
+ * 的稳定序列化做 djb2 哈希。任何素材变化——详情管线升级、`excludeOriginFormDataFields`
+ * 调整、字段增减——都会让它改变；摘要缓存条目的 `dv` 与之比对即可自动失效重写。
+ */
+export function detailMaterialTagOf(entry) {
+    const basic = entry.basicInfo ?? {};
+    const basicKeys = Object.keys(basic).sort();
+    const material = JSON.stringify([
+        basicKeys.map((key) => [key, basic[key]]),
+        (entry.fields ?? []).map((field) => [field.fieldName, field.value]),
+    ]);
+    let hash = 5381;
+    for (let i = 0; i < material.length; i += 1)
+        hash = ((hash << 5) + hash + material.charCodeAt(i)) >>> 0;
+    return hash.toString(16);
+}
 function normalizeEntry(raw) {
     if (!raw || typeof raw !== 'object')
         return null;
     const value = raw;
+    // 旧格式（v1：context + 8 字段/80 字截断）与新口径不兼容，直接视为无效
+    if (value.v !== DETAIL_CACHE_ENTRY_VERSION)
+        return null;
     if (typeof value.cachedAt !== 'number' || !Number.isFinite(value.cachedAt))
         return null;
-    if (typeof value.context !== 'string')
+    if (typeof value.excludeTag !== 'string')
         return null;
+    const basicInfo = {};
+    if (value.basicInfo && typeof value.basicInfo === 'object') {
+        for (const [key, item] of Object.entries(value.basicInfo)) {
+            if (typeof item === 'string')
+                basicInfo[key] = item;
+        }
+    }
     const fields = Array.isArray(value.fields)
         ? value.fields
             .filter((item) => Boolean(item) && typeof item.fieldName === 'string'
@@ -36,10 +72,11 @@ function normalizeEntry(raw) {
         : [];
     const metrics = value.metrics && typeof value.metrics === 'object' ? value.metrics : {};
     return {
-        context: value.context,
-        contextAvailable: value.contextAvailable === true,
-        metrics,
+        v: DETAIL_CACHE_ENTRY_VERSION,
+        basicInfo,
         fields,
+        metrics,
+        excludeTag: value.excludeTag,
         cachedAt: value.cachedAt,
     };
 }