@yancyyu/openhermit 1.6.42 → 1.6.43

package/src/features/worker-society/renderer/societyGraphAdapter.test.ts

@@ -0,0 +1,321 @@
+/**
+ * SocietyGraphAdapter — projection tests (test-first).
+ *
+ * Verifies the pure mapping from worker-society domain (workers / active needs /
+ * relationships) into the reusable @claude-teams/agent-graph port model, so the
+ * cyan/space holographic graph can render the decentralized agora.
+ *
+ * Determinism: no Math.random, no FS/network — same input ⇒ identical output.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { projectSocietyGraph } from './societyGraphAdapter';
+import type { PublishedNeed, Relationship, WorkerProfile } from '../core/domain/models/society';
+
+const TEAM = 'worker-society';
+
+function worker(over: Partial<WorkerProfile> & { workerId: string }): WorkerProfile {
+  return {
+    name: over.workerId,
+    kind: 'atomic',
+    capabilities: [],
+    interests: [],
+    maxConcurrent: 2,
+    activeTaskCount: 0,
+    reputation: 50,
+    status: 'online',
+    ...over,
+  };
+}
+
+function need(over: Partial<PublishedNeed> & { needId: string }): PublishedNeed {
+  return {
+    postedBy: 'user',
+    subject: over.subject ?? `need-${over.needId}`,
+    requiredCapabilities: [],
+    priority: 5,
+    status: 'open',
+    volunteers: [],
+    revisionCount: 0,
+    createdAt: '2026-01-01T00:00:00.000Z',
+    ...over,
+  };
+}
+
+const rel = (
+  fromWorker: string,
+  toWorker: string,
+  over: Partial<Relationship> = {}
+): Relationship => ({
+  fromWorker,
+  toWorker,
+  collaborations: 3,
+  successes: 2,
+  trust: 0.6,
+  lastInteractedAt: '2026-01-01T00:00:00.000Z',
+  ...over,
+});
+
+describe('projectSocietyGraph', () => {
+  it('returns an empty, dead port when there is no society at all', () => {
+    const out = projectSocietyGraph({ workers: [], needs: [], relationships: [] });
+    expect(out.nodes).toEqual([]);
+    expect(out.edges).toEqual([]);
+    expect(out.particles).toEqual([]);
+    expect(out.teamName).toBe(TEAM);
+    expect(out.isAlive).toBe(false);
+  });
+
+  it('places a synthetic Agora hub at the center and parents every worker to it', () => {
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' }), worker({ workerId: 'bob' })],
+      needs: [],
+      relationships: [],
+    });
+    const agora = out.nodes.find((n) => n.kind === 'lead');
+    expect(agora).toMatchObject({ kind: 'lead', state: 'active' });
+    expect(agora?.id).toBe(`agora:${TEAM}`);
+
+    // both workers are member nodes
+    const members = out.nodes.filter((n) => n.kind === 'member');
+    expect(members.map((m) => m.id).sort()).toEqual(['worker:alice', 'worker:bob']);
+
+    // each worker has a parent-child edge from the agora
+    for (const memberId of ['worker:alice', 'worker:bob']) {
+      expect(
+        out.edges.some(
+          (e) => e.source === `agora:${TEAM}` && e.target === memberId && e.type === 'parent-child'
+        )
+      ).toBe(true);
+    }
+    expect(out.isAlive).toBe(true);
+  });
+
+  it('maps worker activity to node state: idle when free, active when carrying tasks', () => {
+    const out = projectSocietyGraph({
+      workers: [
+        worker({ workerId: 'idle1', activeTaskCount: 0, status: 'online' }),
+        worker({ workerId: 'busy1', activeTaskCount: 1, status: 'online' }),
+        worker({ workerId: 'busy2', status: 'busy' }),
+        worker({ workerId: 'off1', status: 'offline' }),
+      ],
+      needs: [],
+      relationships: [],
+    });
+    const state = (id: string) => out.nodes.find((n) => n.id === id)?.state;
+    expect(state('worker:idle1')).toBe('idle');
+    expect(state('worker:busy1')).toBe('active');
+    expect(state('worker:busy2')).toBe('active');
+    // offline workers stay visible but idle (not terminated/hidden)
+    expect(state('worker:off1')).toBe('idle');
+  });
+
+  it('turns an assigned, in-progress need into a task orbiting its assignee with a flowing particle', () => {
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' })],
+      needs: [need({ needId: 'n1', status: 'in_progress', assignee: 'alice' })],
+      relationships: [],
+    });
+    const task = out.nodes.find((n) => n.id === 'need:n1');
+    expect(task).toMatchObject({
+      kind: 'task',
+      state: 'active',
+      ownerId: 'worker:alice',
+      taskStatus: 'in_progress',
+    });
+
+    // ownership edge assignee -> task
+    const ownEdge = out.edges.find(
+      (e) => e.source === 'worker:alice' && e.target === 'need:n1' && e.type === 'ownership'
+    );
+    expect(ownEdge).toBeTruthy();
+
+    // a particle travels that edge (work in flight)
+    const particle = out.particles.find((p) => p.edgeId === ownEdge!.id);
+    expect(particle).toMatchObject({ kind: 'task_assign', progress: 0 });
+    expect(particle?.color).toMatch(/^#[0-9a-f]{6}$/i);
+  });
+
+  it('anchors an open, unclaimed need to the agora (not orphaned): waiting task, no owner/particle', () => {
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' })],
+      needs: [need({ needId: 'n-open', status: 'open' })],
+      relationships: [],
+    });
+    const task = out.nodes.find((n) => n.id === 'need:n-open');
+    expect(task).toMatchObject({ kind: 'task', state: 'waiting', ownerId: null });
+    // 无指派人 → 锚定到广场（parent-child），不再是孤立浮点；但仍无 ownership 边、无粒子。
+    expect(
+      out.edges.find(
+        (e) =>
+          e.source === `agora:${TEAM}` && e.target === 'need:n-open' && e.type === 'parent-child'
+      )
+    ).toBeTruthy();
+    expect(out.edges.some((e) => e.type === 'ownership' && e.target === 'need:n-open')).toBe(false);
+    expect(out.particles.some((p) => p.edgeId.includes('need:n-open'))).toBe(false);
+  });
+
+  it("joins a visible need's required capabilities into the task sublabel", () => {
+    // L166 真臂：`need.requiredCapabilities.length > 0 ? join(' · ') : undefined`。既有可见 need
+    // 测试都用 need() 默认 []（假臂→sublabel undefined），真臂（带能力→拼成 sublabel）未覆盖。
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' })],
+      needs: [
+        need({ needId: 'n-cap', status: 'open', requiredCapabilities: ['frontend', 'design'] }),
+      ],
+      relationships: [],
+    });
+    expect(out.nodes.find((n) => n.id === 'need:n-cap')?.sublabel).toBe('frontend · design');
+  });
+
+  it('maps delivered needs to a complete task state with no in-flight particle', () => {
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' })],
+      needs: [need({ needId: 'n-done', status: 'delivered', assignee: 'alice' })],
+      relationships: [],
+    });
+    const task = out.nodes.find((n) => n.id === 'need:n-done');
+    expect(task).toMatchObject({
+      kind: 'task',
+      state: 'complete',
+      taskStatus: 'completed',
+      ownerId: 'worker:alice',
+    });
+    expect(out.particles.length).toBe(0);
+  });
+
+  it('drops closed / expired / cancelled needs entirely', () => {
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' })],
+      needs: [
+        need({ needId: 'gone', status: 'closed', assignee: 'alice' }),
+        need({ needId: 'stale', status: 'expired' }),
+        need({ needId: 'axed', status: 'cancelled' }),
+      ],
+      relationships: [],
+    });
+    expect(out.nodes.some((n) => n.id.startsWith('need:'))).toBe(false);
+    expect(out.particles.length).toBe(0);
+  });
+
+  it('renders a relationship as a single related edge even when both directions exist', () => {
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' }), worker({ workerId: 'bob' })],
+      needs: [],
+      relationships: [
+        rel('alice', 'bob', { collaborations: 4 }),
+        rel('bob', 'alice', { collaborations: 2 }),
+      ],
+    });
+    const related = out.edges.filter((e) => e.type === 'related');
+    expect(related).toHaveLength(1);
+    const edge = related[0];
+    expect([edge.source, edge.target].sort()).toEqual(['worker:alice', 'worker:bob']);
+  });
+
+  it('skips relationships that reference unknown workers', () => {
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' })],
+      needs: [],
+      relationships: [rel('alice', 'ghost'), rel('ghost1', 'ghost2')],
+    });
+    expect(out.edges.filter((e) => e.type === 'related')).toHaveLength(0);
+  });
+
+  it('skips a self-relationship (fromWorker === toWorker) — no self-loop edge', () => {
+    // L198 真臂 `if (r.fromWorker === r.toWorker) continue`：自指关系跳过，不产生自环 related 边。
+    // 既有关系测试都用不同 worker（假臂：alice↔bob / alice→ghost），自指真臂未覆盖。
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' })],
+      needs: [],
+      relationships: [rel('alice', 'alice')],
+    });
+    expect(out.edges.filter((e) => e.type === 'related')).toHaveLength(0);
+  });
+
+  it('produces a radial layout port whose owner order is the worker node ids', () => {
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' }), worker({ workerId: 'bob' })],
+      needs: [],
+      relationships: [],
+    });
+    expect(out.layout?.mode).toBe('radial');
+    expect(out.layout?.ownerOrder.sort()).toEqual(['worker:alice', 'worker:bob']);
+    // every owner in the order has a matching member node
+    for (const ownerId of out.layout?.ownerOrder ?? []) {
+      expect(out.nodes.some((n) => n.id === ownerId && n.kind === 'member')).toBe(true);
+    }
+  });
+
+  it('is deterministic: identical input yields identical output', () => {
+    const input = {
+      workers: [worker({ workerId: 'alice' }), worker({ workerId: 'bob', activeTaskCount: 1 })],
+      needs: [need({ needId: 'n1', status: 'in_progress', assignee: 'bob' })],
+      relationships: [rel('alice', 'bob')],
+    };
+    const a = projectSocietyGraph(input);
+    const b = projectSocietyGraph(input);
+    expect(b).toEqual(a);
+  });
+
+  it('attaches a resolved avatar url to worker nodes when a resolver is provided', () => {
+    const out = projectSocietyGraph(
+      {
+        workers: [worker({ workerId: 'alice' }), worker({ workerId: 'bob' })],
+        needs: [],
+        relationships: [],
+      },
+      { resolveAvatarUrl: (id) => `img:${id}.png` }
+    );
+    const avatar = (id: string) => out.nodes.find((n) => n.id === id)?.avatarUrl;
+    expect(avatar('worker:alice')).toBe('img:alice.png');
+    expect(avatar('worker:bob')).toBe('img:bob.png');
+    // lead hub has no avatar (engine draws it)
+    expect(out.nodes.find((n) => n.kind === 'lead')?.avatarUrl).toBeUndefined();
+  });
+
+  it('omits avatarUrl when no resolver is provided', () => {
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' })],
+      needs: [],
+      relationships: [],
+    });
+    expect(out.nodes.find((n) => n.id === 'worker:alice')?.avatarUrl).toBeUndefined();
+  });
+
+  it('ignores an unknown-worker assignee — task anchors to the agora, no ownership edge, no particle', () => {
+    // A need whose assignee points to a workerId that is not registered
+    // (e.g. worker unregistered mid-flight, or a stale assignee ref).
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' })],
+      needs: [need({ needId: 'orphan', status: 'in_progress', assignee: 'ghost' })],
+      relationships: [],
+    });
+    const task = out.nodes.find((n) => n.id === 'need:orphan');
+    expect(task).toMatchObject({ kind: 'task', state: 'active', ownerId: null });
+    // 无有效指派人 → 不产生指向不存在的 worker:ghost 的 ownership 边，改锚定到广场。
+    expect(out.edges.some((e) => e.type === 'ownership')).toBe(false);
+    expect(
+      out.edges.some(
+        (e) =>
+          e.source === `agora:${TEAM}` && e.target === 'need:orphan' && e.type === 'parent-child'
+      )
+    ).toBe(true);
+    // no particle can travel an ownership edge that does not exist
+    expect(out.particles.some((p) => p.id.includes('orphan'))).toBe(false);
+  });
+
+  it('only one particle per in-flight need and none for needs lacking an assignee', () => {
+    const out = projectSocietyGraph({
+      workers: [worker({ workerId: 'alice' }), worker({ workerId: 'bob' })],
+      needs: [
+        need({ needId: 'a', status: 'in_progress', assignee: 'alice' }),
+        need({ needId: 'b', status: 'assigned', assignee: 'bob' }),
+        need({ needId: 'c', status: 'open' }),
+      ],
+      relationships: [],
+    });
+    expect(out.particles).toHaveLength(2);
+    expect(out.particles.every((p) => p.kind === 'task_assign')).toBe(true);
+  });
+});

package/src/features/worker-society/renderer/societyGraphAdapter.ts

@@ -0,0 +1,240 @@
+/**
+ * SocietyGraphAdapter — projects worker-society domain → @claude-teams/agent-graph.
+ *
+ * The reusable graph engine (packages/agent-graph) already powers the team graph in
+ * cyan/space holographic style. This adapter feeds it the *decentralized agora*:
+ *   - a synthetic 「广场 / Agora」 hub (kind 'lead') sits at the radial center,
+ *   - each worker becomes a member node parented to the agora,
+ *   - each active need becomes a task orbiting its assignee (ownership edge),
+ *   - each relationship becomes a 'related' edge between two workers,
+ *   - each in-flight assignment spawns a particle along the ownership edge.
+ *
+ * Pure & deterministic: no Math.random, no FS/network/React — fully unit-testable.
+ * The cyan palette comes from the engine itself; we do not override colors, so the
+ * worker society renders with the same 1:1 holographic theme as the team graph.
+ * Worker avatars are injected by the host (SocietyGraph) via resolveAvatarUrl so the
+ * adapter itself stays renderer-agnostic (no asset imports here).
+ */
+import type {
+  GraphDataPort,
+  GraphEdge,
+  GraphLayoutPort,
+  GraphNode,
+  GraphNodeState,
+  GraphParticle,
+} from '@claude-teams/agent-graph';
+
+import type {
+  NeedStatus,
+  PublishedNeed,
+  Relationship,
+  WorkerProfile,
+} from '../core/domain/models/society';
+
+/** Stable society/team name used for node ids and domain refs. */
+export const SOCIETY_GRAPH_TEAM = 'worker-society';
+const AGORA_ID = `agora:${SOCIETY_GRAPH_TEAM}`;
+const AGORA_LABEL = '广场';
+
+/** Engine cyan (matches packages/agent-graph COLORS.active) for in-flight particles. */
+const PARTICLE_CYAN = '#66ccff';
+
+/** Needs still worth showing on the graph (closed/expired/cancelled drop out). */
+const VISIBLE_NEED_STATUSES: ReadonlySet<NeedStatus> = new Set([
+  'open',
+  'assigned',
+  'in_progress',
+  'delivered',
+]);
+
+/** Needs whose assignee is actively working — emit a flowing particle. */
+const IN_FLIGHT_NEED_STATUSES: ReadonlySet<NeedStatus> = new Set(['assigned', 'in_progress']);
+
+export interface SocietyGraphSnapshot {
+  workers: WorkerProfile[];
+  /** Active needs (open/assigned/in_progress/delivered). */
+  needs: PublishedNeed[];
+  relationships: Relationship[];
+}
+
+export interface SocietyGraphProjectOptions {
+  /** Optional avatar resolver — given a workerId, return a stable avatar URL. */
+  resolveAvatarUrl?: (workerId: string) => string | undefined;
+}
+
+/** Node id for a worker. */
+export function workerNodeId(workerId: string): string {
+  return `worker:${workerId}`;
+}
+
+/** Node id for a need. */
+export function needNodeId(needId: string): string {
+  return `need:${needId}`;
+}
+
+function workerState(worker: WorkerProfile): GraphNodeState {
+  if (worker.status === 'offline') return 'idle';
+  if (worker.activeTaskCount > 0) return 'active';
+  if (worker.status === 'busy') return 'active';
+  return 'idle';
+}
+
+function needState(status: NeedStatus): GraphNodeState {
+  switch (status) {
+    case 'in_progress':
+      return 'active';
+    case 'delivered':
+      return 'complete';
+    default:
+      return 'waiting';
+  }
+}
+
+function needTaskStatus(status: NeedStatus): 'pending' | 'in_progress' | 'completed' | 'deleted' {
+  switch (status) {
+    case 'in_progress':
+      return 'in_progress';
+    case 'delivered':
+      return 'completed';
+    default:
+      return 'pending';
+  }
+}
+
+/**
+ * Project a worker-society snapshot into a GraphDataPort snapshot for the engine.
+ * Returns an empty/dead port when the society has no workers and no needs.
+ */
+export function projectSocietyGraph(
+  snapshot: SocietyGraphSnapshot,
+  options: SocietyGraphProjectOptions = {}
+): GraphDataPort {
+  const { workers, needs, relationships } = snapshot;
+  const { resolveAvatarUrl } = options;
+
+  if (workers.length === 0 && needs.length === 0) {
+    return { nodes: [], edges: [], particles: [], teamName: SOCIETY_GRAPH_TEAM, isAlive: false };
+  }
+
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+  const particles: GraphParticle[] = [];
+
+  const knownWorkerIds = new Set(workers.map((w) => w.workerId));
+
+  // ── Agora hub (radial center) ──────────────────────────────────────────────
+  nodes.push({
+    id: AGORA_ID,
+    kind: 'lead',
+    label: AGORA_LABEL,
+    state: 'active',
+    domainRef: { kind: 'lead', teamName: SOCIETY_GRAPH_TEAM, memberName: 'agora' },
+  });
+
+  // ── Workers → member nodes, parented to the agora ──────────────────────────
+  for (const w of workers) {
+    const memberId = workerNodeId(w.workerId);
+    nodes.push({
+      id: memberId,
+      kind: 'member',
+      label: w.name,
+      state: workerState(w),
+      role: w.kind,
+      runtimeLabel: w.harness,
+      avatarUrl: resolveAvatarUrl?.(w.workerId),
+      domainRef: { kind: 'member', teamName: SOCIETY_GRAPH_TEAM, memberName: w.workerId },
+    });
+    edges.push({
+      id: `edge:parent:${AGORA_ID}:${memberId}`,
+      source: AGORA_ID,
+      target: memberId,
+      type: 'parent-child',
+    });
+  }
+
+  // ── Needs → task nodes orbiting their assignee ─────────────────────────────
+  for (const need of needs) {
+    if (!VISIBLE_NEED_STATUSES.has(need.status)) continue;
+    const assigneeId =
+      need.assignee && knownWorkerIds.has(need.assignee) ? workerNodeId(need.assignee) : null;
+    const taskId = needNodeId(need.needId);
+
+    nodes.push({
+      id: taskId,
+      kind: 'task',
+      label: need.subject,
+      sublabel:
+        need.requiredCapabilities.length > 0 ? need.requiredCapabilities.join(' · ') : undefined,
+      state: needState(need.status),
+      taskStatus: needTaskStatus(need.status),
+      ownerId: assigneeId,
+      domainRef: { kind: 'task', teamName: SOCIETY_GRAPH_TEAM, taskId: need.needId },
+    });
+
+    if (assigneeId) {
+      // 已指派 → ownership 边接到具体 worker；进行中再叠一条流动粒子。
+      const ownEdgeId = `edge:own:${assigneeId}:${taskId}`;
+      edges.push({
+        id: ownEdgeId,
+        source: assigneeId,
+        target: taskId,
+        type: 'ownership',
+      });
+
+      // In-flight assignment → a particle flowing along the ownership edge.
+      if (IN_FLIGHT_NEED_STATUSES.has(need.status)) {
+        particles.push({
+          id: `particle:need:${need.needId}`,
+          edgeId: ownEdgeId,
+          progress: 0,
+          kind: 'task_assign',
+          color: PARTICLE_CYAN,
+        });
+      }
+    } else {
+      // 无指派人 → 锚定到广场（agora）。否则 open 需求在力导布局里没有边可依附，成为孤立
+      // 浮点，视觉上「看不出跟谁关联」。用 parent-child 表达「待认领，挂在广场」——ownership
+      // 语义无主不成立，故不用 ownership；粒子也只属于进行中的已指派任务。
+      edges.push({
+        id: `edge:agora:${taskId}`,
+        source: AGORA_ID,
+        target: taskId,
+        type: 'parent-child',
+      });
+    }
+  }
+
+  // ── Relationships → 'related' edges (bidirectional-deduped) ────────────────
+  const seenRelated = new Set<string>();
+  for (const r of relationships) {
+    if (r.fromWorker === r.toWorker) continue;
+    if (!knownWorkerIds.has(r.fromWorker) || !knownWorkerIds.has(r.toWorker)) continue;
+    const [a, b] =
+      r.fromWorker <= r.toWorker ? [r.fromWorker, r.toWorker] : [r.toWorker, r.fromWorker];
+    const key = `${a}:${b}`;
+    if (seenRelated.has(key)) continue;
+    seenRelated.add(key);
+    edges.push({
+      id: `edge:rel:${a}:${b}`,
+      source: workerNodeId(a),
+      target: workerNodeId(b),
+      type: 'related',
+    });
+  }
+
+  const layout: GraphLayoutPort = {
+    version: 'stable-slots-v1',
+    mode: 'radial',
+    ownerOrder: workers.map((w) => workerNodeId(w.workerId)),
+    slotAssignments: {},
+  };
+
+  return {
+    nodes,
+    edges,
+    particles,
+    teamName: SOCIETY_GRAPH_TEAM,
+    isAlive: workers.length > 0,
+    layout,
+  };
+}

package/src/features/worker-society/renderer/societyOverlayActions.test.ts

@@ -0,0 +1,57 @@
+/**
+ * societyOverlayActions 测试 —— 纯图谱交互模型的核心规则（TDD 先行）。
+ *
+ * 删掉看板后，节点点开弹出的小卡片是唯一的交互入口。该模块决定：
+ *   1. 一个 need 处于某状态时，卡片上该出现哪些生命周期动作按钮；
+ *   2. 弹卡定位如何不被屏幕边缘裁切。
+ * 这两条规则是「纯图谱」UX 的全部决策点，必须测全。
+ */
+import { describe, expect, it } from 'vitest';
+
+import { needLifecycleActions, type NeedOverlayAction } from './societyOverlayActions';
+
+describe('needLifecycleActions', () => {
+  it('open need with volunteers → 选派最优 + 触发自治', () => {
+    expect(needLifecycleActions('open', true)).toEqual<NeedOverlayAction[]>([
+      'selectAssignee',
+      'triggerAutonomy',
+    ]);
+  });
+
+  it('open need with no volunteers → 仅触发自治（让 worker 自荐，无手选）', () => {
+    expect(needLifecycleActions('open', false)).toEqual<NeedOverlayAction[]>(['triggerAutonomy']);
+  });
+
+  it('assigned → 开始执行', () => {
+    expect(needLifecycleActions('assigned', false)).toEqual<NeedOverlayAction[]>(['startNeed']);
+  });
+
+  it('in_progress → 标记交付', () => {
+    expect(needLifecycleActions('in_progress', false)).toEqual<NeedOverlayAction[]>([
+      'deliverNeed',
+    ]);
+  });
+
+  it('delivered → 通过审核', () => {
+    expect(needLifecycleActions('delivered', false)).toEqual<NeedOverlayAction[]>([
+      'acceptDelivery',
+    ]);
+  });
+
+  it('closed/expired/cancelled → 无动作（不会出现在图谱上，但要安全兜底）', () => {
+    expect(needLifecycleActions('closed', false)).toEqual<NeedOverlayAction[]>([]);
+    expect(needLifecycleActions('expired', false)).toEqual<NeedOverlayAction[]>([]);
+    expect(needLifecycleActions('cancelled', false)).toEqual<NeedOverlayAction[]>([]);
+  });
+
+  it('volunteers flag only matters for open needs', () => {
+    // assigned/in_progress/delivered 不因是否有自荐者而改变动作。
+    expect(needLifecycleActions('assigned', true)).toEqual(needLifecycleActions('assigned', false));
+    expect(needLifecycleActions('in_progress', true)).toEqual(
+      needLifecycleActions('in_progress', false)
+    );
+    expect(needLifecycleActions('delivered', true)).toEqual(
+      needLifecycleActions('delivered', false)
+    );
+  });
+});

package/src/features/worker-society/renderer/societyOverlayActions.ts

@@ -0,0 +1,49 @@
+/**
+ * societyOverlayActions —— 纯图谱交互模型的决策核心（纯函数）。
+ *
+ * 删掉看板后，点开 worker/need 节点弹出的卡片是唯一的交互入口。本模块封装与渲染无关、
+ * 可单测的决策：needLifecycleActions —— 某 need 处于某状态时，卡片上出现哪些动作按钮。
+ * 自荐改由「触发自治」自动完成（反派单），所以 open 状态不再有「自荐」手选，只有
+ * 「选派最优（若有自荐者）」与「触发自治」。
+ *
+ * 弹卡定位由引擎 GraphView 的 Floating UI（computePosition + flip + shift + offset）负责，
+ * 不在本模块——故无 clamp 函数（曾有的 clampOverlayPosition 与引擎叠加致 double-offset）。
+ */
+import type { NeedStatus } from '../core/domain/models/society';
+
+/** 节点弹卡上可出现的 need 生命周期动作（与 store 的命令一一对应）。 */
+export type NeedOverlayAction =
+  | 'selectAssignee' // open + 有自荐者 → 选派最优
+  | 'triggerAutonomy' // open → 让 worker 自荐/选派（反派单）
+  | 'startNeed' // assigned → 开始执行
+  | 'deliverNeed' // in_progress → 标记交付
+  | 'acceptDelivery'; // delivered → 通过审核
+
+/**
+ * 按 need 状态返回卡片应展示的生命周期动作（顺序即按钮顺序）。
+ *
+ * - open：有自荐者→「选派最优」+「触发自治」；无自荐者→仅「触发自治」。
+ * - assigned/in_progress/delivered：各一个推进动作，与是否有自荐者无关。
+ * - closed/expired/cancelled：图谱不渲染这些节点，但返回空数组做安全兜底。
+ */
+export function needLifecycleActions(
+  status: NeedStatus,
+  hasVolunteers: boolean
+): NeedOverlayAction[] {
+  switch (status) {
+    case 'open':
+      return hasVolunteers ? ['selectAssignee', 'triggerAutonomy'] : ['triggerAutonomy'];
+    case 'assigned':
+      return ['startNeed'];
+    case 'in_progress':
+      return ['deliverNeed'];
+    case 'delivered':
+      return ['acceptDelivery'];
+    case 'closed':
+    case 'expired':
+    case 'cancelled':
+      return [];
+    default:
+      return [];
+  }
+}