@myclaw163/clawclaw-cli 0.6.66 → 0.6.68

package/src/lib/knowledge-store.ts

@@ -1,374 +1,369 @@
-/**
- * 策略知识系统 — 当前对局的「推断快照」存储。
- *
- * 设计要点（见 docs/策略知识系统-by-claude.md）:
- *  - 跨进程：Agent（短进程 CLI）写，strategy（长进程 loop）按 mtime 轮询读，免重启。
- *  - 快照而非日志：单个 JSON 对象，del/clear 直接重写；写入用临时文件 + rename 原子替换。
- *  - gameId 作用域：每份知识标记所属对局（= 最新 session 文件名），换局自动失效。
- *  - 价值中立：只存推断 + confidence/source，对 value 不做价值判断；
- *    确定事实（role/队友/尸体…）走 state/ctx.teammates，不入库。
- */
-import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
-import { basename, dirname, join } from 'path';
-import { AuthStore } from './auth.js';
-import { getProfileStateDir } from './init-command.js';
-import { EventStore } from '../pipeline/event-store.js';
-
-export type KnowledgeSource = 'agent' | 'strategy' | 'server';
-/** v1：仅 'game' 生效（整库按 gameId 失效）。'session'/'persistent' 为预留，暂不跨局保留——跨局画像走 memory.md，CLI 也不暴露 --scope。 */
-export type KnowledgeScope = 'game' | 'session' | 'persistent';
-
-export interface FactMeta {
-  value: unknown;
-  confidence?: number;
-  note?: string;
-  source?: KnowledgeSource;
-  ts: number;
-}
-
-export interface TagMeta {
-  confidence?: number;
-  note?: string;
-  source?: KnowledgeSource;
-  ts: number;
-}
-
-/** 一个 subject（玩家/房间/任务/全局…）上聚合的事实 + 标签。 */
-export interface SubjectEntry {
-  type: string;                          // 'player' | 'room' | 'task' | 'global' | <自定义>
-  selector: string;                      // player→座位号或名字；room→房名；global→''
-  facts?: Record<string, FactMeta>;      // 键值事实，如 role: { value: 'impostor' }
-  tags?: Record<string, TagMeta>;        // 玩家策略主标记：suspect / hostile / trusted；也支持自定义标签
-  scope?: KnowledgeScope;
-}
-
-export interface KnowledgeFile {
-  version: 1;
-  gameId?: string;
-  subjects: Record<string, SubjectEntry>;  // key = `${type}:${selector}`
-}
-
-export type KnowledgeFileReadResult =
-  | { status: 'ok'; file: KnowledgeFile }
-  | { status: 'missing' }
-  | { status: 'invalid'; error: string };
-
-export type PlayerRef = { name?: string; seat?: number };
-export type SubjectRef = { type: string; selector: string };
-export type KnowledgeRef = PlayerRef | SubjectRef;
-export type PlayerMark = 'suspect' | 'hostile' | 'trusted';
-
-export interface KnowledgeView {
-  /** 当前没有任何知识时为 true。 */
-  readonly empty: boolean;
-  /** 取一个 subject（精确 type + selector）。 */
-  subject(type: string, selector: string): SubjectEntry | undefined;
-  /** 取某 subject 的键值事实。player ref 会按座位↔名字归一化解析。 */
-  getFact(ref: KnowledgeRef, key: string): FactMeta | undefined;
-  /** 该 subject 是否带某标签（可选最低置信度门槛）。玩家三档 mark 及旧别名按最新结论解析。 */
-  hasTag(ref: KnowledgeRef, tag: string, minConfidence?: number): boolean;
-  /** 按 type / tag / factKey / 置信度筛选 subject。玩家 mark 标签同样遵守最新结论。 */
-  query(q: { type?: string; tag?: string; factKey?: string; minConfidence?: number }): SubjectEntry[];
-  /** 某 type 下带某标签的全部 selector（喂给 matchesAnyTarget 用）。玩家 mark 标签同样过滤旧结论。 */
-  selectorsWithTag(type: string, tag: string, minConfidence?: number): string[];
-  // —— player 便捷语法糖 ——
-  /** 最近一次 role 事实。身份事实与策略 mark 完全解耦。 */
-  roleOf(p: PlayerRef): string | undefined;
-  markOf(p: PlayerRef, minConfidence?: number): PlayerMark | undefined;
-  isSuspect(p: PlayerRef, minConfidence?: number): boolean;
-  isHostile(p: PlayerRef, minConfidence?: number): boolean;
-  isTrusted(p: PlayerRef, minConfidence?: number): boolean;
-  /** @deprecated Use isHostile. */
-  isConfirmedHostile(p: PlayerRef, minConfidence?: number): boolean;
-  /** @deprecated Use isTrusted. */
-  isCleared(p: PlayerRef): boolean;
-}
-
-const PLAYER_MARK_ALIASES: Record<string, PlayerMark> = {
-  suspect: 'suspect',
-  avoid: 'suspect',
-  hostile: 'hostile',
-  kill_if_armed: 'hostile',
-  trusted: 'trusted',
-  cleared: 'trusted',
-  protected: 'trusted',
-  do_not_kill: 'trusted',
-};
-
-function nowTs(): number {
-  return Date.now();
-}
-
-function subjectKey(type: string, selector: string): string {
-  return `${type}:${selector}`;
-}
-
-/** 座位↔名字双向解析（比 game-utils.matchesTarget 多了「selector 是名字、ref 只有座位」一向），不依赖 StrategyContext（避免循环）。 */
-function selectorMatchesPlayer(
-  selector: string,
-  player: PlayerRef,
-  playerNamesBySeat: Record<string, string>,
-): boolean {
-  const seatStr = selector.trim();
-  const normalized = seatStr.toLowerCase();
-  if (!normalized) return false;
-  if (player.name && player.name.toLowerCase() === normalized) return true;
-  if (/^\d+$/.test(seatStr)) {
-    // 选择器是座位号
-    if (player.seat != null && String(player.seat) === seatStr) return true;
-    const nameFromSeat = playerNamesBySeat[seatStr];
-    if (nameFromSeat && player.name && player.name.toLowerCase() === nameFromSeat.toLowerCase()) return true;
-  } else if (player.seat != null) {
-    // 选择器是名字、引用只有座位 → 用座位映射出名字再比
-    const nameFromSeat = playerNamesBySeat[String(player.seat)];
-    if (nameFromSeat && nameFromSeat.toLowerCase() === normalized) return true;
-  }
-  return false;
-}
-
-function isSubjectRef(ref: KnowledgeRef): ref is SubjectRef {
-  return typeof (ref as SubjectRef).type === 'string' && typeof (ref as SubjectRef).selector === 'string';
-}
-
-/** 当前对局 id = 最新 session 文件名（去扩展名）；无对局时 undefined。 */
-export function currentGameId(): string | undefined {
-  try {
-    const path = EventStore.latestSessionPath();
-    return path ? basename(path, '.jsonl') : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-export function knowledgeFilePathForActiveAccount(): string {
-  const profile = new AuthStore().getActive();
-  if (!profile) throw new Error('Not logged in.');
-  return join(getProfileStateDir(profile), 'knowledge.json');
-}
-
-export function readKnowledgeFileResult(path: string): KnowledgeFileReadResult {
-  if (!existsSync(path)) return { status: 'missing' };
-  try {
-    const parsed = JSON.parse(readFileSync(path, 'utf8'));
-    if (parsed && parsed.version === 1 && parsed.subjects && typeof parsed.subjects === 'object') {
-      return { status: 'ok', file: parsed as KnowledgeFile };
-    }
-    return { status: 'invalid', error: 'invalid knowledge file shape' };
-  } catch (err) {
-    return { status: 'invalid', error: err instanceof Error ? err.message : String(err) };
-  }
-}
-
-/** 读 knowledge.json；不存在 / 解析失败 / 结构不对都返回 null。需要区分错误原因时用 readKnowledgeFileResult。 */
-export function readKnowledgeFile(path: string): KnowledgeFile | null {
-  const result = readKnowledgeFileResult(path);
-  return result.status === 'ok' ? result.file : null;
-}
-
-/** 临时文件 + rename 原子替换，避免读端读到写一半的 JSON。 */
-export function writeKnowledgeFileAtomic(path: string, file: KnowledgeFile): void {
-  mkdirSync(dirname(path), { recursive: true });
-  const tmp = `${path}.tmp.${process.pid}`;
-  writeFileSync(tmp, JSON.stringify(file, null, 2));
-  renameSync(tmp, path);
-}
-
-export interface KnowledgeSetInput {
-  type: string;
-  selector: string;
-  key?: string;
-  value?: unknown;
-  tags?: string[];
-  removeTags?: string[];
-  confidence?: number;
-  note?: string;
-  source?: KnowledgeSource;
-  scope?: KnowledgeScope;
-}
-
-/** Agent 侧读-改-写句柄；CLI 命令使用。strategy 侧只读，用 buildKnowledgeView。 */
-export class KnowledgeStore {
-  constructor(
-    private readonly path: string,
-    readonly gameId?: string,
-  ) {}
-
-  static forActiveAccount(): KnowledgeStore {
-    return new KnowledgeStore(knowledgeFilePathForActiveAccount(), currentGameId());
-  }
-
-  /** 读当前文件；若不存在或属于别的对局，返回该对局的空文件（旧局知识自动失效）。 */
-  load(): KnowledgeFile {
-    const file = readKnowledgeFile(this.path);
-    if (file && file.gameId === this.gameId) return file;
-    return { version: 1, gameId: this.gameId, subjects: {} };
-  }
-
-  private save(file: KnowledgeFile): void {
-    writeKnowledgeFileAtomic(this.path, file);
-  }
-
-  set(input: KnowledgeSetInput): SubjectEntry {
-    if (!input.type || !input.selector) throw new Error('knowledge set requires type and selector');
-    if (input.confidence != null && (!Number.isFinite(input.confidence) || input.confidence < 0 || input.confidence > 1)) {
-      throw new Error('confidence must be a finite number between 0 and 1');
-    }
-    const file = this.load();
-    const key = subjectKey(input.type, input.selector);
-    const entry: SubjectEntry = file.subjects[key] ?? { type: input.type, selector: input.selector };
-    const ts = nowTs();
-    const source = input.source ?? 'agent';
-
-    if (input.key != null) {
-      entry.facts = entry.facts ?? {};
-      entry.facts[input.key] = {
-        value: input.value === undefined ? true : input.value,
-        confidence: input.confidence,
-        note: input.note,
-        source,
-        ts,
-      };
-    }
-    if (input.tags && input.tags.length > 0) {
-      entry.tags = entry.tags ?? {};
-      for (const tag of input.tags) {
-        if (!tag) continue;
-        entry.tags[tag] = { confidence: input.confidence, note: input.note, source, ts };
-      }
-    }
-    if (input.removeTags && entry.tags) {
-      for (const tag of input.removeTags) delete entry.tags[tag];
-    }
-    if (input.scope) entry.scope = input.scope;
-
-    file.subjects[key] = entry;
-    this.save(file);
-    return entry;
-  }
-
-  /** 删整个 subject，或仅删某个 fact / tag；删空后自动清除该 subject。 */
-  del(type: string, selector: string, opts?: { key?: string; tag?: string }): boolean {
-    const file = this.load();
-    const key = subjectKey(type, selector);
-    const entry = file.subjects[key];
-    if (!entry) return false;
-
-    if (!opts?.key && !opts?.tag) {
-      delete file.subjects[key];
-      this.save(file);
-      return true;
-    }
-    if (opts.key && entry.facts) delete entry.facts[opts.key];
-    if (opts.tag && entry.tags) delete entry.tags[opts.tag];
-    const noFacts = !entry.facts || Object.keys(entry.facts).length === 0;
-    const noTags = !entry.tags || Object.keys(entry.tags).length === 0;
-    if (noFacts && noTags) delete file.subjects[key];
-    this.save(file);
-    return true;
-  }
-
-  clear(): void {
-    this.save({ version: 1, gameId: this.gameId, subjects: {} });
-  }
-
-  list(): KnowledgeFile {
-    return this.load();
-  }
-}
-
-/** 由 strategy-loop 每次重载时构造。playerNamesBySeat 传入活引用即可，座位解析始终最新。 */
-export function buildKnowledgeView(
-  file: KnowledgeFile | null,
-  opts: { playerNamesBySeat?: Record<string, string> } = {},
-): KnowledgeView {
-  const subjects = file?.subjects ?? {};
-  const namesBySeat = opts.playerNamesBySeat ?? {};
-  const confOk = (conf: number | undefined, min?: number): boolean => min == null || (conf ?? 1) >= min;
-
-  const resolveAll = (ref: KnowledgeRef): SubjectEntry[] => {
-    if (isSubjectRef(ref)) {
-      const s = subjects[subjectKey(ref.type, ref.selector)];
-      return s ? [s] : [];
-    }
-    return Object.values(subjects).filter((s) => s.type === 'player' && selectorMatchesPlayer(s.selector, ref, namesBySeat));
-  };
-
-  const latestFact = (ref: KnowledgeRef, key: string): FactMeta | undefined => {
-    let best: FactMeta | undefined;
-    for (const s of resolveAll(ref)) {
-      const f = s.facts?.[key];
-      if (f && (!best || f.ts > best.ts)) best = f;
-    }
-    return best;
-  };
-
-  type MarkVerdict = { kind: PlayerMark; ts: number; confidence?: number };
-  const markRank = (kind: PlayerMark): number => kind === 'trusted' ? 3 : kind === 'hostile' ? 2 : 1;
-  const latestMark = (ref: KnowledgeRef): MarkVerdict | undefined => {
-    let best: MarkVerdict | undefined;
-    const take = (v: MarkVerdict) => {
-      if (!best
-          || v.ts > best.ts
-          || (v.ts === best.ts && markRank(v.kind) > markRank(best.kind))) {
-        best = v;
-      }
-    };
-    for (const s of resolveAll(ref)) {
-      for (const [tag, meta] of Object.entries(s.tags ?? {})) {
-        const kind = PLAYER_MARK_ALIASES[tag];
-        if (kind) take({ kind, ts: meta.ts, confidence: meta.confidence });
-      }
-    }
-    return best;
-  };
-
-  const markKindForTag = (tag: string): PlayerMark | undefined => PLAYER_MARK_ALIASES[tag];
-  const tagActive = (s: SubjectEntry, tag: string, min?: number): boolean => {
-    const requestedMark = markKindForTag(tag);
-    if (s.type === 'player' && requestedMark) {
-      const carriesRequestedMark = Object.keys(s.tags ?? {}).some(candidate => markKindForTag(candidate) === requestedMark);
-      if (!carriesRequestedMark) return false;
-      const ref: PlayerRef = /^\d+$/.test(s.selector.trim()) ? { seat: Number(s.selector) } : { name: s.selector };
-      const mark = latestMark(ref);
-      return !!mark && mark.kind === requestedMark && confOk(mark.confidence, min);
-    }
-    const meta = s.tags?.[tag];
-    return !!meta && confOk(meta.confidence, min);
-  };
-
-  return {
-    empty: Object.keys(subjects).length === 0,
-    subject: (type, selector) => subjects[subjectKey(type, selector)],
-    getFact: (ref, key) => latestFact(ref, key),
-    hasTag: (ref, tag, min) => resolveAll(ref).some((s) => tagActive(s, tag, min)),
-    query: (q) => Object.values(subjects).filter((s) => {
-      if (q.type && s.type !== q.type) return false;
-      if (q.factKey) {
-        const f = s.facts?.[q.factKey];
-        if (!f || !confOk(f.confidence, q.minConfidence)) return false;
-      }
-      if (q.tag && !tagActive(s, q.tag, q.minConfidence)) return false;
-      return true;
-    }),
-    selectorsWithTag: (type, tag, min) => Object.values(subjects)
-      .filter((s) => s.type === type && tagActive(s, tag, min))
-      .map((s) => s.selector),
-    roleOf: (p) => {
-      const fact = latestFact(p, 'role');
-      return typeof fact?.value === 'string' ? fact.value : undefined;
-    },
-    markOf: (p, min) => {
-      const mark = latestMark(p);
-      return mark && confOk(mark.confidence, min) ? mark.kind : undefined;
-    },
-    isSuspect: (p, min) => latestMark(p)?.kind === 'suspect' && confOk(latestMark(p)?.confidence, min),
-    isHostile: (p, min) => latestMark(p)?.kind === 'hostile' && confOk(latestMark(p)?.confidence, min),
-    isTrusted: (p, min) => latestMark(p)?.kind === 'trusted' && confOk(latestMark(p)?.confidence, min),
-    isConfirmedHostile: (p, min) => latestMark(p)?.kind === 'hostile' && confOk(latestMark(p)?.confidence, min),
-    isCleared: (p) => latestMark(p)?.kind === 'trusted',
-  };
-}
-
-export function emptyKnowledgeView(): KnowledgeView {
-  return buildKnowledgeView(null);
-}
+/**
+ * 策略知识系统 — 当前对局的「推断快照」存储。
+ *
+ * 设计要点（见 docs/策略知识系统-by-claude.md）:
+ *  - 跨进程：Agent（短进程 CLI）写，strategy（长进程 loop）按 mtime 轮询读，免重启。
+ *  - 快照而非日志：单个 JSON 对象，del/clear 直接重写；写入用临时文件 + rename 原子替换。
+ *  - gameId 作用域：每份知识标记所属对局（= 最新 session 文件名），换局自动失效。
+ *  - 价值中立：只存推断 + source，对 value 不做价值判断；
+ *    确定事实（role/队友/尸体…）走 state/ctx.teammates，不入库。
+ *  - 玩家两档标记：只显式标 hostile（坏人）/ trusted（好人），未标记的一律默认「被怀疑」，不再有 suspect 标记，也不存置信度。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'fs';
+import { basename, dirname, join } from 'path';
+import { AuthStore } from './auth.js';
+import { getProfileStateDir } from './init-command.js';
+import { EventStore } from '../pipeline/event-store.js';
+
+export type KnowledgeSource = 'agent' | 'strategy' | 'server';
+/** v1：仅 'game' 生效（整库按 gameId 失效）。'session'/'persistent' 为预留，暂不跨局保留——跨局画像走 memory.md，CLI 也不暴露 --scope。 */
+export type KnowledgeScope = 'game' | 'session' | 'persistent';
+
+export interface FactMeta {
+  value: unknown;
+  note?: string;
+  source?: KnowledgeSource;
+  ts: number;
+}
+
+export interface TagMeta {
+  note?: string;
+  source?: KnowledgeSource;
+  ts: number;
+}
+
+/** 一个 subject（玩家/房间/任务/全局…）上聚合的事实 + 标签。 */
+export interface SubjectEntry {
+  type: string;                          // 'player' | 'room' | 'task' | 'global' | <自定义>
+  selector: string;                      // player→座位号或名字；room→房名；global→''
+  facts?: Record<string, FactMeta>;      // 键值事实，如 role: { value: 'impostor' }
+  tags?: Record<string, TagMeta>;        // 玩家策略主标记：hostile / trusted（未标记默认被怀疑）；也支持自定义标签
+  scope?: KnowledgeScope;
+}
+
+export interface KnowledgeFile {
+  version: 1;
+  gameId?: string;
+  subjects: Record<string, SubjectEntry>;  // key = `${type}:${selector}`
+}
+
+export type KnowledgeFileReadResult =
+  | { status: 'ok'; file: KnowledgeFile }
+  | { status: 'missing' }
+  | { status: 'invalid'; error: string };
+
+export type PlayerRef = { name?: string; seat?: number };
+export type SubjectRef = { type: string; selector: string };
+export type KnowledgeRef = PlayerRef | SubjectRef;
+/** 玩家显式标记只有两档：hostile（坏人）/ trusted（好人）。未标记 = 被怀疑（markOf 返回 undefined）。 */
+export type PlayerMark = 'hostile' | 'trusted';
+
+export interface KnowledgeView {
+  /** 当前没有任何知识时为 true。 */
+  readonly empty: boolean;
+  /** 取一个 subject（精确 type + selector）。 */
+  subject(type: string, selector: string): SubjectEntry | undefined;
+  /** 取某 subject 的键值事实。player ref 会按座位↔名字归一化解析。 */
+  getFact(ref: KnowledgeRef, key: string): FactMeta | undefined;
+  /** 该 subject 是否带某标签。玩家两档 mark 及旧别名按最新结论解析。 */
+  hasTag(ref: KnowledgeRef, tag: string): boolean;
+  /** 按 type / tag / factKey 筛选 subject。玩家 mark 标签同样遵守最新结论。 */
+  query(q: { type?: string; tag?: string; factKey?: string }): SubjectEntry[];
+  /** 某 type 下带某标签的全部 selector（喂给 matchesAnyTarget 用）。玩家 mark 标签同样过滤旧结论。 */
+  selectorsWithTag(type: string, tag: string): string[];
+  // —— player 便捷语法糖 ——
+  /** 最近一次 role 事实。身份事实与策略 mark 完全解耦。 */
+  roleOf(p: PlayerRef): string | undefined;
+  /** 最新显式标记；未标记返回 undefined（= 被怀疑）。 */
+  markOf(p: PlayerRef): PlayerMark | undefined;
+  /** 被怀疑 = 既非 hostile 也非 trusted（含完全未标记者）。 */
+  isSuspect(p: PlayerRef): boolean;
+  isHostile(p: PlayerRef): boolean;
+  isTrusted(p: PlayerRef): boolean;
+}
+
+const PLAYER_MARK_ALIASES: Record<string, PlayerMark> = {
+  hostile: 'hostile',
+  kill_if_armed: 'hostile',
+  trusted: 'trusted',
+  cleared: 'trusted',
+  protected: 'trusted',
+  do_not_kill: 'trusted',
+};
+
+/**
+ * 两档化后被废弃的旧玩家标记：一律视同未标记（= 被怀疑），不映射到任何 canonical mark
+ *（「被怀疑」就是默认态，没有对应标签）。读取侧与写入侧共用这一份清单，避免漂移：
+ *  - 读取侧（buildKnowledgeView.tagActive）：旧数据里的 tags.suspect / tags.avoid 不再被 hasTag / query / selectorsWithTag 命中。
+ *  - 写入侧（knowledge mark 的 removeTags）：改判玩家时顺手删掉残留的 raw tag，否则 knowledge get / subject() 仍会暴露 tags.suspect/avoid 误导人。
+ */
+export const DROPPED_PLAYER_MARK_TAGS = new Set(['suspect', 'avoid']);
+
+function nowTs(): number {
+  return Date.now();
+}
+
+function subjectKey(type: string, selector: string): string {
+  return `${type}:${selector}`;
+}
+
+/** 座位↔名字双向解析（比 game-utils.matchesTarget 多了「selector 是名字、ref 只有座位」一向），不依赖 StrategyContext（避免循环）。 */
+function selectorMatchesPlayer(
+  selector: string,
+  player: PlayerRef,
+  playerNamesBySeat: Record<string, string>,
+): boolean {
+  const seatStr = selector.trim();
+  const normalized = seatStr.toLowerCase();
+  if (!normalized) return false;
+  if (player.name && player.name.toLowerCase() === normalized) return true;
+  if (/^\d+$/.test(seatStr)) {
+    // 选择器是座位号
+    if (player.seat != null && String(player.seat) === seatStr) return true;
+    const nameFromSeat = playerNamesBySeat[seatStr];
+    if (nameFromSeat && player.name && player.name.toLowerCase() === nameFromSeat.toLowerCase()) return true;
+  } else if (player.seat != null) {
+    // 选择器是名字、引用只有座位 → 用座位映射出名字再比
+    const nameFromSeat = playerNamesBySeat[String(player.seat)];
+    if (nameFromSeat && nameFromSeat.toLowerCase() === normalized) return true;
+  }
+  return false;
+}
+
+function isSubjectRef(ref: KnowledgeRef): ref is SubjectRef {
+  return typeof (ref as SubjectRef).type === 'string' && typeof (ref as SubjectRef).selector === 'string';
+}
+
+/** 当前对局 id = 最新 session 文件名（去扩展名）；无对局时 undefined。 */
+export function currentGameId(): string | undefined {
+  try {
+    const path = EventStore.latestSessionPath();
+    return path ? basename(path, '.jsonl') : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function knowledgeFilePathForActiveAccount(): string {
+  const profile = new AuthStore().getActive();
+  if (!profile) throw new Error('Not logged in.');
+  return join(getProfileStateDir(profile), 'knowledge.json');
+}
+
+export function readKnowledgeFileResult(path: string): KnowledgeFileReadResult {
+  if (!existsSync(path)) return { status: 'missing' };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (parsed && parsed.version === 1 && parsed.subjects && typeof parsed.subjects === 'object') {
+      return { status: 'ok', file: parsed as KnowledgeFile };
+    }
+    return { status: 'invalid', error: 'invalid knowledge file shape' };
+  } catch (err) {
+    return { status: 'invalid', error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** 读 knowledge.json；不存在 / 解析失败 / 结构不对都返回 null。需要区分错误原因时用 readKnowledgeFileResult。 */
+export function readKnowledgeFile(path: string): KnowledgeFile | null {
+  const result = readKnowledgeFileResult(path);
+  return result.status === 'ok' ? result.file : null;
+}
+
+/** 临时文件 + rename 原子替换，避免读端读到写一半的 JSON。 */
+export function writeKnowledgeFileAtomic(path: string, file: KnowledgeFile): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(file, null, 2));
+  renameSync(tmp, path);
+}
+
+export interface KnowledgeSetInput {
+  type: string;
+  selector: string;
+  key?: string;
+  value?: unknown;
+  tags?: string[];
+  removeTags?: string[];
+  note?: string;
+  source?: KnowledgeSource;
+  scope?: KnowledgeScope;
+}
+
+/** Agent 侧读-改-写句柄；CLI 命令使用。strategy 侧只读，用 buildKnowledgeView。 */
+export class KnowledgeStore {
+  constructor(
+    private readonly path: string,
+    readonly gameId?: string,
+  ) {}
+
+  static forActiveAccount(): KnowledgeStore {
+    return new KnowledgeStore(knowledgeFilePathForActiveAccount(), currentGameId());
+  }
+
+  /** 读当前文件；若不存在或属于别的对局，返回该对局的空文件（旧局知识自动失效）。 */
+  load(): KnowledgeFile {
+    const file = readKnowledgeFile(this.path);
+    if (file && file.gameId === this.gameId) return file;
+    return { version: 1, gameId: this.gameId, subjects: {} };
+  }
+
+  private save(file: KnowledgeFile): void {
+    writeKnowledgeFileAtomic(this.path, file);
+  }
+
+  set(input: KnowledgeSetInput): SubjectEntry {
+    if (!input.type || !input.selector) throw new Error('knowledge set requires type and selector');
+    const file = this.load();
+    const key = subjectKey(input.type, input.selector);
+    const entry: SubjectEntry = file.subjects[key] ?? { type: input.type, selector: input.selector };
+    const ts = nowTs();
+    const source = input.source ?? 'agent';
+
+    if (input.key != null) {
+      entry.facts = entry.facts ?? {};
+      entry.facts[input.key] = {
+        value: input.value === undefined ? true : input.value,
+        note: input.note,
+        source,
+        ts,
+      };
+    }
+    if (input.tags && input.tags.length > 0) {
+      entry.tags = entry.tags ?? {};
+      for (const tag of input.tags) {
+        if (!tag) continue;
+        entry.tags[tag] = { note: input.note, source, ts };
+      }
+    }
+    if (input.removeTags && entry.tags) {
+      for (const tag of input.removeTags) delete entry.tags[tag];
+    }
+    if (input.scope) entry.scope = input.scope;
+
+    file.subjects[key] = entry;
+    this.save(file);
+    return entry;
+  }
+
+  /** 删整个 subject，或仅删某个 fact / tag；删空后自动清除该 subject。 */
+  del(type: string, selector: string, opts?: { key?: string; tag?: string }): boolean {
+    const file = this.load();
+    const key = subjectKey(type, selector);
+    const entry = file.subjects[key];
+    if (!entry) return false;
+
+    if (!opts?.key && !opts?.tag) {
+      delete file.subjects[key];
+      this.save(file);
+      return true;
+    }
+    if (opts.key && entry.facts) delete entry.facts[opts.key];
+    if (opts.tag && entry.tags) delete entry.tags[opts.tag];
+    const noFacts = !entry.facts || Object.keys(entry.facts).length === 0;
+    const noTags = !entry.tags || Object.keys(entry.tags).length === 0;
+    if (noFacts && noTags) delete file.subjects[key];
+    this.save(file);
+    return true;
+  }
+
+  clear(): void {
+    this.save({ version: 1, gameId: this.gameId, subjects: {} });
+  }
+
+  list(): KnowledgeFile {
+    return this.load();
+  }
+}
+
+/** 由 strategy-loop 每次重载时构造。playerNamesBySeat 传入活引用即可，座位解析始终最新。 */
+export function buildKnowledgeView(
+  file: KnowledgeFile | null,
+  opts: { playerNamesBySeat?: Record<string, string> } = {},
+): KnowledgeView {
+  const subjects = file?.subjects ?? {};
+  const namesBySeat = opts.playerNamesBySeat ?? {};
+
+  const resolveAll = (ref: KnowledgeRef): SubjectEntry[] => {
+    if (isSubjectRef(ref)) {
+      const s = subjects[subjectKey(ref.type, ref.selector)];
+      return s ? [s] : [];
+    }
+    return Object.values(subjects).filter((s) => s.type === 'player' && selectorMatchesPlayer(s.selector, ref, namesBySeat));
+  };
+
+  const latestFact = (ref: KnowledgeRef, key: string): FactMeta | undefined => {
+    let best: FactMeta | undefined;
+    for (const s of resolveAll(ref)) {
+      const f = s.facts?.[key];
+      if (f && (!best || f.ts > best.ts)) best = f;
+    }
+    return best;
+  };
+
+  type MarkVerdict = { kind: PlayerMark; ts: number };
+  // 同一时刻打了冲突标记时，trusted 优先级高于 hostile（好人判断更慎重，不轻易被覆盖）。
+  const markRank = (kind: PlayerMark): number => kind === 'trusted' ? 2 : 1;
+  const latestMark = (ref: KnowledgeRef): MarkVerdict | undefined => {
+    let best: MarkVerdict | undefined;
+    const take = (v: MarkVerdict) => {
+      if (!best
+          || v.ts > best.ts
+          || (v.ts === best.ts && markRank(v.kind) > markRank(best.kind))) {
+        best = v;
+      }
+    };
+    for (const s of resolveAll(ref)) {
+      for (const [tag, meta] of Object.entries(s.tags ?? {})) {
+        const kind = PLAYER_MARK_ALIASES[tag];
+        if (kind) take({ kind, ts: meta.ts });
+      }
+    }
+    return best;
+  };
+
+  const markKindForTag = (tag: string): PlayerMark | undefined => PLAYER_MARK_ALIASES[tag];
+  const tagActive = (s: SubjectEntry, tag: string): boolean => {
+    if (s.type === 'player') {
+      const requestedMark = markKindForTag(tag);
+      if (requestedMark) {
+        const carriesRequestedMark = Object.keys(s.tags ?? {}).some(candidate => markKindForTag(candidate) === requestedMark);
+        if (!carriesRequestedMark) return false;
+        const ref: PlayerRef = /^\d+$/.test(s.selector.trim()) ? { seat: Number(s.selector) } : { name: s.selector };
+        const mark = latestMark(ref);
+        return !!mark && mark.kind === requestedMark;
+      }
+      // 废弃的旧玩家标记（suspect/avoid）= 未标记 = 被怀疑，绝不命中；其余自定义标签（如 paradise_fish）照常按原值判定。
+      if (DROPPED_PLAYER_MARK_TAGS.has(tag)) return false;
+    }
+    return !!s.tags?.[tag];
+  };
+
+  return {
+    empty: Object.keys(subjects).length === 0,
+    subject: (type, selector) => subjects[subjectKey(type, selector)],
+    getFact: (ref, key) => latestFact(ref, key),
+    hasTag: (ref, tag) => resolveAll(ref).some((s) => tagActive(s, tag)),
+    query: (q) => Object.values(subjects).filter((s) => {
+      if (q.type && s.type !== q.type) return false;
+      if (q.factKey && !s.facts?.[q.factKey]) return false;
+      if (q.tag && !tagActive(s, q.tag)) return false;
+      return true;
+    }),
+    selectorsWithTag: (type, tag) => Object.values(subjects)
+      .filter((s) => s.type === type && tagActive(s, tag))
+      .map((s) => s.selector),
+    roleOf: (p) => {
+      const fact = latestFact(p, 'role');
+      return typeof fact?.value === 'string' ? fact.value : undefined;
+    },
+    markOf: (p) => latestMark(p)?.kind,
+    // 未标记 hostile/trusted 的玩家一律「被怀疑」——这就是「除好人坏人外剩下全是被怀疑」的落点。
+    isSuspect: (p) => !latestMark(p),
+    isHostile: (p) => latestMark(p)?.kind === 'hostile',
+    isTrusted: (p) => latestMark(p)?.kind === 'trusted',
+  };
+}
+
+export function emptyKnowledgeView(): KnowledgeView {
+  return buildKnowledgeView(null);
+}