pi-shadow-mind 0.1.22 → 0.1.23

package/DESIGN-Evolution.md

@@ -67,3 +67,9 @@
 - 发生：用户希望仅对特定主力模型（如 `gpt-6-astra`）关闭某 Shadow，而对其余模型保持启用。
 - 分析：此前仅支持全量 `*` 或显式枚举白名单，针对特定模型禁用必须穷举所有其他合法模型，配置维护成本高；应支持以 `!` 开头的排除规则，支持模型短名与 glob 通配，并在纯排除配置时默认全量模型候选。
 - 改变：`matchesModel` 区分正向与否定规则；命中任一排除规则立即过滤；纯排除列表默认继承 `*`；补充短名、通配、格式破坏与调度过滤回归。
+
+## 2026-09-21 · Shadow 会话不加载按会话记录的扩展
+
+- 发生：同时安装 Run 归档扩展 pi-experiencev2 时，用户归档的 1098 个 Run 里有 381 个（35%）来自 Shadow 会话，缺摘要率 21.0%，高于用户会话的 9.3%；摘要成功的 301 条也按 Main 的目标撰写，再因为 Shadow 只回 `NOT_RELEVANT` 判成任务未完成，在归档列表里与用户 Run 混排。Shadow 会话不走 CLI 的 `session_start` / `session_shutdown`，这类扩展的关闭路径也不触发，归档 `writers` 表残留 26 条记录。
+- 分析：Shadow 的结论本来就通过 `report_to_main` 进入 Main 会话记录，381 次运行只有 8 次产出报告，单独归档价值接近零。整体关闭扩展不可行，provider 扩展要提供模型。因此按名单排除，默认排除 `pi-experiencev2`，写 `[]` 恢复原状。匹配只能基于扩展文件路径：`DefaultResourceLoader` 先调用 `extensionsOverride`，再调用 `applyExtensionSourceInfo`，回调拿到的 `sourceInfo` 还是 `source: "local"` / `origin: "top-level"` 的占位值，`baseDir` 指向文件所在目录而非包根。包名改从文件向上最近的 `package.json` 读取，遇到 `node_modules` 或 home 目录即停，`index.js` 这类入口文件名不作为标识，避免一个通用词排除掉所有打包扩展。
+- 改变：新增 `excluded_extensions` 配置与 `src/extension-filter.ts`（`isSelfExtension` 一并迁入），`bootstrapSession` 的 `extensionsOverride` 同时应用两个判据。实测对照：`excluded_extensions: []` 时归档 2 条 Run 且残留 1 条 writer，默认值下归档 1 条、writer 0 条，同一次运行的 Shadow debug 日志与 usage 证明 Shadow 确实执行过。

package/DESIGN.md

@@ -47,6 +47,8 @@ Shadow 的 Markdown 定义持久存在，但运行实例不保留长期记忆。
 
 每个实例同时快照激活时 Main 的当前工作目录，并在整个临时 AgentSession 中保持不变。Shadow 的工具都以该目录为 `cwd`；Main 后续切换目录只影响新激活的 Shadow。
 
+临时 AgentSession 加载的扩展是 Main 的子集：去掉本插件自身，再去掉 `excluded_extensions` 列出的扩展。Shadow 需要 provider 扩展提供模型，因此不整体关闭扩展。排除项按扩展文件路径匹配，可用的标识是包名、包目录名、单文件扩展的文件名和绝对路径，都是精确匹配，不支持通配。
+
 ## 3. Shadow Mind 实体
 
 每个 Shadow Mind 使用一个 Markdown 文件描述。用户可以创建和调整它，主 Agent 也可以通过插件工具创建和调整它。
@@ -65,7 +67,7 @@ Shadow 定义统一从全局目录加载：
 
 该目录属于用户数据，不放入插件安装目录，也不随当前项目切换。插件级配置保存在 `config.json`；registry 只扫描目录顶层的 `.md` 文件，不读取 `config.json`，也不递归读取 `logs/`。
 
-`config.json` 保存默认 Shadow 模型、`default_thinking_level`、`heartbeat_probability`、`heartbeat_tools`、`max_parallel_shadows`、`default_shadow_timeout_seconds`、`headless_drain_timeout_seconds`、`result_batch_window_ms` 和可选的 `random_seed` 等全局调度配置。`default_shadow_model` 省略时，插件使用激活时的当前 Main 模型；用户也可以配置一个固定默认模型。`default_thinking_level` 的内置默认值为 `low`。
+`config.json` 保存默认 Shadow 模型、`default_thinking_level`、`heartbeat_probability`、`heartbeat_tools`、`max_parallel_shadows`、`default_shadow_timeout_seconds`、`headless_drain_timeout_seconds`、`result_batch_window_ms`、`excluded_extensions` 和可选的 `random_seed` 等全局调度配置。`excluded_extensions` 的内置默认值是 `["pi-experiencev2"]`，写成 `[]` 即加载 Main 的全部扩展。`default_shadow_model` 省略时，插件使用激活时的当前 Main 模型；用户也可以配置一个固定默认模型。`default_thinking_level` 的内置默认值为 `low`。
 
 每次 heartbeat 判断或 final-response 调度前，插件检查并重新加载发生变化的 `config.json`。纯文本轮次不会进入 heartbeat，但 Main 的最终文字可以触发 final-response 检查。新配置只影响后续调度和新建实例；已经运行的 Shadow 继续使用启动时取得的配置快照。
 

package/README.md

@@ -97,6 +97,8 @@ On the first session start, the extension creates:
 
 No default Shadow Mind is created. The global runtime timeout defaults to 300 seconds, and individual Shadows may override it with `timeout_seconds`.
 
+A Shadow session loads the same extensions as the main session, minus this plugin and anything listed in `excluded_extensions`. Extensions that archive or record whole sessions would otherwise file every Shadow run as one more user session, so `pi-experiencev2` is excluded by default. An entry is an exact identifier, not a pattern: a package name (`pi-experiencev2`, `@scope/name`), a package directory name, a single-file extension's file name, or an absolute path. Set `"excluded_extensions": []` to load everything the main session loads. Shadows need their model provider, so keep provider extensions off this list.
+
 Press `F6` or `Alt+S` to pause or resume Shadow Mind for the current session. On macOS, you may need `Fn+F6`; `Alt+S` corresponds to `Option+S` and depends on the terminal's Option key mapping. The paused footer reads `🐙 Paused` without a redundant zero count. Use `/shadow` to toggle the status panel, `/shadow status` for a summary, or `/shadow toggle`, `/shadow pause`, and `/shadow resume` for command-based control. In TUI mode, `/shadow reports` opens a bounded, scrollable viewer for the five most recently delivered reports, independent of the recent-run list. Use ↑/↓, PageUp/PageDown, or Home/End to scroll; Escape or `/shadow reports hide` closes it. The viewer shows a snapshot; reopen to see new deliveries. Report history is session-local and clears on session replacement or reload; persisted reports remain in the conversation. The status panel keeps its compact summary. Management tools can list, create, update, enable, disable, and delete Shadow Minds, as well as read or update the global configuration. Every write requires user confirmation.
 
 ## Using with DSH

package/README.zh-CN.md

@@ -94,6 +94,8 @@ pi install npm:pi-shadow-mind
 
 扩展不会默认创建 Shadow Mind。全局默认运行超时为 300 秒，单个 Shadow 可以通过 `timeout_seconds` 覆盖。
 
+Shadow 会话加载的扩展与 Main 相同，只去掉本插件和 `excluded_extensions` 里列出的扩展。按会话归档或记录的扩展会把每次 Shadow 运行也记成一条用户会话，因此默认排除 `pi-experiencev2`。每个条目是精确标识，不是通配：包名（`pi-experiencev2`、`@scope/name`）、包目录名、单文件扩展的文件名，或绝对路径。写 `"excluded_extensions": []` 就恢复加载 Main 的全部扩展。Shadow 需要自己的模型 provider，不要把 provider 扩展写进这个列表。
+
 按 `F6` 或 `Alt+S` 可以暂停或恢复当前 Session 的 Shadow Mind。macOS 上可能需要按 `Fn+F6`；`Alt+S` 对应 `Option+S`，是否生效取决于终端的 Option 键映射。暂停时底部状态显示为 `🐙 Paused`，不再显示没有信息量的零计数。使用 `/shadow` 显示或隐藏状态面板，`/shadow status` 查看摘要，也可以通过 `/shadow toggle`、`/shadow pause` 和 `/shadow resume` 控制状态。TUI 模式下，`/shadow reports` 直接打开限高、可滚动的查看器，展示最近交付的 5 份报告，独立于最近运行列表。使用 ↑/↓、PageUp/PageDown 或 Home/End 滚动，Escape 或 `/shadow reports hide` 关闭。查看器显示打开时的快照，重新打开可查看新报告。报告历史仅保留在当前 Session 内存中，切换会话或 reload 时清空；已持久化的报告仍可在对话记录中查看。状态面板保持简短摘要。管理工具可以查询、创建、更新、启用、禁用和删除 Shadow Mind，以及读取或修改全局配置。所有写操作都需要用户确认。
 
 ## 在 DSH 中使用

package/dist/index.js

@@ -158,6 +158,7 @@ function isThinkingLevel(value) {
 }
 
 // src/config.ts
+var DEFAULT_EXCLUDED_EXTENSIONS = ["pi-experiencev2"];
 var DEFAULT_CONFIG = {
   heartbeatProbability: 1 / 3,
   heartbeatTools: [],
@@ -165,6 +166,7 @@ var DEFAULT_CONFIG = {
   defaultShadowTimeoutSeconds: 300,
   headlessDrainTimeoutSeconds: 120,
   resultBatchWindowMs: 400,
+  excludedExtensions: DEFAULT_EXCLUDED_EXTENSIONS,
   defaultThinkingLevel: "low"
 };
 function parseConfig(input) {
@@ -178,6 +180,7 @@ function parseConfig(input) {
   const timeout = positiveNumber(value.default_shadow_timeout_seconds, DEFAULT_CONFIG.defaultShadowTimeoutSeconds, "default_shadow_timeout_seconds");
   const drainTimeout = positiveNumber(value.headless_drain_timeout_seconds, DEFAULT_CONFIG.headlessDrainTimeoutSeconds, "headless_drain_timeout_seconds");
   const windowMs = nonNegativeInteger(value.result_batch_window_ms, DEFAULT_CONFIG.resultBatchWindowMs, "result_batch_window_ms");
+  const excludedExtensions = cleanStringArray(value.excluded_extensions, DEFAULT_CONFIG.excludedExtensions, "excluded_extensions");
   const model = optionalNonEmptyString(value.default_shadow_model, "default_shadow_model");
   const randomSeed = optionalSeed(value.random_seed);
   const thinking = value.default_thinking_level ?? DEFAULT_CONFIG.defaultThinkingLevel;
@@ -191,6 +194,7 @@ function parseConfig(input) {
     defaultShadowTimeoutSeconds: timeout,
     headlessDrainTimeoutSeconds: drainTimeout,
     resultBatchWindowMs: windowMs,
+    excludedExtensions,
     defaultShadowModel: model,
     defaultThinkingLevel: thinking,
     randomSeed
@@ -204,6 +208,8 @@ function serializeConfig(config) {
     default_shadow_timeout_seconds: config.defaultShadowTimeoutSeconds,
     headless_drain_timeout_seconds: config.headlessDrainTimeoutSeconds,
     result_batch_window_ms: config.resultBatchWindowMs,
+    // Always written, including `[]`: omitting it would silently restore the default.
+    excluded_extensions: config.excludedExtensions,
     ...config.defaultShadowModel ? { default_shadow_model: config.defaultShadowModel } : {},
     default_thinking_level: config.defaultThinkingLevel,
     ...config.randomSeed !== void 0 ? { random_seed: config.randomSeed } : {}
@@ -7327,6 +7333,7 @@ function configWriteTool(store, getConfig) {
         Type.Number({ exclusiveMinimum: 0 })
       ),
       result_batch_window_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+      excluded_extensions: Type.Optional(Type.Array(Type.String())),
       default_shadow_model: Type.Optional(Type.String()),
       default_thinking_level: Type.Optional(THINKING),
       random_seed: Type.Optional(
@@ -7343,6 +7350,7 @@ function configWriteTool(store, getConfig) {
         default_shadow_timeout_seconds: raw.default_shadow_timeout_seconds ?? current.defaultShadowTimeoutSeconds,
         headless_drain_timeout_seconds: raw.headless_drain_timeout_seconds ?? current.headlessDrainTimeoutSeconds,
         result_batch_window_ms: raw.result_batch_window_ms ?? current.resultBatchWindowMs,
+        excluded_extensions: raw.excluded_extensions ?? current.excludedExtensions,
         default_shadow_model: raw.default_shadow_model ?? current.defaultShadowModel,
         default_thinking_level: raw.default_thinking_level ?? current.defaultThinkingLevel,
         random_seed: raw.random_seed ?? current.randomSeed
@@ -7921,8 +7929,7 @@ function isStaleExtensionContextError(error) {
 
 // src/shadow-runner.ts
 import { mkdir as mkdir3 } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-import { basename as basename3, dirname as dirname2, join as join4, normalize, resolve } from "node:path";
+import { join as join5 } from "node:path";
 import { Type as Type2 } from "typebox";
 import {
   DefaultResourceLoader,
@@ -8136,6 +8143,90 @@ function compactJson(value) {
   }
 }
 
+// src/extension-filter.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { homedir } from "node:os";
+import { basename as basename3, dirname as dirname2, join as join4, normalize, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var SELF_PATH = normalize(resolve(fileURLToPath(import.meta.url)));
+var SELF_DIRECTORY = dirname2(SELF_PATH);
+var SELF_ENTRIES = /* @__PURE__ */ new Set(["index.ts", "index.js"]);
+function isSelfExtension(candidate) {
+  const normalized = normalize(resolve(candidate));
+  if (normalized === SELF_PATH) return true;
+  return dirname2(normalized) === SELF_DIRECTORY && SELF_ENTRIES.has(basename3(normalized));
+}
+var PACKAGE_LOOKUP_DEPTH = 4;
+var GENERIC_ENTRY_FILE = /^index\.[^.]+$/;
+var packageNameCache = /* @__PURE__ */ new Map();
+function extensionIdentifiers(resolvedPath) {
+  const normalized = normalize(resolve(resolvedPath));
+  const identifiers = /* @__PURE__ */ new Set([normalized]);
+  const owner = findPackage(dirname2(normalized));
+  if (owner) {
+    identifiers.add(owner.name);
+    identifiers.add(basename3(owner.directory));
+    identifiers.add(owner.directory);
+  }
+  const fileName = basename3(normalized);
+  if (!GENERIC_ENTRY_FILE.test(fileName)) {
+    identifiers.add(fileName);
+    identifiers.add(fileName.replace(/\.[^.]+$/, ""));
+  }
+  return identifiers;
+}
+function createExtensionExcluder(entries) {
+  const wanted = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    const trimmed = entry.trim();
+    if (!trimmed) continue;
+    wanted.add(trimmed);
+    wanted.add(stripScheme(trimmed));
+    wanted.add(normalize(resolve(expandHome(trimmed))));
+  }
+  if (wanted.size === 0) return () => false;
+  return (resolvedPath) => {
+    for (const identifier of extensionIdentifiers(resolvedPath)) {
+      if (wanted.has(identifier)) return true;
+    }
+    return false;
+  };
+}
+function findPackage(directory) {
+  if (packageNameCache.has(directory)) return packageNameCache.get(directory);
+  const home = resolve(homedir());
+  let current = directory;
+  let found;
+  for (let depth = 0; depth < PACKAGE_LOOKUP_DEPTH; depth += 1) {
+    if (basename3(current) === "node_modules" || current === home) break;
+    const name = readPackageName(current);
+    if (name) {
+      found = { name, directory: current };
+      break;
+    }
+    const parent = dirname2(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  packageNameCache.set(directory, found);
+  return found;
+}
+function readPackageName(directory) {
+  try {
+    const parsed = JSON.parse(readFileSync2(join4(directory, "package.json"), "utf8"));
+    const name = parsed.name;
+    return typeof name === "string" && name.trim() ? name.trim() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function stripScheme(source) {
+  return source.replace(/^[a-z][a-z0-9+.-]+:/i, "");
+}
+function expandHome(entry) {
+  return entry === "~" || entry.startsWith("~/") ? resolve(homedir(), entry.slice(2)) : entry;
+}
+
 // src/shadow-runner.ts
 function resolveShadowTools(whitelist, available, defaults = DEFAULT_READ_TOOLS) {
   const builtin = /* @__PURE__ */ new Set(["report_to_main"]);
@@ -8147,7 +8238,6 @@ function resolveShadowTools(whitelist, available, defaults = DEFAULT_READ_TOOLS)
   }
   return { tools, missing };
 }
-var SELF_PATH = normalize(resolve(fileURLToPath(import.meta.url)));
 function runReason(timedOut, reported, aborted, failed = false) {
   if (timedOut) return "timeout";
   if (reported) return "report";
@@ -8225,6 +8315,7 @@ var ShadowRunner = class {
   async bootstrapSession(request, model, controller, state, sessionManager) {
     const thinkingLevel = resolveRunThinkingLevel(model, request);
     const settingsManager = SettingsManager.create(request.cwd, request.agentDir);
+    const isExcluded = createExtensionExcluder(request.config.excludedExtensions);
     const resourceLoader = new DefaultResourceLoader({
       cwd: request.cwd,
       agentDir: request.agentDir,
@@ -8236,9 +8327,14 @@ var ShadowRunner = class {
       appendSystemPrompt: [],
       agentsFilesOverride: () => ({ agentsFiles: [] }),
       skillsOverride: (base) => ({ skills: [], diagnostics: base.diagnostics }),
+      // Drop this plugin itself plus every extension the user excluded, so
+      // session-scoped extensions (archivers, recorders) never treat an internal
+      // Shadow run as one more user session.
       extensionsOverride: (base) => ({
         ...base,
-        extensions: base.extensions.filter((extension) => !isSelfExtension(extension.resolvedPath))
+        extensions: base.extensions.filter(
+          (extension) => !isSelfExtension(extension.resolvedPath) && !isExcluded(extension.resolvedPath)
+        )
       })
     });
     await resourceLoader.reload();
@@ -8331,7 +8427,7 @@ function createReportTool(onReport) {
 }
 async function createShadowSessionManager(request) {
   if (!request.shadow.debug) return SessionManager.inMemory(request.cwd);
-  const directory = join4(request.agentDir, "shadow-minds", "logs", request.shadow.id);
+  const directory = join5(request.agentDir, "shadow-minds", "logs", request.shadow.id);
   await mkdir3(directory, { recursive: true });
   const manager = SessionManager.create(request.cwd, directory);
   manager.appendCustomEntry("shadow-mind-run", { runId: request.runId, epoch: request.epoch, shadowId: request.shadow.id });
@@ -8363,12 +8459,6 @@ function assertTrajectoryFits(model, messages) {
     throw new Error(`trajectory ~${estimated} tokens exceeds ${model.provider}/${model.id} context window (${model.contextWindow})`);
   }
 }
-function isSelfExtension(candidate) {
-  const normalized = normalize(resolve(candidate));
-  if (normalized === SELF_PATH) return true;
-  const sourceDirectory = normalize(resolve(dirname2(SELF_PATH)));
-  return dirname2(normalized) === sourceDirectory && (basename3(normalized) === "index.ts" || basename3(normalized) === "index.js");
-}
 
 // src/shutdown-drain.ts
 async function waitForSettled(options) {
@@ -8394,12 +8484,12 @@ async function waitForSettled(options) {
 // src/usage-store.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 import { mkdir as mkdir5, readFile as readFile5, rename as rename2, rm as rm2, writeFile as writeFile4 } from "node:fs/promises";
-import { dirname as dirname3, join as join6 } from "node:path";
+import { dirname as dirname3, join as join7 } from "node:path";
 
 // src/usage-file-lock.ts
 import { randomUUID } from "node:crypto";
 import { mkdir as mkdir4, readFile as readFile4, rename, rm, stat as stat2, utimes, writeFile as writeFile3 } from "node:fs/promises";
-import { join as join5 } from "node:path";
+import { join as join6 } from "node:path";
 var USAGE_LOCK_OWNER_FILE = "owner";
 var USAGE_LOCK_OPERATION_DIRECTORY = ".operation";
 async function acquireUsageFileLock(usagePath, timing = {}) {
@@ -8436,7 +8526,7 @@ function startLease(lockPath, owner, timing) {
         return;
       }
       const now = /* @__PURE__ */ new Date();
-      await utimes(join5(lockPath, USAGE_LOCK_OWNER_FILE), now, now);
+      await utimes(join6(lockPath, USAGE_LOCK_OWNER_FILE), now, now);
     }).catch(() => void 0);
   }, timing.heartbeatMs);
   timer.unref();
@@ -8450,7 +8540,7 @@ function startLease(lockPath, owner, timing) {
 async function recoverStaleUsageLock(lockPath, timing) {
   const observed = await readUsageLockState(lockPath);
   if (!observed || !isRecoverableUsageLock(observed, timing.staleMs)) return;
-  const operationPath = join5(lockPath, USAGE_LOCK_OPERATION_DIRECTORY);
+  const operationPath = join6(lockPath, USAGE_LOCK_OPERATION_DIRECTORY);
   if (!await claimUsageLockOperation(operationPath, timing)) return;
   try {
     const current = await readUsageLockState(lockPath);
@@ -8468,7 +8558,7 @@ async function recoverStaleUsageLock(lockPath, timing) {
   }
 }
 async function releaseUsageLock(lockPath, token, timing) {
-  const operationPath = join5(lockPath, USAGE_LOCK_OPERATION_DIRECTORY);
+  const operationPath = join6(lockPath, USAGE_LOCK_OPERATION_DIRECTORY);
   while (true) {
     const observed = await readUsageLockState(lockPath);
     if (!observed || observed.owner?.token !== token) return;
@@ -8523,7 +8613,7 @@ async function claimUsageLockOperation(operationPath, timing) {
   return false;
 }
 async function writeOwner(path, owner) {
-  await writeFile3(join5(path, USAGE_LOCK_OWNER_FILE), JSON.stringify(owner), {
+  await writeFile3(join6(path, USAGE_LOCK_OWNER_FILE), JSON.stringify(owner), {
     encoding: "utf8",
     flag: "wx"
   });
@@ -8537,7 +8627,7 @@ async function readUsageLockState(lockPath) {
     throw error;
   }
   try {
-    const ownerPath = join5(lockPath, USAGE_LOCK_OWNER_FILE);
+    const ownerPath = join6(lockPath, USAGE_LOCK_OWNER_FILE);
     const [raw, ownerFile] = await Promise.all([readFile4(ownerPath, "utf8"), stat2(ownerPath)]);
     return {
       owner: parseOwner(raw),
@@ -8595,7 +8685,7 @@ var UsageStore = class {
   initialization;
   pendingWrite = Promise.resolve();
   constructor(agentDir) {
-    this.usagePath = join6(agentDir, "shadow-minds", "usage.json");
+    this.usagePath = join7(agentDir, "shadow-minds", "usage.json");
   }
   initialize() {
     this.initialization ??= this.load();