@yancyyu/openhermit 1.6.41 → 1.6.43

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

@@ -0,0 +1,218 @@
+/**
+ * societyStore 测试 —— Zustand 数据层（TDD 先行）。
+ *
+ * 注入一个 mock API（不触网络），断言：loadAll 聚合四类数据并管理 loading/error；
+ * 每个 mutation（注册/发布/自荐/选派/交付/社交）调用对应 API 后**只刷新受影响切片**。
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import { createSocietyStore } from './societyStore';
+import type { SocietyApiClient } from './societyApi';
+
+function mockApi(overrides: Partial<SocietyApiClient> = {}): SocietyApiClient {
+  return {
+    listWorkers: vi.fn().mockResolvedValue([]),
+    registerWorker: vi.fn().mockResolvedValue({}),
+    getWorker: vi.fn().mockResolvedValue(null),
+    listOpenNeeds: vi.fn().mockResolvedValue([]),
+    listActiveNeeds: vi.fn().mockResolvedValue([]),
+    listAllNeeds: vi.fn().mockResolvedValue([]),
+    publishNeed: vi.fn().mockResolvedValue({}),
+    volunteer: vi.fn().mockResolvedValue({}),
+    selectAssignee: vi.fn().mockResolvedValue({}),
+    startNeed: vi.fn().mockResolvedValue({}),
+    deliverNeed: vi.fn().mockResolvedValue({}),
+    acceptDelivery: vi.fn().mockResolvedValue({}),
+    cancelNeed: vi.fn().mockResolvedValue({}),
+    listRelationships: vi.fn().mockResolvedValue([]),
+    sendMessage: vi.fn().mockResolvedValue({}),
+    getFeed: vi.fn().mockResolvedValue([]),
+    runAutonomyTick: vi.fn().mockResolvedValue({ ok: true, applied: 0 }),
+    autoSelectPending: vi.fn().mockResolvedValue({ ok: true, selected: 0 }),
+    ...overrides,
+  };
+}
+
+describe('createSocietyStore', () => {
+  it('loadAll aggregates workers, open needs, relationships, and feed', async () => {
+    const api = mockApi({
+      listWorkers: vi.fn().mockResolvedValue([{ workerId: 'a' }]),
+      listOpenNeeds: vi.fn().mockResolvedValue([{ needId: 'n1' }]),
+      listActiveNeeds: vi.fn().mockResolvedValue([{ needId: 'a1', status: 'assigned' }]),
+      listRelationships: vi.fn().mockResolvedValue([{ fromWorker: 'a' }]),
+      getFeed: vi.fn().mockResolvedValue([{ id: 'm1' }]),
+    });
+    const store = createSocietyStore(api);
+    await store.getState().loadAll();
+    const s = store.getState();
+    expect(s.workers).toEqual([{ workerId: 'a' }]);
+    expect(s.openNeeds).toEqual([{ needId: 'n1' }]);
+    expect(s.activeNeeds).toEqual([{ needId: 'a1', status: 'assigned' }]);
+    expect(s.relationships).toEqual([{ fromWorker: 'a' }]);
+    expect(s.feed).toEqual([{ id: 'm1' }]);
+    expect(s.loading).toBe(false);
+    expect(s.error).toBeNull();
+  });
+
+  it('refresh reloads all data (loadAllInto alias)', async () => {
+    // refresh 是 loadAll 的公开别名（两者都调 loadAllInto），此前无测试调用 → funcs 覆盖缺口。
+    const api = mockApi({
+      listWorkers: vi.fn().mockResolvedValue([{ workerId: 'a' }]),
+    });
+    const store = createSocietyStore(api);
+    await store.getState().refresh();
+    expect(store.getState().workers).toEqual([{ workerId: 'a' }]);
+    expect(store.getState().loading).toBe(false);
+  });
+
+  it('sets error and clears loading when loadAll fails', async () => {
+    const api = mockApi({ listWorkers: vi.fn().mockRejectedValue(new Error('down')) });
+    const store = createSocietyStore(api);
+    await store.getState().loadAll();
+    const s = store.getState();
+    expect(s.error).toBe('down');
+    expect(s.loading).toBe(false);
+  });
+
+  it('registerWorker calls the API then reloads only workers (not needs/feed)', async () => {
+    const api = mockApi({ listWorkers: vi.fn().mockResolvedValue([{ workerId: 'dev' }]) });
+    const store = createSocietyStore(api);
+    await store.getState().registerWorker({ workerId: 'dev', name: 'Dev', capabilities: 'code' });
+    expect(api.registerWorker).toHaveBeenCalledWith({
+      workerId: 'dev',
+      name: 'Dev',
+      capabilities: 'code',
+    });
+    expect(api.listWorkers).toHaveBeenCalledTimes(1); // targeted reload
+    expect(api.listOpenNeeds).not.toHaveBeenCalled(); // unaffected slice untouched
+    expect(api.getFeed).not.toHaveBeenCalled();
+    expect(store.getState().workers).toEqual([{ workerId: 'dev' }]);
+  });
+
+  it('publishNeed calls the API then reloads only open needs', async () => {
+    const api = mockApi({ listOpenNeeds: vi.fn().mockResolvedValue([{ needId: 'n1' }]) });
+    const store = createSocietyStore(api);
+    await store
+      .getState()
+      .publishNeed({ postedBy: 'u', subject: 'X', requiredCapabilities: 'code' });
+    expect(api.publishNeed).toHaveBeenCalledWith({
+      postedBy: 'u',
+      subject: 'X',
+      requiredCapabilities: 'code',
+    });
+    expect(api.listOpenNeeds).toHaveBeenCalledTimes(1);
+    expect(api.listWorkers).not.toHaveBeenCalled();
+    expect(store.getState().openNeeds).toEqual([{ needId: 'n1' }]);
+  });
+
+  it('volunteer -> select -> deliver -> accept each reload open needs', async () => {
+    const api = mockApi();
+    const store = createSocietyStore(api);
+    const st = store.getState();
+    await st.volunteer('n1', 'dev');
+    await st.selectAssignee('n1');
+    await st.deliverNeed('n1', 'v1');
+    await st.acceptDelivery('n1');
+    expect(api.volunteer).toHaveBeenCalledWith('n1', 'dev');
+    expect(api.selectAssignee).toHaveBeenCalledWith('n1');
+    expect(api.deliverNeed).toHaveBeenCalledWith('n1', 'v1');
+    expect(api.acceptDelivery).toHaveBeenCalledWith('n1');
+    expect(api.listOpenNeeds).toHaveBeenCalledTimes(4);
+  });
+
+  it('sendMessage reloads only the feed (not workers/needs)', async () => {
+    const api = mockApi({ getFeed: vi.fn().mockResolvedValue([{ id: 'm1' }]) });
+    const store = createSocietyStore(api);
+    await store.getState().sendMessage('a', 'b', 'hi');
+    expect(api.sendMessage).toHaveBeenCalledWith('a', 'b', 'hi');
+    expect(api.getFeed).toHaveBeenCalledTimes(1);
+    expect(api.listWorkers).not.toHaveBeenCalled();
+    expect(api.listOpenNeeds).not.toHaveBeenCalled();
+    expect(store.getState().feed).toEqual([{ id: 'm1' }]);
+  });
+
+  it('runAutonomyTick calls the API then reloads open needs and feed (autonomy changes both)', async () => {
+    const api = mockApi({
+      runAutonomyTick: vi.fn().mockResolvedValue({ ok: true, applied: 3 }),
+      listOpenNeeds: vi.fn().mockResolvedValue([{ needId: 'n1' }]),
+      getFeed: vi.fn().mockResolvedValue([{ id: 'm1' }]),
+    });
+    const store = createSocietyStore(api);
+    await store.getState().runAutonomyTick();
+    expect(api.runAutonomyTick).toHaveBeenCalledTimes(1);
+    expect(api.listOpenNeeds).toHaveBeenCalledTimes(1); // 自荐改变需求的自荐者
+    expect(api.getFeed).toHaveBeenCalledTimes(1); // 自荐产生社交消息
+    expect(api.listWorkers).not.toHaveBeenCalled(); // 花名册不受影响
+  });
+
+  it('autoSelectPending calls the API then reloads open needs and feed', async () => {
+    const api = mockApi({
+      autoSelectPending: vi.fn().mockResolvedValue({ ok: true, selected: 2 }),
+      listOpenNeeds: vi.fn().mockResolvedValue([{ needId: 'n1' }]),
+      getFeed: vi.fn().mockResolvedValue([{ id: 'm1' }]),
+    });
+    const store = createSocietyStore(api);
+    await store.getState().autoSelectPending();
+    expect(api.autoSelectPending).toHaveBeenCalledTimes(1);
+    expect(api.listOpenNeeds).toHaveBeenCalledTimes(1); // 选派改变需求状态
+    expect(api.getFeed).toHaveBeenCalledTimes(1); // 选派产生通知消息
+  });
+
+  it('startNeed and cancelNeed each reload BOTH open and active needs (graph stays in sync)', async () => {
+    // reloadNeeds（旧名 reloadOpenNeeds）同时刷新 open + active：画布据 activeNeeds 渲染
+    // worker→task 锚点。锁住「需求生命周期 mutation 后两切片都刷新」——否则 cancel 一个
+    // assigned 需求（assigned→cancelled 合法，见 iter-9）会让画布 activeNeeds 留陈旧节点，
+    // 或诱导后人把 reload「优化」成只刷 open（函数名曾误导，本轮已正名）。
+    const api = mockApi({
+      listOpenNeeds: vi.fn().mockResolvedValue([{ needId: 'n1' }]),
+      listActiveNeeds: vi.fn().mockResolvedValue([{ needId: 'a1', status: 'in_progress' }]),
+    });
+    const store = createSocietyStore(api);
+
+    await store.getState().startNeed('n1', 'dev');
+    expect(api.startNeed).toHaveBeenCalledWith('n1', 'dev');
+    expect(api.listOpenNeeds).toHaveBeenCalledTimes(1);
+    expect(api.listActiveNeeds).toHaveBeenCalledTimes(1); // ← 关键：active 也刷新
+
+    await store.getState().cancelNeed('n1');
+    expect(api.cancelNeed).toHaveBeenCalledWith('n1');
+    expect(api.listOpenNeeds).toHaveBeenCalledTimes(2);
+    expect(api.listActiveNeeds).toHaveBeenCalledTimes(2); // ← cancel 同样双切片刷新
+  });
+
+  it('sets error (and preserves prior data, leaves loading untouched) when a mutation fails', async () => {
+    // iter-3 标记的缺口：此前只测了 loadAll 失败；mutation 失败的 error 契约未覆盖。
+    // mutate 捕获异常 → 写 error；不触碰数据切片（既有数据保留）；mutations 不动 loading。
+    const api = mockApi({
+      listWorkers: vi.fn().mockResolvedValue([{ workerId: 'a' }]),
+      registerWorker: vi.fn().mockRejectedValue(new Error('already exists')),
+    });
+    const store = createSocietyStore(api);
+    await store.getState().loadAll(); // 先装好数据
+    expect(store.getState().workers).toEqual([{ workerId: 'a' }]);
+
+    await store.getState().registerWorker({ workerId: 'a', name: 'A', capabilities: '' });
+
+    const s = store.getState();
+    expect(s.error).toBe('already exists'); // 失败 → 写 error（mutate 的 catch 分支）
+    expect(s.loading).toBe(false); // mutation 不动 loading（loadAll 已结束为 false）
+    expect(s.workers).toEqual([{ workerId: 'a' }]); // 既有数据未被清空
+  });
+
+  it('stringifies a non-Error thrown value into the error state (loadAll and mutations)', async () => {
+    // store 的 catch 兜底 `e instanceof Error ? e.message : String(e)`：非 Error 抛值（裸字符串/
+    // 数字等）须 String() 化——error 状态恒为 string 是 UI 渲染前提（否则 React 渲染 number/对象报错）。
+    // 现有 loadAll/mutation 失败用例都用 new Error（真臂 e.message）；本测补两处 false 臂 String(e)。
+    const api = mockApi({
+      listWorkers: vi.fn().mockRejectedValue('network down'), // 非 Error（裸字符串）
+      registerWorker: vi.fn().mockRejectedValue(42), // 非 Error（数字）
+    });
+    const store = createSocietyStore(api);
+
+    await store.getState().loadAll();
+    expect(store.getState().error).toBe('network down'); // String('network down') → L63 兜底
+
+    await store.getState().registerWorker({ workerId: 'x', name: 'X' });
+    expect(store.getState().error).toBe('42'); // String(42) → L96 兜底
+  });
+});

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

@@ -0,0 +1,146 @@
+/**
+ * Worker Society — 前端状态层（Zustand）。
+ *
+ * 把 SocietyApiClient 聚合成一个可被 React 组件订阅的 store：workers / 公告板需求 /
+ * 关系图 / 活动流，外加 loading/error。每个 mutation（注册/发布/自荐/选派/交付/社交）
+ * 调用 API 后**只刷新受影响切片**，避免全量重拉。
+ *
+ * api 可注入（测试用 mock；生产用 createSocietyApi()）。store 是 factory 形式，便于
+ * 在测试里每次拿到干净实例。
+ */
+import { create } from 'zustand';
+
+import {
+  createSocietyApi,
+  type PublishNeedInput,
+  type RegisterWorkerInput,
+  type SocietyApiClient,
+} from './societyApi';
+import type { PublishedNeed, Relationship, WorkerProfile } from '../core/domain/models/society';
+import type { SocialMessageRecord } from '../main/infrastructure/crossTeamMessageGateway';
+
+export interface SocietyStoreState {
+  workers: WorkerProfile[];
+  openNeeds: PublishedNeed[];
+  /** 仍在生命周期内的需求（open/assigned/in_progress/delivered）—— 画布据此渲染 worker 跑向任务。 */
+  activeNeeds: PublishedNeed[];
+  relationships: Relationship[];
+  feed: SocialMessageRecord[];
+  loading: boolean;
+  error: string | null;
+
+  loadAll(): Promise<void>;
+  refresh(): Promise<void>;
+  registerWorker(input: RegisterWorkerInput): Promise<WorkerProfile | undefined>;
+  publishNeed(input: PublishNeedInput): Promise<PublishedNeed | undefined>;
+  volunteer(needId: string, workerId: string): Promise<unknown>;
+  selectAssignee(needId: string): Promise<unknown>;
+  startNeed(needId: string, workerId: string): Promise<unknown>;
+  deliverNeed(needId: string, result: string): Promise<unknown>;
+  acceptDelivery(needId: string): Promise<unknown>;
+  cancelNeed(needId: string): Promise<unknown>;
+  sendMessage(fromWorker: string, toWorker: string, text: string): Promise<unknown>;
+  runAutonomyTick(): Promise<{ ok: boolean; applied: number } | undefined>;
+  autoSelectPending(): Promise<{ ok: boolean; selected: number } | undefined>;
+}
+
+/** 拉取四类数据并写入 store；统一管理 loading/error。 */
+async function loadAllInto(
+  set: (partial: Partial<SocietyStoreState>) => void,
+  api: SocietyApiClient
+): Promise<void> {
+  set({ loading: true, error: null });
+  try {
+    const [workers, openNeeds, activeNeeds, relationships, feed] = await Promise.all([
+      api.listWorkers(),
+      api.listOpenNeeds(),
+      api.listActiveNeeds(),
+      api.listRelationships(),
+      api.getFeed(),
+    ]);
+    set({ workers, openNeeds, activeNeeds, relationships, feed, loading: false });
+  } catch (e) {
+    set({ loading: false, error: e instanceof Error ? e.message : String(e) });
+  }
+}
+
+/**
+ * 创建一个 society store（默认指向同源 /api/society/*）。
+ * @param api 注入的 API 客户端；省略则用 createSocietyApi()。
+ */
+export function createSocietyStore(api: SocietyApiClient = createSocietyApi()) {
+  const useSocietyStore = create<SocietyStoreState>((set) => {
+    // 局部刷新：只重拉受影响的切片，避免全量 loadAll。
+    const reloadWorkers = async (): Promise<void> => set({ workers: await api.listWorkers() });
+    // 需求切片刷新：open（看板的待办）与 active（画布的生命周期）同源，一起刷新，
+    // 这样任意状态流转（自荐/选派/执行/交付）后两处视图都同步。
+    const reloadNeeds = async (): Promise<void> => {
+      const [openNeeds, activeNeeds] = await Promise.all([
+        api.listOpenNeeds(),
+        api.listActiveNeeds(),
+      ]);
+      set({ openNeeds, activeNeeds });
+    };
+    const reloadFeed = async (): Promise<void> => set({ feed: await api.getFeed() });
+
+    // 统一 mutation：调命令 → 捕获错误 → 仅刷受影响切片 → 回传命令结果（供调用方给反馈）。
+    const mutate = async <T>(
+      run: () => Promise<T>,
+      after: () => Promise<void>
+    ): Promise<T | undefined> => {
+      set({ error: null });
+      try {
+        const result = await run();
+        await after();
+        return result;
+      } catch (e) {
+        set({ error: e instanceof Error ? e.message : String(e) });
+        return undefined;
+      }
+    };
+
+    return {
+      workers: [],
+      openNeeds: [],
+      activeNeeds: [],
+      relationships: [],
+      feed: [],
+      loading: false,
+      error: null,
+
+      loadAll: () => loadAllInto(set, api),
+      refresh: () => loadAllInto(set, api),
+
+      registerWorker: (input) => mutate(() => api.registerWorker(input), reloadWorkers),
+      publishNeed: (input) => mutate(() => api.publishNeed(input), reloadNeeds),
+      volunteer: (needId, workerId) => mutate(() => api.volunteer(needId, workerId), reloadNeeds),
+      selectAssignee: (needId) => mutate(() => api.selectAssignee(needId), reloadNeeds),
+      startNeed: (needId, workerId) => mutate(() => api.startNeed(needId, workerId), reloadNeeds),
+      deliverNeed: (needId, result) => mutate(() => api.deliverNeed(needId, result), reloadNeeds),
+      acceptDelivery: (needId) => mutate(() => api.acceptDelivery(needId), reloadNeeds),
+      cancelNeed: (needId) => mutate(() => api.cancelNeed(needId), reloadNeeds),
+      sendMessage: (fromWorker, toWorker, text) =>
+        mutate(() => api.sendMessage(fromWorker, toWorker, text), reloadFeed),
+      runAutonomyTick: () =>
+        mutate(
+          () => api.runAutonomyTick(),
+          // 自治自荐同时改变「需求的自荐者」与「社交活动流」。
+          async () => {
+            await reloadNeeds();
+            await reloadFeed();
+          }
+        ),
+      autoSelectPending: () =>
+        mutate(
+          () => api.autoSelectPending(),
+          // 选派改变需求状态并产生通知消息。
+          async () => {
+            await reloadNeeds();
+            await reloadFeed();
+          }
+        ),
+    };
+  });
+
+  return useSocietyStore;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * societyViewUtils 测试 —— 前端纯可视化逻辑。
+ *
+ * 图谱引擎不暴露节点尺寸/边宽/透明度字段，故历史上的 workerNodeRadius/edgeWidth/
+ * trustOpacity 与看板用的 topWorkersByReputation/activeWorkers/sortNeedsByLifecycle
+ * 在「纯图谱」改造后无消费者，已随实现一并删除（见 docs §15 迭代 #6）。本文件只覆盖
+ * 当前仍被消费的纯映射：状态标签、声誉档色、状态区分色、头像稳定分配。
+ * 纯函数，无 React/DOM 依赖，易测。
+ */
+import { describe, expect, it } from 'vitest';
+
+import type { PublishedNeed } from '../core/domain/models/society';
+import {
+  NEED_STATUS_LABEL,
+  needStatusColor,
+  pickAvatarUrl,
+  reputationColor,
+} from './societyViewUtils';
+
+describe('NEED_STATUS_LABEL', () => {
+  it('provides a non-empty Chinese label for every need status', () => {
+    const statuses: PublishedNeed['status'][] = [
+      'open',
+      'assigned',
+      'in_progress',
+      'delivered',
+      'closed',
+      'expired',
+      'cancelled',
+    ];
+    for (const s of statuses) {
+      expect(typeof NEED_STATUS_LABEL[s]).toBe('string');
+      expect(NEED_STATUS_LABEL[s].length).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('reputationColor', () => {
+  it('is green for high, amber for mid, red for low', () => {
+    expect(reputationColor(80)).toBe('#16a34a');
+    expect(reputationColor(50)).toBe('#d97706');
+    expect(reputationColor(20)).toBe('#dc2626');
+  });
+});
+
+describe('needStatusColor', () => {
+  it('assigns a distinct color per status', () => {
+    const statuses: PublishedNeed['status'][] = [
+      'open',
+      'assigned',
+      'in_progress',
+      'delivered',
+      'closed',
+      'expired',
+      'cancelled',
+    ];
+    const colors = statuses.map(needStatusColor);
+    expect(new Set(colors).size).toBe(statuses.length); // all distinct
+  });
+});
+
+describe('pickAvatarUrl (stable sprite assignment)', () => {
+  const urls = ['a.png', 'b.png', 'c.png', 'd.png', 'e.png'];
+  it('is deterministic — same id always maps to the same url', () => {
+    expect(pickAvatarUrl('frontend', urls)).toBe(pickAvatarUrl('frontend', urls));
+  });
+  it('always returns an in-range url for any id', () => {
+    for (const id of ['a', 'b', 'c', 'x', 'y', 'z', 'long-id-123']) {
+      expect(urls).toContain(pickAvatarUrl(id, urls));
+    }
+  });
+  it('returns undefined for an empty url set', () => {
+    expect(pickAvatarUrl('anyone', [])).toBeUndefined();
+  });
+  it('distributes distinct ids across the set (not all collapsed to one)', () => {
+    const picks = new Set(
+      ['w1', 'w2', 'w3', 'w4', 'w5', 'w6', 'w7', 'w8'].map((id) => pickAvatarUrl(id, urls))
+    );
+    expect(picks.size).toBeGreaterThan(1);
+  });
+});

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

@@ -0,0 +1,68 @@
+/**
+ * Worker Society — 前端纯可视化逻辑。
+ *
+ * 图谱（@claude-teams/agent-graph）自身负责节点尺寸/边样式/粒子：其 GraphNode/GraphEdge
+ * 契约不暴露 size/radius/width/opacity 字段，故「声誉=节点大小、协作=边宽、信任=边透明度」
+ * 无法经图谱编码——这些信息改由 SocietyNodeOverlay 弹卡呈现（声誉色/状态徽章）。
+ * 旧的 workerNodeRadius/edgeWidth/trustOpacity 及看板用的排行榜/排序映射在「纯图谱」改造后
+ * 已无消费者（见 docs §15 迭代 #6），一并删除，杜绝死代码。
+ *
+ * 本文件只保留当前真正被消费的纯映射：
+ *   - NEED_STATUS_LABEL：需求状态中文标签（弹卡/徽章单一来源）；
+ *   - reputationColor / needStatusColor：声誉档 / 需求状态 → 区分色（弹卡用）；
+ *   - pickAvatarUrl：把 workerId 稳定映射到内置头像列表（图谱用）。
+ * 纯函数，无 React/DOM/network 副作用，便于单测与复用。
+ */
+import type { NeedStatus, PublishedNeed } from '../core/domain/models/society';
+
+/** 需求生命周期状态的中文标签（弹卡/状态徽章共用，单一来源）。 */
+export const NEED_STATUS_LABEL: Record<NeedStatus, string> = {
+  open: '招募中',
+  assigned: '已选派',
+  in_progress: '执行中',
+  delivered: '待审核',
+  closed: '已完结',
+  expired: '已过期',
+  cancelled: '已取消',
+};
+
+/** 声誉档位颜色：高=绿、中=琥珀、低=红。 */
+export function reputationColor(reputation: number): string {
+  if (reputation >= 70) return '#16a34a';
+  if (reputation >= 40) return '#d97706';
+  return '#dc2626';
+}
+
+/** 需求生命周期状态 → 区分色。 */
+export function needStatusColor(status: PublishedNeed['status']): string {
+  switch (status) {
+    case 'open':
+      return '#2563eb';
+    case 'assigned':
+      return '#7c3aed';
+    case 'in_progress':
+      return '#d97706';
+    case 'delivered':
+      return '#0891b2';
+    case 'closed':
+      return '#16a34a';
+    case 'expired':
+      return '#9ca3af';
+    case 'cancelled':
+      return '#dc2626';
+    default:
+      return '#9ca3af';
+  }
+}
+
+/**
+ * 把一个 id 稳定映射到 url 列表中的某一项（确定性哈希：同 id 永远同一项）。
+ * 空列表返回 undefined。供 SocietyGraph 给每个 worker 稳定分配头像（复用 hermit
+ * 自带的 participant-avatars 目录）。
+ */
+export function pickAvatarUrl(seed: string, urls: readonly string[]): string | undefined {
+  if (urls.length === 0) return undefined;
+  let h = 0;
+  for (let i = 0; i < seed.length; i++) h = (h * 31 + seed.charCodeAt(i)) >>> 0;
+  return urls[h % urls.length];
+}

package/src/main/ipc/extensions.ts

@@ -7,6 +7,9 @@
 
 import type { CcAgentType } from '@shared/types/ccConnect';
 import type {
+  CapabilityCommandPromptRequest,
+  CapabilityPackExportRequest,
+  CapabilityPackImportRequest,
   McpCustomInstallRequest,
   McpLibraryImportRequest,
   McpLibraryUpsertRequest,
@@ -18,6 +21,7 @@ import type {
   SkillWatcherEvent,
 } from '@shared/types/extensions';
 
+import { CapabilityPackLoaderService } from '@main/services/extensions/capability-packs/CapabilityPackLoaderService';
 import { PluginCatalogService } from '@main/services/extensions/catalog/PluginCatalogService';
 import { ExtensionFacadeService } from '@main/services/extensions/ExtensionFacadeService';
 import { McpLibraryService } from '@main/services/extensions/library/McpLibraryService';
@@ -52,6 +56,7 @@ function wrapHandler<T>(handler: () => Promise<T>): Promise<IpcResult<T>> {
 
 let facade: ExtensionFacadeService | null = null;
 let mcpLibrary: McpLibraryService | null = null;
+let capabilityPacks: CapabilityPackLoaderService | null = null;
 let skillsCatalog: SkillsCatalogService | null = null;
 let skillsMutation: SkillsMutationService | null = null;
 let skillsWatcher: SkillsWatcherService | null = null;
@@ -71,6 +76,11 @@ function getMcpLibrary(): McpLibraryService {
   return mcpLibrary;
 }
 
+function getCapabilityPacks(): CapabilityPackLoaderService {
+  if (!capabilityPacks) capabilityPacks = new CapabilityPackLoaderService();
+  return capabilityPacks;
+}
+
 function getSkillsCatalog(): SkillsCatalogService {
   if (!skillsCatalog) skillsCatalog = new SkillsCatalogService();
   return skillsCatalog;
@@ -114,6 +124,10 @@ const channels = {
   MCP_INSTALL: 'extensions:mcp:install',
   MCP_INSTALL_CUSTOM: 'extensions:mcp:installCustom',
   MCP_UNINSTALL: 'extensions:mcp:uninstall',
+  CAPABILITY_PACKS_LIST: 'extensions:capabilityPacks:list',
+  CAPABILITY_PACKS_IMPORT: 'extensions:capabilityPacks:import',
+  CAPABILITY_PACKS_EXPORT: 'extensions:capabilityPacks:export',
+  CAPABILITY_PACKS_COMMAND_PROMPT: 'extensions:capabilityPacks:commandPrompt',
   SKILLS_LIST: 'extensions:skills:list',
   SKILLS_GET_DETAIL: 'extensions:skills:getDetail',
   SKILLS_UPSERT: 'extensions:skills:upsert',
@@ -249,6 +263,19 @@ export const extensionHandlers = {
   mcpLibraryImport: (request: McpLibraryImportRequest) =>
     wrapHandler(() => getMcpLibrary().importFromLive(request)),
 
+  // ── Capability Packs ──
+
+  capabilityPacksList: () => wrapHandler(() => getCapabilityPacks().list()),
+
+  capabilityPacksImport: (request: CapabilityPackImportRequest) =>
+    wrapHandler(() => getCapabilityPacks().importPack(request)),
+
+  capabilityPacksExport: (request: CapabilityPackExportRequest) =>
+    wrapHandler(() => getCapabilityPacks().exportPack(request)),
+
+  capabilityPacksCommandPrompt: (request: CapabilityCommandPromptRequest) =>
+    wrapHandler(() => getCapabilityPacks().getCommandPrompt(request)),
+
   // ── Skills ──
 
   skillsList: (projectPath?: string) => wrapHandler(() => getSkillsCatalog().list(projectPath)),