@istuen/pt 0.1.0

package/src/session.ts

@@ -0,0 +1,190 @@
+// src/session.ts — Pt Session 状态封装（pt-quality #2 / P2.6）
+//
+// 替代 index.ts 10 个模块级 let 变量——收拢到单 state 对象，便于维护和单元测试。
+//
+// 设计：
+// - Map<sessionId, SessionState>（v12.x）—— key 用 pi SessionManager.getSessionId()
+//   支持 pi-web 多 session 并发：不同 session 各自一份 SessionState。
+//   TUI 模式下只有一个 session，Map 只有一个 entry，等同 module-level 单例行为。
+// - 所有 setter 都通过 state 字段赋值（不解构）
+// - clearSessionById 暴露给 session_shutdown / 测试
+//
+// v10.x：session-state 升级为 session-scoped daemon 级——
+//   - sessionId：crypto 生成的 8-hex 短 id（多并发 `pi` 进程的日志隔离键）
+//   - logger   ：per-session 单例 PtLogger（替代 per-transpile 实例化）
+//
+// v10.x（issue pt-context-persist-lost 修复，现 /pt-profile）：loadedFrom 记录当前 activeProfile 的来源，
+//   用于 /pt status 可观测性 + 排查"为什么没选到我预期的 profile"。
+//
+// v12.x（issue pt-session-singleton-pi-web-pollution 修复）：
+//   - 移除 module-level `session` 单例（设计假设 per-process = per-session 在 pi-web 下不成立）
+//   - state 容器改为 Map<sessionId, SessionState>，key 用 pi SessionManager.getSessionId()
+//   - 调用方通过 `getSessionById(ctx.sessionManager.getSessionId())` 取 state
+//   - 对应 `src/agent/registry.ts` 把 Adapter 注册表也改成 WeakMap<ExtensionAPI, ...>，
+//     保证 Adapter 实例 per-pi，避免"单例 PiAdapter.this.segment 被其他 session 覆盖"。
+//   - `cachedManualProgress` 从 module-level let 搬到 SessionState 字段。
+
+import type { AssetHealthIssue } from "./asset-health.js";
+import type { ValidationResult } from "./asset-pack/validate.js";
+import type {
+  AgentAdapter,
+  AgentContext,
+  Blueprint,
+  Domain,
+  Profile,
+  SchemaBundle,
+} from "./schema.js";
+import type { PtLogger } from "./log.js";
+import type { ManualProgress } from "./manual-track.js";
+
+/** activeProfile 的来源（session_start fallback 命中点）。 */
+export type ProfileLoadSource =
+  | "flag"
+  | "settings"
+  | "session"
+  | "auto"
+  | "default"
+  // v15.x PR6（fix pt-active-profile-fallback-mismatch）：显式 fallback 标识
+  | "fallback"
+  | null;
+
+/** pt 注入到 Session Inject 的状态（自报，非检测 Pi）。
+ *  - idle：未激活 / 无 segment
+ *  - pending：Profile 已加载但还没轮到下一轮 before_agent_start
+ *  - injected：本轮 before_agent_start 成功返回注入结果
+ *  - failed：本轮 before_agent_start catch 异常 */
+export type InjectionState = "idle" | "pending" | "injected" | "failed";
+
+/** 当前追踪的 Manual 实例（LLM 调 pt_manual 写入后触发）。
+ *  进度（stepDone/stepTotal）不存 session——文件是 single source of truth，
+ *  每次 widget 渲染时 parse 文件重新计算。 */
+export interface ActiveManual {
+  filePath: string; // .pt/manuals/<procedure>-<ts>.md
+  procedure: string;
+  args: string;
+  activatedAt: number; // Date.now()，排序/去重用
+}
+
+/** Session 全量状态。 */
+export interface SessionState {
+  activeProfile: string | null;
+  cachedSegment: string | null;
+  cachedBundles: SchemaBundle[] | null;
+  cachedAgentContext: AgentContext | null;
+  cachedBlueprint: Blueprint | null;
+  cachedDomains: Domain[];
+  cachedProfile: Profile | null;
+  lastCwd: string;
+  lastBuiltPrompt: string | null;
+  lastCacheHit: boolean;
+  activeAdapter: AgentAdapter | null;
+  /** v10.x：session 唯一短 id，8 hex（4.3B 组合空间，足够区分并发 pi 进程）。 */
+  sessionId: string;
+  /** v10.x：per-session 单例 logger（替代 per-transpile 实例化）。 */
+  logger: PtLogger | null;
+  /** v10.x：当前 activeProfile 的来源（可观测性）。null 表示未加载。 */
+  loadedFrom: ProfileLoadSource;
+  /** pt 注入到 Session Inject 的状态（footer 三态文字 + widget 依据）。 */
+  injectionState: InjectionState;
+  /** failed 时存错误消息（footer 追加）。其它状态 null。 */
+  injectionError: string | null;
+  /** 当前追踪的 Manual 实例（widget + footer 后缀 + 持久化恢复）。 */
+  activeManual: ActiveManual | null;
+  /** v12.x：当前 manual widget 的 async parse 缓存（替代原 module-level `cachedManualProgress`）。 */
+  cachedManualProgress: ManualProgress | null;
+  /** v14.x（issue pt-asset-migration-visibility Layer 2）：
+   *  session_start 批量体检结果——footer 追加 ⚠ N issues + /pt status 暴露。
+   *  null = 未扫描（用户加载内置 profile 后才扫描过项目 profile）。 */
+  assetHealthIssues: AssetHealthIssue[] | null;
+  /** v15.x PR1（§6.7.1）：session_start 一次性 pack 校验结果——/pt status 展示用。 */
+  packValidation: ValidationResult[] | null;
+  /** v15.x PR1（§6.7.3）：project pack 校验失败时标 true，transpileActive 强制回 guide。 */
+  projectPackDegraded: boolean;
+  /** v15.x PR1（§7.5）：全局 Pack 初始化引导一次性提示标记。 */
+  globalPackGuideShown: boolean;
+}
+
+/** 默认空 SessionState。 */
+export function createSessionState(): SessionState {
+  return {
+    activeProfile: null,
+    cachedSegment: null,
+    cachedBundles: null,
+    cachedAgentContext: null,
+    cachedBlueprint: null,
+    cachedDomains: [],
+    cachedProfile: null,
+    lastCwd: "",
+    lastBuiltPrompt: null,
+    lastCacheHit: false,
+    activeAdapter: null,
+    sessionId: "",
+    logger: null,
+    loadedFrom: null,
+    injectionState: "idle",
+    injectionError: null,
+    activeManual: null,
+    cachedManualProgress: null,
+    assetHealthIssues: null,
+    packValidation: null,
+    projectPackDegraded: false,
+    globalPackGuideShown: false,
+  };
+}
+
+/** v12.x：Map<sessionId, SessionState> 容器，key = pi SessionManager.getSessionId()。
+ *  对外不导出（避免外部直接 mutate 绕过懒加载）。 */
+const sessionMap = new Map<string, SessionState>();
+
+/** 重置编译产物字段（catch 路径用）。
+ *  v13.x（issue pt-no-agent-context-reset-session-state 修复）：
+ *  - transpile/session_start/switchProfile 三处 catch 调用本函数
+ *  - 避免 stale cachedAgentContext/cachedBlueprint/cachedDomains/cachedProfile/activeAdapter
+ *    误导 /pt flows / /pt manual 返回旧 Profile 的手册列表（掩盖真实失败）
+ *  - 不清 sessionId/logger/lastCwd/activeProfile/loadedFrom/activeManual（生命周期不同：
+ *    session_id 标识当前会话、logger 持续写日志、lastCwd 是项目根、activeProfile 是用户意图、
+ *    loadedFrom 是来源、activeManual 是手动追踪）
+ */
+export function resetSessionState(s: SessionState): void {
+  s.cachedSegment = null;
+  s.cachedBundles = null;
+  s.cachedAgentContext = null;
+  s.cachedBlueprint = null;
+  s.cachedDomains = [];
+  s.cachedProfile = null;
+  s.activeAdapter?.resetInjection?.();
+  s.activeAdapter = null;
+  s.lastCacheHit = false;
+  s.injectionState = "idle";
+  s.injectionError = null;
+}
+
+/** 取指定 sessionId 的 state（lazy create）。TUI 模式下只有一个 entry。 */
+export function getSessionById(sessionId: string): SessionState {
+  let s = sessionMap.get(sessionId);
+  if (!s) {
+    s = createSessionState();
+    sessionMap.set(sessionId, s);
+  }
+  return s;
+}
+
+/** 列表所有 session state（debug / 诊断用，如 /pt sessions 列表）。 */
+export function listAllSessions(): SessionState[] {
+  return [...sessionMap.values()];
+}
+
+/** 清空指定 sessionId 的 state（session_shutdown 调用）。 */
+export function clearSessionById(sessionId: string): void {
+  sessionMap.delete(sessionId);
+}
+
+/** 清空所有 session state（仅测试 / 重启进程等需要）。 */
+export function clearAllSessions(): void {
+  sessionMap.clear();
+}
+
+/** 测试 / 诊断：Map 的当前大小。 */
+export function sessionCount(): number {
+  return sessionMap.size;
+}

package/src/slog.ts

@@ -0,0 +1,32 @@
+// src/slog.ts — session-scoped logger 快捷调用
+//
+// 设计动机：
+//   - 入口代码（src/index.ts）和 session 交互层（src/manual-session.ts）共享同一 slog 快捷
+//   - session.logger 为 null 时静默（session_start 之前不可用）
+//   - 不依赖 file IO（持久化走 src/log.ts 的 PtLogger 类），仅作调用快捷
+//
+// v11.x：从 src/index.ts 抽出（与 manual-session 同次提交），统一两个调用点的快捷。
+//
+// v12.x（issue pt-session-singleton-pi-web-pollution 修复）：
+//   - 移除 module-level `session` 单例访问
+//   - `slog` 改接受 `sessionId` 参数，按 sessionId 取 per-session logger
+//   - sessionId 为空时静默（与原 "session.logger 为 null 时静默" 行为一致）
+//
+// 类型说明：PtLogLevel 用 "warning"（与 ctx.ui.notify 兼容），PtLogger 方法用 "warn"。
+//   此处使用 PtLogger 的方法名（debug/info/warn/error）作为调用 key，与原 slog 行为一致。
+
+import { getSessionById } from "./session.js";
+
+/** session-scoped logger 快捷调用（sessionId 空时静默——session_start 之前不可用）。
+ *  level 用 PtLogger 的方法名（debug/info/warn/error），不是 PtLogLevel 的字面量。 */
+export function slog(
+  sessionId: string,
+  level: "debug" | "info" | "warn" | "error",
+  msg: string,
+  ctx?: Record<string, unknown>
+): void {
+  if (!sessionId) return;
+  const logger = getSessionById(sessionId).logger;
+  if (!logger) return;
+  logger[level](msg, ctx);
+}

package/src/transpile.ts

@@ -0,0 +1,302 @@
+// src/transpile.ts — v9 三段式链路：parse → compile → cache → render
+//
+// Phase 9.7：v9 链路——Profile 用户面 + Blueprint 结构层 + AgentAdapter 注入。
+//   parse(profile md) → IR (SchemaBundle with profiles)
+//     ↓
+//   findProfile → findBlueprint → compileAgentContext(profile, blueprint, domains) → AgentContext IR
+//     ↓
+//   cache.load? 命中 → 用缓存 : cache.save(AgentContext) → 重编译
+//     ↓
+//   render.systemPrompt(AgentContext, Blueprint) → 给 AgentAdapter 注入 before_agent_start
+//
+// Phase 11.x / P1：单源线性（YAGNI 多源合并）——取第一个成功的 adapter。
+//   旧版多 bundle 循环 + 5 个 lastXxx 累积已删（P1.1）。bundles 仍返 [bundle]
+//   保留 SchemaBundle[] 形态（index.ts:786 r.bundles[0] 依赖）。无成功 bundle
+//   抛错（P1.2）由 index.ts:286 catch 兜底。
+//
+// Phase term-P1：Context IR → AgentContext 改名同步——
+//   - compileContext → compileAgentContext
+//   - saveContext/loadContext → saveAgentContext/loadAgentContext
+//   - TranspileResult.context → TranspileResult.agentContext（字段改名）
+
+import { readdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { CACHE_DIR } from "./constants.js";
+import { errMsg, reportError, reportWarn } from "./diagnostics.js";
+import { mdAdapter } from "./parse/index.js";
+import { compileAgentContext } from "./compile/agent-context.js";
+import { saveAgentContext, loadAgentContext } from "./render/cache.js";
+import { renderSessionInject } from "./render/session-inject.js";
+import { findProfile } from "./schema.js";
+import { parseRef, resolveBlueprint } from "./parse/ref-resolver.js";
+import {
+  expandProfile,
+  UseTargetNotFound,
+  UseChainCycle,
+  BlueprintGroupOutOfScope,
+} from "./compile/resolve-use.js";
+import type {
+  AgentContext,
+  Blueprint,
+  Domain,
+  Profile,
+  SchemaBundle,
+  SourceAdapter,
+  SourceAdapterContext,
+} from "./schema.js";
+
+export interface TranspileResult {
+  /** 注入 session 的字符串段（聚合所有 inject=session 的聚合组） */
+  segment: string;
+  /** 各 adapter 返回的 SchemaBundle（保留给 input handler 找 FlowTemplate / listManuals 用） */
+  bundles: SchemaBundle[];
+  /** 缓存命中信息 */
+  cacheHit: boolean;
+  /** v9 新增（给 AgentAdapter 用）。Phase term-P1：context → agentContext（IR 改名同步）。 */
+  agentContext: AgentContext;
+  blueprint: Blueprint;
+  domains: Domain[];
+  /** 当前激活的 Profile 名 */
+  activeProfile: string;
+  /** 当前激活的 Profile（listManuals 范围过滤用） */
+  profile: Profile;
+  /** v15.x PR6（fix pt-active-profile-fallback-mismatch）：bundle.activeProfile 由来
+   *  caller 层依据 origin 决定是否同步 s.activeProfile / loadedFrom / notify。 */
+  activeProfileOrigin: "exact" | "fallback";
+  /** origin="fallback" 时记录用户原始请求名（caller 用作 notify 文案 + log） */
+  originalProfileName?: string;
+}
+
+/** ============== Source Adapter 注册表（MVP 只有 MD） ==============
+ *  P1.1：保留数组形式作为扩展点（未来加 yamlAdapter / dbAdapter），
+ *  但 loadAndTranspile 改为"取第一个成功 adapter"——多源合并未来设计（YAGNI）。 */
+const sourceAdapters: SourceAdapter[] = [
+  mdAdapter,
+  // 未来：yamlAdapter, dbAdapter, ...
+];
+
+/** 三段式转译：parse → compile → cache → render。 */
+export async function loadAndTranspile(
+  cwd: string,
+  profileName: string,
+  adapterCtx?: SourceAdapterContext
+): Promise<TranspileResult> {
+  adapterCtx?.log?.debug("transpile:start", { profileName, adapterCount: sourceAdapters.length });
+
+  // 1. parse：依次调所有 adapter，取第一个成功的 bundle
+  let bundle: SchemaBundle | null = null;
+  for (const a of sourceAdapters) {
+    try {
+      const b = await a.load(cwd, profileName, adapterCtx);
+      if (b) {
+        bundle = b;
+        break;
+      }
+    } catch (e) {
+      reportError(adapterCtx, `adapter ${a.name} failed: ${errMsg(e)}`, { adapter: a.name });
+    }
+  }
+  if (!bundle) {
+    throw new Error(`transpile: no adapter succeeded for profile "${profileName}"`);
+  }
+  adapterCtx?.log?.info("transpile:parse done", {
+    profileName,
+    profileCount: bundle.profiles.length,
+    blueprintCount: bundle.blueprints.length,
+    domainCount: bundle.domains.length,
+  });
+
+  // 2. compile：profile → blueprint → context
+  const rawProfile = findProfile(bundle.profiles, bundle.activeProfile);
+  if (!rawProfile) {
+    throw new Error(
+      `transpile: profile "${bundle.activeProfile}" not found in bundle (available: ${bundle.profiles.map((p) => p.name).join(", ") || "<none>"})`
+    );
+  }
+
+  // v15.x PR5（§5.3.2 + §8.2）：use 单继承展开
+  //  - 在 findProfile 之后、findBlueprint 之前——展开后 blueprint 可能被 self 覆盖
+  //  - 展开后 profile 进 compileAgentContext + computeSourceHash（§8.2 use 链自然进 hash）
+  //  - profileByQualifiedName = workingSet.profiles 视图转换（key 已是 "pack/name"）
+  //  - blueprintByQualifiedName 直接复用 workingSet.blueprints（{pack, asset} 视图）
+  // v15.x §4.4.2：profileByQualifiedName 从 workingSet.profiles.identity 迭代（key = pack.name/asset.name）
+  const profileByQualifiedName = new Map<string, Profile>();
+  for (const [k, v] of bundle.workingSet.profiles.identity) {
+    profileByQualifiedName.set(k, v.asset);
+  }
+  // v15.x §4.4.2：blueprintByQualifiedName 从 workingSet.blueprints.identity 取（与原单索引语义一致）
+  const blueprintByQualifiedName = bundle.workingSet.blueprints.identity;
+  let profile: Profile;
+  try {
+    profile = expandProfile(
+      rawProfile,
+      profileByQualifiedName,
+      blueprintByQualifiedName,
+      bundle.packs,
+      new Set(),
+      adapterCtx
+    );
+  } catch (e) {
+    // use 链错误：reportWarn + rethrow——让上层报"transpile: failed"并阻断激活
+    if (
+      e instanceof UseTargetNotFound ||
+      e instanceof UseChainCycle ||
+      e instanceof BlueprintGroupOutOfScope
+    ) {
+      reportWarn(adapterCtx, e.message, {
+        profileName: rawProfile.name,
+        errorType: e.name,
+      });
+    }
+    throw e;
+  }
+  const blueprintEntry = resolveBlueprint(
+    profile,
+    bundle.workingSet.blueprints,
+    bundle.packs.map((p) => p.name)
+  );
+  const blueprint = blueprintEntry?.asset;
+  if (!blueprint) {
+    const resolved = (() => {
+      const { pack, name } = parseRef(profile.blueprint, profile.sourcePack ?? "");
+      return `${pack}/${name}`;
+    })();
+    reportWarn(adapterCtx, `Profile "${profile.name}" 引用未知 Blueprint "${profile.blueprint}"`, {
+      profileName: profile.name,
+      referencedBlueprint: profile.blueprint,
+      resolvedBlueprint: `@${resolved}`,
+      // v15.x §4.4.2：availableBlueprints 从 identity 索引读（manifest.name 视图，与原单索引语义一致）
+      availableBlueprints: [...bundle.workingSet.blueprints.identity.keys()],
+    });
+    throw new Error(
+      `transpile: blueprint "${profile.blueprint}" not found for profile "${profile.name}"`
+    );
+  }
+  // v15.x PR2（§8.1 + §8.3）+ PR3（§4.4.3 #2）：compileAgentContext 加 packs + profilePack + workingSet
+  const ctx = compileAgentContext(
+    profile,
+    blueprint,
+    bundle.domains,
+    bundle.packs,
+    bundle.activeProfilePack,
+    bundle.workingSet
+  );
+  adapterCtx?.log?.debug("transpile:compile done", {
+    profileName: profile.name,
+    sourceHashPrefix: ctx.sourceHash.slice(0, 8),
+    moduleCount: Object.keys(ctx.modules).length,
+    packName: ctx.packName,
+  });
+
+  // 3. cache：load 命中 → 用缓存（跳过写入），未命中 → save
+  //   Phase term-P4.2：cacheDir 改用 constants.CACHE_DIR 常量，签名删 compilation 参数。
+  //   v15.x PR2（§8.3）：loadAgentContext 加 packName 参数，cache 文件名 <pack>__<profile>。
+  const cached = await loadAgentContext(cwd, ctx.packName, ctx.name, ctx.sourceHash);
+  let used: AgentContext;
+  let cacheHit = false;
+  if (cached) {
+    cacheHit = true;
+    adapterCtx?.log?.info("transpile:cache hit", { agentContextName: ctx.name });
+    used = cached;
+  } else {
+    adapterCtx?.log?.info("transpile:cache miss → save", { agentContextName: ctx.name });
+    await saveAgentContext(cwd, ctx);
+    used = ctx;
+  }
+
+  // 4. render：剥 asset 分隔注释
+  //   Phase term-P4.3：renderSystemPrompt → renderSessionInject（inject 语义值 session/turn）。
+  const segment = renderSessionInject(used, blueprint)
+    .replace(/<!-- =====[^\n]*-->\n?/g, "")
+    .trim();
+
+  // issue pt-status-no-injection-state：segmentLen === 0 几乎总是配置错误
+  // (profile 缺 ### Modules / blueprint groups 名错配 / domain 段名不匹配等)。
+  // cache hit 路径下特别危险——空 segment 被缓存复用，footer 永远 idle。
+  // 主动告警让用户首次切换就发现问题，而不是依赖 `injected: true` 误导
+  if (segment.length === 0) {
+    reportWarn(
+      adapterCtx,
+      `Profile「${profile.name}」编译产出空 segment（注入不会生效，footer 会一直 idle）`,
+      {
+        profileName: profile.name,
+        cacheHit,
+        hint: "检查 Profile 的 H2 段下 `### Modules` 配置、Blueprint groups 名匹配、Domain H2 段名",
+      }
+    );
+  }
+
+  // 5. prune orphan caches（v13.x issue pt-no-agent-context-prune-orphan-caches 修复）
+  //   Profile 删除/改名后，旧 cache 文件残留——transpile 末尾自动 unlink
+  //   validProfileNames 来自当前 bundle（项目 + builtin 合并后的全集）
+  //   Phase term-P4.2：Blueprint.competition 已移除，cacheDir 用 CACHE_DIR 常量
+  const pruned = await pruneOrphanCaches(
+    cwd,
+    CACHE_DIR,
+    new Set(bundle.profiles.map((p) => p.name))
+  );
+  if (pruned.length > 0) {
+    adapterCtx?.log?.info("transpile:prune orphan caches", { pruned });
+  }
+
+  adapterCtx?.log?.info("transpile:done", {
+    profileName: profile.name,
+    segmentLen: segment.length,
+    cacheHit,
+    prunedCount: pruned.length,
+  });
+
+  return {
+    segment,
+    bundles: [bundle],
+    cacheHit,
+    agentContext: used,
+    blueprint,
+    domains: bundle.domains,
+    activeProfile: profile.name,
+    profile,
+    // v15.x PR6（fix pt-active-profile-fallback-mismatch）：透传 origin 给 caller
+    activeProfileOrigin: bundle.activeProfileOrigin,
+    originalProfileName: bundle.originalProfileName,
+  };
+}
+
+/** 删除孤儿 cache 文件（Profile 已不存在的 cache）。
+ *  v13.x（issue pt-no-agent-context-prune-orphan-caches）：transpile 末尾自动清理，
+ *  避免 Profile 删改后旧 cache 文件残留误导排查。
+ *
+ *  @param cwd 项目根目录
+ *  @param cacheDir 缓存目录（从 Blueprint.compilation.cacheDir 读，默认 `.pt/cache/agent-contexts/`）
+ *  @param validProfileNames 当前 bundle.profiles 合并后的全集（项目覆盖 builtin）
+ *  @returns 被 unlink 的 cache 名列表（用于 trace）
+ */
+export async function pruneOrphanCaches(
+  cwd: string,
+  cacheDir: string,
+  validProfileNames: Set<string>
+): Promise<string[]> {
+  const dir = join(cwd, cacheDir);
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch {
+    return []; // 目录不存在（首次加载）返空，不抛错
+  }
+  const pruned: string[] = [];
+  for (const f of files) {
+    if (!f.endsWith(".agent-context.md")) continue;
+    // v15.x PR2（§8.3）：cache 文件名 <pack>__<profile>.agent-context.md——split "__" 拿 profile name
+    // PR1 阶段：<profile>.agent-context.md——slice 去后缀。二者需向后兼容。
+    const stem = f.slice(0, -".agent-context.md".length);
+    const sepIdx = stem.lastIndexOf("__");
+    const name = sepIdx >= 0 ? stem.slice(sepIdx + 2) : stem;
+    if (validProfileNames.has(name)) continue;
+    try {
+      await unlink(join(dir, f));
+      pruned.push(name);
+    } catch {
+      // unlink 失败（权限/不存在）跳过——不影响主流程
+    }
+  }
+  return pruned;
+}

package/src/verify/file-hash.ts

@@ -0,0 +1,29 @@
+// src/verify/file-hash.ts — 验证文件 sha256 hash 匹配
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ProbeOutcome } from "../schema.js";
+
+export async function fileHash(cwd: string, params: Record<string, string>): Promise<ProbeOutcome> {
+  const path = params.path;
+  if (!path) return { outcome: "INCONCLUSIVE", message: "缺少参数: path" };
+  const expected = params.expected;
+  if (!expected) return { outcome: "INCONCLUSIVE", message: "缺少参数: expected (sha256)" };
+  try {
+    const content = readFileSync(join(cwd, path));
+    const hash = createHash("sha256").update(content).digest("hex");
+    const match = hash === expected;
+    return {
+      outcome: match ? "COMPLETED" : "DEVIATED",
+      message: match
+        ? `hash 匹配: ${path}`
+        : `hash 不匹配: ${path}（期望 ${expected.slice(0, 8)}...，实际 ${hash.slice(0, 8)}...）`,
+      actual: hash,
+    };
+  } catch (e) {
+    return {
+      outcome: "INCONCLUSIVE",
+      message: `无法读取 ${path}: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}

package/src/verify/fs-content-match.ts

@@ -0,0 +1,28 @@
+// src/verify/fs-content-match.ts — 验证文件包含某文本
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ProbeOutcome } from "../schema.js";
+
+export async function fsContentMatch(
+  cwd: string,
+  params: Record<string, string>
+): Promise<ProbeOutcome> {
+  const path = params.path;
+  if (!path) return { outcome: "INCONCLUSIVE", message: "缺少参数: path" };
+  const pattern = params.pattern;
+  if (!pattern) return { outcome: "INCONCLUSIVE", message: "缺少参数: pattern" };
+  try {
+    const content = readFileSync(join(cwd, path), "utf8");
+    const found = content.includes(pattern);
+    return {
+      outcome: found ? "COMPLETED" : "DEVIATED",
+      message: found ? `文件 ${path} 包含 "${pattern}"` : `文件 ${path} 不包含 "${pattern}"`,
+      actual: found ? "found" : "not-found",
+    };
+  } catch (e) {
+    return {
+      outcome: "INCONCLUSIVE",
+      message: `无法读取 ${path}: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}

package/src/verify/fs-exists.ts

@@ -0,0 +1,14 @@
+// src/verify/fs-exists.ts — 验证文件存在
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ProbeOutcome } from "../schema.js";
+
+export async function fsExists(cwd: string, params: Record<string, string>): Promise<ProbeOutcome> {
+  const path = params.path;
+  if (!path) return { outcome: "INCONCLUSIVE", message: "缺少参数: path" };
+  const exists = existsSync(join(cwd, path));
+  return {
+    outcome: exists ? "COMPLETED" : "DEVIATED",
+    message: exists ? `存在: ${path}` : `不存在: ${path}`,
+  };
+}

package/src/verify/fs-not-exists.ts

@@ -0,0 +1,17 @@
+// src/verify/fs-not-exists.ts — 验证文件不存在
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { ProbeOutcome } from "../schema.js";
+
+export async function fsNotExists(
+  cwd: string,
+  params: Record<string, string>
+): Promise<ProbeOutcome> {
+  const path = params.path;
+  if (!path) return { outcome: "INCONCLUSIVE", message: "缺少参数: path" };
+  const exists = existsSync(join(cwd, path));
+  return {
+    outcome: !exists ? "COMPLETED" : "DEVIATED",
+    message: !exists ? `已删除: ${path}` : `仍存在: ${path}`,
+  };
+}

package/src/verify/git-status-clean.ts

@@ -0,0 +1,23 @@
+// src/verify/git-status-clean.ts — 验证 git 工作树干净
+import { execSync } from "node:child_process";
+import type { ProbeOutcome } from "../schema.js";
+
+export async function gitStatusClean(
+  cwd: string,
+  _params: Record<string, string>
+): Promise<ProbeOutcome> {
+  try {
+    const out = execSync("git status --porcelain", { cwd, encoding: "utf8", timeout: 10000 });
+    const clean = out.trim() === "";
+    return {
+      outcome: clean ? "COMPLETED" : "DEVIATED",
+      message: clean ? "git 工作树干净" : `git 工作树有变更:\n${out.trim()}`,
+      actual: clean ? "clean" : "dirty",
+    };
+  } catch (e) {
+    return {
+      outcome: "INCONCLUSIVE",
+      message: `git 执行失败: ${e instanceof Error ? e.message : String(e)}`,
+    };
+  }
+}