agentshire 1.0.0

package/src/plugin/citizen-agent-manager.ts

@@ -0,0 +1,178 @@
+/**
+ * Manages independent citizen agents in openclaw.json agents.list.
+ * Creates workspace + SOUL.md for each citizen.
+ * No sub-agents — each citizen is a full independent agent.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { stateDir } from "./paths.js";
+
+export interface AgentChange {
+  action: "create" | "disable" | "update_soul";
+  citizenId: string;
+  citizenName: string;
+  agentId: string;
+  soulContent?: string;
+  specialty?: string;
+}
+
+export interface AgentChangeResult {
+  citizenId: string;
+  action: string;
+  success: boolean;
+  agentId?: string;
+  error?: string;
+}
+
+function getOpenClawConfigPath(): string {
+  return join(stateDir(), "openclaw.json");
+}
+
+function getAgentWorkspacePath(agentId: string): string {
+  return join(stateDir(), `workspace-${agentId}`);
+}
+
+function loadOpenClawConfig(): any {
+  const configPath = getOpenClawConfigPath();
+  if (!existsSync(configPath)) throw new Error("openclaw.json not found");
+  return JSON.parse(readFileSync(configPath, "utf-8"));
+}
+
+function saveOpenClawConfig(cfg: any): void {
+  const configPath = getOpenClawConfigPath();
+  writeFileSync(configPath, JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+}
+
+function getPluginDir(): string {
+  return join(fileURLToPath(import.meta.url), "../../..");
+}
+
+function getStewardWorkspaceDir(): string {
+  return join(stateDir(), "workspace-town-steward");
+}
+
+function syncSharedFiles(workspace: string): void {
+  const pluginDir = getPluginDir();
+  const stewardDir = getStewardWorkspaceDir();
+  const sharedFiles = ["town-guide.md", "town-defaults.json"];
+  for (const file of sharedFiles) {
+    const dst = join(workspace, file);
+    const stewardSrc = join(stewardDir, file);
+    const pluginSrc = join(pluginDir, "town-workspace", file);
+    const src = existsSync(stewardSrc) ? stewardSrc : pluginSrc;
+    if (existsSync(src)) {
+      copyFileSync(src, dst);
+    }
+  }
+}
+
+function writeIdentity(workspace: string, name: string, specialty?: string): void {
+  const lines = [
+    `# ${name}`,
+    "",
+    `- **Name:** ${name}`,
+  ];
+  if (specialty) lines.push(`- **Role:** ${specialty}`);
+  if (specialty) lines.push(`- Vibe: ${specialty}`);
+  writeFileSync(join(workspace, "IDENTITY.md"), lines.join("\n") + "\n", "utf-8");
+}
+
+function createAgentWorkspace(agentId: string, soulContent: string, name: string, specialty?: string): void {
+  const workspace = getAgentWorkspacePath(agentId);
+  if (!existsSync(workspace)) mkdirSync(workspace, { recursive: true });
+  writeFileSync(join(workspace, "SOUL.md"), soulContent, "utf-8");
+  writeIdentity(workspace, name, specialty);
+  syncSharedFiles(workspace);
+}
+
+function updateSoulFile(agentId: string, soulContent: string, name: string, specialty?: string): void {
+  const workspace = getAgentWorkspacePath(agentId);
+  if (!existsSync(workspace)) mkdirSync(workspace, { recursive: true });
+  writeFileSync(join(workspace, "SOUL.md"), soulContent, "utf-8");
+  writeIdentity(workspace, name, specialty);
+  syncSharedFiles(workspace);
+}
+
+function addAgentToConfig(agentId: string, citizenName: string, specialty?: string): void {
+  const cfg = loadOpenClawConfig();
+  const agents: any[] = cfg.agents?.list ?? [];
+  if (agents.some((a: any) => a.id === agentId)) return;
+
+  if (!cfg.agents) cfg.agents = {};
+  if (!cfg.agents.list) cfg.agents.list = [];
+  const identity: Record<string, string> = { name: citizenName };
+  cfg.agents.list.push({
+    id: agentId,
+    name: citizenName,
+    workspace: getAgentWorkspacePath(agentId),
+    identity,
+  });
+  saveOpenClawConfig(cfg);
+  console.log(`[citizen-agent-manager] Added agent ${agentId} to openclaw.json`);
+}
+
+function removeAgentFromConfig(agentId: string): void {
+  const cfg = loadOpenClawConfig();
+  const agents: any[] = cfg.agents?.list ?? [];
+  const before = agents.length;
+  cfg.agents.list = agents.filter((a: any) => a.id !== agentId);
+  if (cfg.agents.list.length < before) {
+    saveOpenClawConfig(cfg);
+    console.log(`[citizen-agent-manager] Removed agent ${agentId} from openclaw.json`);
+  }
+}
+
+function isAgentInConfig(agentId: string): boolean {
+  try {
+    const cfg = loadOpenClawConfig();
+    return (cfg.agents?.list ?? []).some((a: any) => a.id === agentId);
+  } catch {
+    return false;
+  }
+}
+
+export function buildAgentId(citizenId: string): string {
+  return `citizen-${citizenId.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
+}
+
+export async function applyAgentChanges(
+  changes: AgentChange[],
+): Promise<AgentChangeResult[]> {
+  const results: AgentChangeResult[] = [];
+
+  for (const change of changes) {
+    try {
+      switch (change.action) {
+        case "create": {
+          if (!change.soulContent) throw new Error("soulContent is required for create");
+          createAgentWorkspace(change.agentId, change.soulContent, change.citizenName, change.specialty);
+          addAgentToConfig(change.agentId, change.citizenName, change.specialty);
+          results.push({ citizenId: change.citizenId, action: "create", success: true, agentId: change.agentId });
+          break;
+        }
+        case "disable": {
+          removeAgentFromConfig(change.agentId);
+          results.push({ citizenId: change.citizenId, action: "disable", success: true, agentId: change.agentId });
+          break;
+        }
+        case "update_soul": {
+          if (!change.soulContent) throw new Error("soulContent is required for update_soul");
+          updateSoulFile(change.agentId, change.soulContent, change.citizenName, change.specialty);
+          if (!isAgentInConfig(change.agentId)) {
+            addAgentToConfig(change.agentId, change.citizenName);
+          }
+          results.push({ citizenId: change.citizenId, action: "update_soul", success: true, agentId: change.agentId });
+          break;
+        }
+      }
+    } catch (err: any) {
+      const errMsg = err?.message ?? "Unknown error";
+      console.error(`[citizen-agent-manager] Failed to ${change.action} agent for ${change.citizenName}: ${errMsg}`);
+      results.push({ citizenId: change.citizenId, action: change.action, success: false, error: errMsg });
+    }
+  }
+
+  return results;
+}

package/src/plugin/citizen-chat-router.ts

@@ -0,0 +1,83 @@
+/**
+ * Routes user messages to independent citizen agents.
+ * Reads agentId from citizen-config.json (published) and dispatches
+ * to the citizen's own session via SessionKey = "agent:{agentId}:{townSessionId}".
+ */
+
+import { getTownRuntime } from "./runtime.js";
+import { pushCitizenMessages } from "./ws-server.js";
+import { sanitizeTownSessionId } from "./town-session.js";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CHANNEL_ID = "agentshire";
+
+function getPublishedConfigPath(): string {
+  const pluginDir = join(fileURLToPath(import.meta.url), "..", "..", "..");
+  return join(pluginDir, "town-data", "citizen-config.json");
+}
+
+function findCitizenAgentId(npcId: string): string | null {
+  try {
+    const configPath = getPublishedConfigPath();
+    if (!existsSync(configPath)) return null;
+    const config = JSON.parse(readFileSync(configPath, "utf-8"));
+    const characters: any[] = config.characters ?? [];
+    const citizen = characters.find((c: any) => c.id === npcId && c.role === "citizen");
+    if (!citizen?.agentEnabled || !citizen?.agentId) return null;
+    return citizen.agentId;
+  } catch {
+    return null;
+  }
+}
+
+export async function routeCitizenMessage(params: {
+  npcId: string;
+  label: string;
+  message: string;
+  townSessionId: string;
+  accountId: string;
+  cfg: Record<string, unknown>;
+  mediaPaths?: string[];
+}): Promise<void> {
+  const { npcId, label, message, townSessionId, accountId, cfg, mediaPaths } = params;
+
+  const agentId = findCitizenAgentId(npcId);
+  if (!agentId) {
+    console.log(`[citizen-chat] No active agent for ${label} (${npcId}), message dropped`);
+    return;
+  }
+
+  const rt = getTownRuntime();
+  const sanitizedSession = sanitizeTownSessionId(townSessionId);
+  const sessionKey = `agent:${agentId}:${sanitizedSession}`;
+
+  console.log(`[citizen-chat] Routing to ${agentId} (${label}), sessionKey=${sessionKey}`);
+
+  const msgCtx = rt.channel.reply.finalizeInboundContext({
+    Body: message,
+    RawBody: message,
+    CommandBody: message,
+    From: `${CHANNEL_ID}:user`,
+    To: `${CHANNEL_ID}:${npcId}`,
+    SessionKey: sessionKey,
+    AccountId: accountId,
+    OriginatingChannel: CHANNEL_ID,
+    ChatType: "direct",
+    SenderId: "user",
+    Provider: CHANNEL_ID,
+    Surface: CHANNEL_ID,
+    ...(mediaPaths?.length ? { MediaPaths: mediaPaths } : {}),
+  });
+
+  await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx: msgCtx,
+    cfg,
+    dispatcherOptions: {
+      deliver: async (_payload: any) => {
+        setTimeout(() => pushCitizenMessages(agentId, townSessionId), 500);
+      },
+    },
+  });
+}

package/src/plugin/citizen-workshop-manager.ts

@@ -0,0 +1,96 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export interface WorkshopUserConfig {
+  name: string;
+  avatarUrl?: string;
+  avatarId: string;
+  modelSource: "builtin" | "library" | "custom";
+}
+
+export interface WorkshopStewardConfig {
+  name: string;
+  avatarUrl?: string;
+  avatarId: string;
+  modelSource: "builtin" | "library" | "custom";
+  bio: string;
+  persona: string;
+  boundAgentId?: string;
+}
+
+export interface WorkshopCitizenConfig {
+  id: string;
+  name: string;
+  avatarUrl?: string;
+  avatarId: string;
+  modelSource: "builtin" | "library" | "custom";
+  bio: string;
+  industry: string;
+  specialty: string;
+  persona: string;
+  homeId: string;
+  boundAgentId?: string;
+  boundSubAgentId?: string;
+}
+
+export interface CitizenWorkshopConfig {
+  version: 1;
+  user: WorkshopUserConfig;
+  steward: WorkshopStewardConfig;
+  citizens: WorkshopCitizenConfig[];
+}
+
+export class CitizenWorkshopManager {
+  private configPath: string;
+  private soulsDir: string;
+
+  constructor(pluginDir: string) {
+    const townDataDir = join(pluginDir, "town-data");
+    this.configPath = join(townDataDir, "citizen-config.json");
+    this.soulsDir = join(townDataDir, "souls");
+    this.ensureDirs();
+  }
+
+  private ensureDirs(): void {
+    if (!existsSync(this.soulsDir)) mkdirSync(this.soulsDir, { recursive: true });
+  }
+
+  loadConfig(): CitizenWorkshopConfig | null {
+    if (!existsSync(this.configPath)) return null;
+    try {
+      return JSON.parse(readFileSync(this.configPath, "utf-8"));
+    } catch {
+      return null;
+    }
+  }
+
+  saveConfig(config: CitizenWorkshopConfig): void {
+    writeFileSync(this.configPath, JSON.stringify(config, null, 2), "utf-8");
+  }
+
+  saveSoul(name: string, content: string): void {
+    const fileName = `${name.toUpperCase()}.md`;
+    writeFileSync(join(this.soulsDir, fileName), content, "utf-8");
+  }
+
+  loadSoul(name: string): string | null {
+    const fileName = `${name.toUpperCase()}.md`;
+    const filePath = join(this.soulsDir, fileName);
+    if (!existsSync(filePath)) return null;
+    try {
+      return readFileSync(filePath, "utf-8");
+    } catch {
+      return null;
+    }
+  }
+
+  listSouls(): string[] {
+    try {
+      return readdirSync(this.soulsDir)
+        .filter((f: string) => f.endsWith(".md"))
+        .map((f: string) => f.replace(/\.md$/i, ""));
+    } catch {
+      return [];
+    }
+  }
+}

package/src/plugin/custom-asset-manager.ts

@@ -0,0 +1,250 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export type CustomAssetKind = "model" | "character";
+
+export interface CharacterAnimationSet {
+  idle: boolean;
+  walk: boolean;
+  work: boolean;
+  wave: boolean;
+  cheer: boolean;
+  dance: boolean;
+}
+
+export interface CustomAsset {
+  id: string;
+  kind: CustomAssetKind;
+  name: string;
+  fileName: string;
+  fileSize: number;
+  createdAt: string;
+  updatedAt: string;
+  cells?: [number, number];
+  scale?: number;
+  assetType?: string;
+  fixRotationX?: number;
+  fixRotationY?: number;
+  fixRotationZ?: number;
+  thumbnail?: string;
+  thumbnailFileName?: string;
+  animFileName?: string;
+  detectedAnimations?: CharacterAnimationSet;
+  gender?: "male" | "female" | "neutral";
+}
+
+interface CustomAssetCatalog {
+  version: 1;
+  assets: CustomAsset[];
+}
+
+const MAX_FILE_SIZE = 30 * 1024 * 1024; // 30MB
+const MAX_ASSET_COUNT = 20;
+const ALLOWED_EXT = ".glb";
+
+export class CustomAssetManager {
+  private catalogPath: string;
+  private baseDir: string;
+
+  constructor(pluginDir: string) {
+    this.baseDir = join(pluginDir, "town-data", "custom-assets");
+    this.catalogPath = join(this.baseDir, "_catalog.json");
+    this.ensureDirs();
+  }
+
+  private ensureDirs(): void {
+    for (const sub of ["models", "characters", "thumbnails"]) {
+      const dir = join(this.baseDir, sub);
+      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    }
+    if (!existsSync(this.catalogPath)) {
+      this.writeCatalog({ version: 1, assets: [] });
+    }
+  }
+
+  private saveThumbnailFile(assetId: string, dataUrl: string): string | null {
+    try {
+      const match = dataUrl.match(/^data:image\/(\w+);base64,(.+)$/);
+      if (!match) return null;
+      const ext = match[1] === "jpeg" ? "jpg" : match[1];
+      const outName = `${assetId}.${ext}`;
+      writeFileSync(join(this.baseDir, "thumbnails", outName), Buffer.from(match[2], "base64"));
+      return outName;
+    } catch {
+      return null;
+    }
+  }
+
+  private deleteThumbnailFile(fileName?: string): void {
+    if (!fileName) return;
+    try {
+      const fp = join(this.baseDir, "thumbnails", fileName);
+      if (existsSync(fp)) unlinkSync(fp);
+    } catch { /* already gone */ }
+  }
+
+  getThumbnailUrl(asset: CustomAsset): string | undefined {
+    if (asset.thumbnailFileName) return `/custom-assets/thumbnails/${asset.thumbnailFileName}`;
+    if (asset.thumbnail && !asset.thumbnail.startsWith("data:")) return asset.thumbnail;
+    return undefined;
+  }
+
+  migrateThumbnails(): boolean {
+    const catalog = this.readCatalog();
+    let changed = false;
+    for (const asset of catalog.assets) {
+      if (asset.thumbnailFileName) continue;
+      if (!asset.thumbnail || !asset.thumbnail.startsWith("data:")) continue;
+      const outName = this.saveThumbnailFile(asset.id, asset.thumbnail);
+      if (outName) {
+        asset.thumbnailFileName = outName;
+        delete asset.thumbnail;
+        changed = true;
+      }
+    }
+    if (changed) this.writeCatalog(catalog);
+    return changed;
+  }
+
+  private readCatalog(): CustomAssetCatalog {
+    try {
+      return JSON.parse(readFileSync(this.catalogPath, "utf-8"));
+    } catch {
+      return { version: 1, assets: [] };
+    }
+  }
+
+  private writeCatalog(catalog: CustomAssetCatalog): void {
+    writeFileSync(this.catalogPath, JSON.stringify(catalog, null, 2), "utf-8");
+  }
+
+  listAssets(kind?: CustomAssetKind): CustomAsset[] {
+    const catalog = this.readCatalog();
+    if (kind) return catalog.assets.filter((a) => a.kind === kind);
+    return catalog.assets;
+  }
+
+  saveAsset(params: {
+    kind: CustomAssetKind;
+    name: string;
+    data: string; // base64
+    cells?: [number, number];
+    scale?: number;
+    assetType?: string;
+    fixRotationX?: number;
+    fixRotationY?: number;
+    fixRotationZ?: number;
+    thumbnail?: string;
+  }): CustomAsset | { error: string } {
+    const catalog = this.readCatalog();
+
+    if (catalog.assets.length >= MAX_ASSET_COUNT) {
+      return { error: `最多添加 ${MAX_ASSET_COUNT} 个自定义资产` };
+    }
+
+    const buf = Buffer.from(params.data, "base64");
+    if (buf.length > MAX_FILE_SIZE) {
+      return { error: "文件超过 30MB 限制" };
+    }
+
+    const id = randomUUID();
+    const fileName = `${id}${ALLOWED_EXT}`;
+    const subDir = params.kind === "character" ? "characters" : "models";
+    const filePath = join(this.baseDir, subDir, fileName);
+
+    writeFileSync(filePath, buf);
+
+    const now = new Date().toISOString();
+    let thumbnailFileName: string | undefined;
+    if (params.thumbnail && params.thumbnail.startsWith("data:")) {
+      const outName = this.saveThumbnailFile(id, params.thumbnail);
+      if (outName) thumbnailFileName = outName;
+    }
+    const asset: CustomAsset = {
+      id,
+      kind: params.kind,
+      name: params.name.slice(0, 20),
+      fileName,
+      fileSize: buf.length,
+      createdAt: now,
+      updatedAt: now,
+      cells: params.cells,
+      scale: params.scale,
+      assetType: params.assetType,
+      fixRotationX: params.fixRotationX,
+      fixRotationY: params.fixRotationY,
+      fixRotationZ: params.fixRotationZ,
+      ...(thumbnailFileName
+        ? { thumbnailFileName }
+        : params.thumbnail ? { thumbnail: params.thumbnail } : {}),
+    };
+
+    catalog.assets.unshift(asset);
+    this.writeCatalog(catalog);
+    return asset;
+  }
+
+  updateAsset(
+    id: string,
+    updates: Partial<Pick<CustomAsset, "name" | "cells" | "scale" | "assetType" | "fixRotationX" | "fixRotationY" | "fixRotationZ" | "thumbnail">>,
+  ): CustomAsset | { error: string } {
+    const catalog = this.readCatalog();
+    const asset = catalog.assets.find((a) => a.id === id);
+    if (!asset) return { error: "资产不存在" };
+
+    if (updates.name !== undefined) asset.name = updates.name.slice(0, 20);
+    if (updates.cells !== undefined) asset.cells = updates.cells;
+    if (updates.scale !== undefined) asset.scale = updates.scale;
+    if (updates.assetType !== undefined) asset.assetType = updates.assetType;
+    if (updates.fixRotationX !== undefined) asset.fixRotationX = updates.fixRotationX;
+    if (updates.fixRotationY !== undefined) asset.fixRotationY = updates.fixRotationY;
+    if (updates.fixRotationZ !== undefined) asset.fixRotationZ = updates.fixRotationZ;
+    if (updates.thumbnail !== undefined) {
+      if (updates.thumbnail && updates.thumbnail.startsWith("data:")) {
+        const outName = this.saveThumbnailFile(asset.id, updates.thumbnail);
+        if (outName) {
+          this.deleteThumbnailFile(asset.thumbnailFileName);
+          asset.thumbnailFileName = outName;
+          delete asset.thumbnail;
+        } else {
+          asset.thumbnail = updates.thumbnail;
+        }
+      } else {
+        asset.thumbnail = updates.thumbnail;
+      }
+    }
+    asset.updatedAt = new Date().toISOString();
+
+    this.writeCatalog(catalog);
+    return asset;
+  }
+
+  deleteAsset(id: string): { success: boolean; error?: string } {
+    const catalog = this.readCatalog();
+    const idx = catalog.assets.findIndex((a) => a.id === id);
+    if (idx < 0) return { success: false, error: "资产不存在" };
+
+    const asset = catalog.assets[idx];
+    const subDir = asset.kind === "character" ? "characters" : "models";
+    const filePath = join(this.baseDir, subDir, asset.fileName);
+
+    try {
+      if (existsSync(filePath)) unlinkSync(filePath);
+    } catch {
+      /* file already gone */
+    }
+    this.deleteThumbnailFile(asset.thumbnailFileName);
+
+    catalog.assets.splice(idx, 1);
+    this.writeCatalog(catalog);
+    return { success: true };
+  }
+
+  getFilePath(kind: CustomAssetKind, fileName: string): string | null {
+    const subDir = kind === "character" ? "characters" : "models";
+    const filePath = join(this.baseDir, subDir, fileName);
+    if (existsSync(filePath) && statSync(filePath).isFile()) return filePath;
+    return null;
+  }
+}