@memtensor/memos-local-openclaw-plugin 1.0.4-beta.10 → 1.0.4-beta.11

package/src/hub/server.ts

@@ -169,6 +169,20 @@ export class HubServer {
     });
   }
 
+  private embedSkillAsync(skillId: string, name: string, description: string, sourceUserId: string, sourceSkillId: string): void {
+    const embedder = this.opts.embedder;
+    if (!embedder) return;
+    const text = `${name}: ${description}`;
+    embedder.embed([text]).then((vectors) => {
+      if (vectors[0]) {
+        this.opts.store.upsertHubSkillEmbedding(skillId, Array.from(vectors[0]), sourceUserId, sourceSkillId);
+        this.opts.log.info(`hub: embedded shared skill ${skillId}`);
+      }
+    }).catch((err) => {
+      this.opts.log.warn(`hub: embedding shared skill failed: ${err}`);
+    });
+  }
+
   private embedMemoryAsync(memoryId: string, summary: string, content: string): void {
     const embedder = this.opts.embedder;
     if (!embedder) return;
@@ -205,46 +219,70 @@ export class HubServer {
         || (req.headers["x-client-ip"] as string)?.trim()
         || (req.headers["x-forwarded-for"] as string)?.split(",")[0]?.trim()
         || req.socket.remoteAddress || "";
-      const existingUsers = this.opts.store.listHubUsers();
-      const existingUser = existingUsers.find(u => u.username === username);
+      const identityKey = typeof body.identityKey === "string" ? body.identityKey.trim() : "";
+
+      let existingUser = identityKey
+        ? this.userManager.findByIdentityKey(identityKey)
+        : null;
+      if (!existingUser) {
+        const existingUsers = this.opts.store.listHubUsers();
+        existingUser = existingUsers.find(u => u.username === username && u.status !== "left" && u.status !== "removed") ?? null;
+      }
+
       if (existingUser) {
         try { this.opts.store.updateHubUserActivity(existingUser.id, joinIp); } catch { /* best-effort */ }
+
         if (existingUser.status === "active") {
           const token = issueUserToken(
             { userId: existingUser.id, username: existingUser.username, role: existingUser.role, status: "active" },
             this.authSecret,
           );
           this.userManager.approveUser(existingUser.id, token);
-          return this.json(res, 200, { status: "active", userId: existingUser.id, userToken: token });
+          if (identityKey && !existingUser.identityKey) {
+            this.opts.store.upsertHubUser({ ...existingUser, identityKey });
+          }
+          return this.json(res, 200, { status: "active", userId: existingUser.id, userToken: token, identityKey: existingUser.identityKey || identityKey });
         }
         if (existingUser.status === "pending") {
           this.notifyAdmins("user_join_request", "user", username, "", { dedup: true });
-          return this.json(res, 200, { status: "pending", userId: existingUser.id });
+          return this.json(res, 200, { status: "pending", userId: existingUser.id, identityKey: existingUser.identityKey || identityKey });
         }
         if (existingUser.status === "rejected") {
           if (body.reapply === true) {
             this.userManager.resetToPending(existingUser.id);
             this.notifyAdmins("user_join_request", "user", username, "");
             this.opts.log.info(`Hub: rejected user "${username}" (${existingUser.id}) re-applied, reset to pending`);
-            return this.json(res, 200, { status: "pending", userId: existingUser.id });
+            return this.json(res, 200, { status: "pending", userId: existingUser.id, identityKey: existingUser.identityKey || identityKey });
           }
           return this.json(res, 200, { status: "rejected", userId: existingUser.id });
         }
         if (existingUser.status === "removed") {
-          this.userManager.resetToPending(existingUser.id);
-          this.notifyAdmins("user_join_request", "user", username, "");
-          this.opts.log.info(`Hub: removed user "${username}" (${existingUser.id}) re-applied, reset to pending`);
-          return this.json(res, 200, { status: "pending", userId: existingUser.id });
+          this.userManager.rejoinUser(existingUser.id);
+          this.notifyAdmins("user_join_request", "user", username, "", { dedup: true });
+          this.opts.log.info(`Hub: removed user "${username}" (${existingUser.id}) re-applied via rejoin, reset to pending`);
+          return this.json(res, 200, { status: "pending", userId: existingUser.id, identityKey: existingUser.identityKey || identityKey });
+        }
+        if (existingUser.status === "left") {
+          this.userManager.rejoinUser(existingUser.id);
+          this.notifyAdmins("user_join_request", "user", username, "", { dedup: true });
+          this.opts.log.info(`Hub: left user "${username}" (${existingUser.id}) re-applied via rejoin, reset to pending`);
+          return this.json(res, 200, { status: "pending", userId: existingUser.id, identityKey: existingUser.identityKey || identityKey });
+        }
+        if (existingUser.status === "blocked") {
+          return this.json(res, 200, { status: "blocked", userId: existingUser.id });
         }
       }
+
+      const generatedIdentityKey = identityKey || randomUUID();
       const user = this.userManager.createPendingUser({
         username,
         deviceName: typeof body.deviceName === "string" ? body.deviceName : undefined,
+        identityKey: generatedIdentityKey,
       });
       try { this.opts.store.updateHubUserActivity(user.id, joinIp); } catch { /* best-effort */ }
       this.opts.log.info(`Hub: user "${username}" (${user.id}) registered as pending, awaiting admin approval`);
       this.notifyAdmins("user_join_request", "user", username, "");
-      return this.json(res, 200, { status: "pending", userId: user.id });
+      return this.json(res, 200, { status: "pending", userId: user.id, identityKey: generatedIdentityKey });
     }
 
     if (req.method === "POST" && routePath === "/api/v1/hub/registration-status") {
@@ -262,6 +300,15 @@ export class HubServer {
       if (user.status === "rejected") {
         return this.json(res, 200, { status: "rejected" });
       }
+      if (user.status === "blocked") {
+        return this.json(res, 200, { status: "blocked" });
+      }
+      if (user.status === "left") {
+        return this.json(res, 200, { status: "left" });
+      }
+      if (user.status === "removed") {
+        return this.json(res, 200, { status: "removed" });
+      }
       if (user.status === "active") {
         const token = issueUserToken(
           { userId: user.id, username: user.username, role: user.role, status: user.status },
@@ -286,12 +333,10 @@ export class HubServer {
     }
 
     if (req.method === "POST" && routePath === "/api/v1/hub/leave") {
-      try {
-        this.opts.store.updateHubUserActivity(auth.userId, "", 0);
-      } catch { /* best-effort */ }
+      this.userManager.markUserLeft(auth.userId);
       this.knownOnlineUsers.delete(auth.userId);
       this.notifyAdmins("user_offline", "user", auth.username, auth.userId);
-      this.opts.log.info(`Hub: user "${auth.username}" (${auth.userId}) left voluntarily`);
+      this.opts.log.info(`Hub: user "${auth.username}" (${auth.userId}) left voluntarily, status set to "left"`);
       return this.json(res, 200, { ok: true });
     }
 
@@ -609,20 +654,70 @@ export class HubServer {
     }
 
     if (req.method === "GET" && routePath === "/api/v1/hub/skills") {
-      const hits = this.opts.store.searchHubSkills(String(url.searchParams.get("query") || ""), {
+      const skillQuery = String(url.searchParams.get("query") || "");
+      const skillMaxResults = Number(url.searchParams.get("maxResults") || 10);
+      const ftsSkillHits = this.opts.store.searchHubSkills(skillQuery, {
         userId: auth.userId,
-        maxResults: Number(url.searchParams.get("maxResults") || 10),
-      }).map(({ hit }) => ({
-        skillId: hit.id,
-        name: hit.name,
-        description: hit.description,
-        version: hit.version,
-        visibility: hit.visibility,
-        groupName: hit.group_name,
-        ownerName: hit.owner_name || "unknown",
-        ownerStatus: hit.owner_status || "",
-        qualityScore: hit.quality_score,
-      }));
+        maxResults: skillMaxResults * 2,
+      });
+
+      let mergedSkillIds: string[];
+      if (this.opts.embedder && skillQuery) {
+        try {
+          const [queryVec] = await this.opts.embedder.embed([skillQuery]);
+          if (queryVec) {
+            const skillEmbs = this.opts.store.getVisibleHubSkillEmbeddings();
+            const cosineSim = (vec: Float32Array) => {
+              let dot = 0, nA = 0, nB = 0;
+              for (let i = 0; i < queryVec.length && i < vec.length; i++) {
+                dot += queryVec[i] * vec[i]; nA += queryVec[i] * queryVec[i]; nB += vec[i] * vec[i];
+              }
+              return nA > 0 && nB > 0 ? dot / (Math.sqrt(nA) * Math.sqrt(nB)) : 0;
+            };
+            const vecScored = skillEmbs
+              .map(e => ({ id: e.skillId, score: cosineSim(e.vector) }))
+              .filter(e => e.score > 0.3)
+              .sort((a, b) => b.score - a.score)
+              .slice(0, skillMaxResults * 2);
+
+            const K = 60;
+            const rrfScores = new Map<string, number>();
+            ftsSkillHits.forEach(({ hit }, idx) => {
+              rrfScores.set(hit.id, (rrfScores.get(hit.id) ?? 0) + 1 / (K + idx + 1));
+            });
+            vecScored.forEach(({ id }, idx) => {
+              rrfScores.set(id, (rrfScores.get(id) ?? 0) + 1 / (K + idx + 1));
+            });
+            mergedSkillIds = [...rrfScores.entries()].sort((a, b) => b[1] - a[1]).slice(0, skillMaxResults).map(([id]) => id);
+          } else {
+            mergedSkillIds = ftsSkillHits.slice(0, skillMaxResults).map(({ hit }) => hit.id);
+          }
+        } catch {
+          mergedSkillIds = ftsSkillHits.slice(0, skillMaxResults).map(({ hit }) => hit.id);
+        }
+      } else {
+        mergedSkillIds = ftsSkillHits.slice(0, skillMaxResults).map(({ hit }) => hit.id);
+      }
+
+      const ftsSkillMap = new Map(ftsSkillHits.map(({ hit }) => [hit.id, hit]));
+      const hits = mergedSkillIds.map(id => {
+        const hit = ftsSkillMap.get(id);
+        if (hit) {
+          return {
+            skillId: hit.id, name: hit.name, description: hit.description,
+            version: hit.version, visibility: hit.visibility, groupName: hit.group_name,
+            ownerName: hit.owner_name || "unknown", ownerStatus: hit.owner_status || "",
+            qualityScore: hit.quality_score,
+          };
+        }
+        const skill = this.opts.store.getHubSkillById(id);
+        if (!skill) return null;
+        return {
+          skillId: skill.id, name: skill.name, description: skill.description,
+          version: skill.version, visibility: skill.visibility, groupName: "",
+          ownerName: "unknown", ownerStatus: "", qualityScore: skill.qualityScore,
+        };
+      }).filter(Boolean);
       return this.json(res, 200, { hits });
     }
 
@@ -648,6 +743,7 @@ export class HubServer {
         createdAt: existing?.createdAt ?? Date.now(),
         updatedAt: Date.now(),
       });
+      this.embedSkillAsync(skillId, String(metadata.name || sourceSkillId), String(metadata.description || ""), auth.userId, sourceSkillId);
       if (!existing) {
         this.notifyAdmins("resource_shared", "skill", String(metadata.name || sourceSkillId), auth.userId);
       }

package/src/hub/user-manager.ts

@@ -4,13 +4,24 @@ import type { Logger } from "../types";
 import type { UserInfo } from "../sharing/types";
 import type { SqliteStore } from "../storage/sqlite";
 
-type ManagedHubUser = UserInfo & { tokenHash: string; createdAt: number; approvedAt: number | null; lastIp: string; lastActiveAt: number | null };
+type ManagedHubUser = UserInfo & {
+  tokenHash: string;
+  createdAt: number;
+  approvedAt: number | null;
+  lastIp: string;
+  lastActiveAt: number | null;
+  identityKey?: string;
+  leftAt?: number | null;
+  removedAt?: number | null;
+  rejectedAt?: number | null;
+  rejoinRequestedAt?: number | null;
+};
 
 export class HubUserManager {
   constructor(private store: SqliteStore, private log: Logger) {}
 
-  createPendingUser(input: { username: string; deviceName?: string }): ManagedHubUser {
-    const user = {
+  createPendingUser(input: { username: string; deviceName?: string; identityKey?: string }): ManagedHubUser {
+    const user: ManagedHubUser = {
       id: randomUUID(),
       username: input.username,
       deviceName: input.deviceName,
@@ -22,11 +33,36 @@ export class HubUserManager {
       approvedAt: null,
       lastIp: "",
       lastActiveAt: null,
+      identityKey: input.identityKey || "",
     };
     this.store.upsertHubUser(user);
     return user;
   }
 
+  findByIdentityKey(identityKey: string): ManagedHubUser | null {
+    if (!identityKey) return null;
+    return this.store.findHubUserByIdentityKey(identityKey);
+  }
+
+  markUserLeft(userId: string): boolean {
+    this.log.info(`Hub: user "${userId}" marked as left`);
+    return this.store.markHubUserLeft(userId);
+  }
+
+  rejoinUser(userId: string): ManagedHubUser | null {
+    const user = this.store.getHubUser(userId);
+    if (!user) return null;
+    const updated: ManagedHubUser = {
+      ...user,
+      status: "pending" as const,
+      tokenHash: "",
+      rejoinRequestedAt: Date.now(),
+    };
+    this.store.upsertHubUser(updated);
+    this.log.info(`Hub: user "${userId}" (${user.username}) requested rejoin, previous status: ${user.status}`);
+    return updated;
+  }
+
   listPendingUsers(): ManagedHubUser[] {
     return this.store.listHubUsers("pending");
   }
@@ -105,7 +141,7 @@ export class HubUserManager {
 
   isUsernameTaken(username: string, excludeUserId?: string): boolean {
     const users = this.store.listHubUsers();
-    return users.some(u => u.username === username && u.id !== excludeUserId);
+    return users.some(u => u.username === username && u.id !== excludeUserId && u.status !== "left" && u.status !== "removed");
   }
 
   updateUsername(userId: string, newUsername: string): ManagedHubUser | null {
@@ -119,10 +155,10 @@ export class HubUserManager {
   rejectUser(userId: string): ManagedHubUser | null {
     const user = this.store.getHubUser(userId);
     if (!user) return null;
-    const updated = {
+    const updated: ManagedHubUser = {
       ...user,
       status: "rejected" as const,
-      approvedAt: Date.now(),
+      rejectedAt: Date.now(),
     };
     this.store.upsertHubUser(updated);
     return updated;

package/src/recall/engine.ts

@@ -202,6 +202,7 @@ export class RecallEngine {
           taskId: null,
           skillId: null,
           owner: `hub-user:${mem.sourceUserId}`,
+          origin: "hub-memory",
           source: {
             ts: mem.createdAt,
             role: (mem.role || "assistant") as any,
@@ -228,6 +229,7 @@ export class RecallEngine {
         score: Math.round(candidate.score * 1000) / 1000,
         taskId: chunk.taskId,
         skillId: chunk.skillId,
+        origin: chunk.owner === "public" ? "local-shared" : "local",
         source: {
           ts: chunk.createdAt,
           role: chunk.role,

package/src/sharing/types.ts

@@ -12,7 +12,7 @@ import type {
 export type HubScope = "local" | "group" | "all";
 export type SharedVisibility = "group" | "public";
 export type UserRole = "admin" | "member";
-export type UserStatus = "pending" | "active" | "blocked" | "rejected" | "removed";
+export type UserStatus = "pending" | "active" | "blocked" | "rejected" | "removed" | "left";
 
 export type { ClientModeConfig, HubModeConfig, SharingCapabilities, SharingConfig, SharingRole };
 

package/src/skill/evolver.ts

@@ -9,7 +9,7 @@ import { DEFAULTS } from "../types";
 import { SkillEvaluator } from "./evaluator";
 import { SkillGenerator } from "./generator";
 import { SkillUpgrader } from "./upgrader";
-import { SkillInstaller } from "./installer";
+import { SkillInstaller, type SkillInstallMode } from "./installer";
 import { buildSkillConfigChain, callLLMWithFallback } from "../shared/llm-call";
 
 export type SkillEvolvedCallback = (skillName: string, upgradeType: "created" | "upgraded") => void;
@@ -96,10 +96,19 @@ export class SkillEvolver {
       return;
     }
 
+    const preferUpgrade = this.ctx.config.skillEvolution?.preferUpgradeExisting ?? DEFAULTS.skillPreferUpgrade;
     const relatedSkill = await this.findRelatedSkill(task);
 
     if (relatedSkill) {
       await this.handleExistingSkill(task, chunks, relatedSkill);
+    } else if (preferUpgrade) {
+      const nameCandidate = await this.findSkillByNameSimilarity(task);
+      if (nameCandidate) {
+        this.ctx.log.info(`SkillEvolver: preferUpgrade found name-similar skill "${nameCandidate.name}" for task "${task.title}"`);
+        await this.handleExistingSkill(task, chunks, nameCandidate);
+      } else {
+        await this.handleNewSkill(task, chunks);
+      }
     } else {
       await this.handleNewSkill(task, chunks);
     }
@@ -281,7 +290,11 @@ Use selectedIndex 0 when none is highly relevant.`;
 
       if (upgraded) {
         this.store.linkTaskSkill(task.id, freshSkill.id, "evolved_from", freshSkill.version + 1);
-        this.installer.syncIfInstalled(freshSkill.name);
+        if (freshSkill.installed) {
+          this.installer.syncIfInstalled(freshSkill.name);
+        } else {
+          this.autoInstallIfNeeded(freshSkill);
+        }
         this.onSkillEvolved?.(freshSkill.name, "upgraded");
       } else {
         this.store.linkTaskSkill(task.id, freshSkill.id, "applied_to", freshSkill.version);
@@ -304,6 +317,13 @@ Use selectedIndex 0 when none is highly relevant.`;
     const evalResult = await this.evaluator.evaluateCreate(task);
 
     if (evalResult.shouldGenerate && evalResult.confidence >= minConfidence) {
+      const existingByName = this.store.getSkillByName(evalResult.suggestedName);
+      if (existingByName && (existingByName.status === "active" || existingByName.status === "draft")) {
+        this.ctx.log.info(`SkillEvolver: skill "${evalResult.suggestedName}" already exists, redirecting to upgrade instead of create`);
+        await this.handleExistingSkill(task, chunks, existingByName);
+        return;
+      }
+
       this.ctx.log.info(`SkillEvolver: generating new skill "${evalResult.suggestedName}" — ${evalResult.reason}`);
       this.store.setTaskSkillMeta(task.id, { skillStatus: "generating", skillReason: evalResult.reason });
 
@@ -313,10 +333,7 @@ Use selectedIndex 0 when none is highly relevant.`;
       this.store.setTaskSkillMeta(task.id, { skillStatus: "generated", skillReason: evalResult.reason });
       this.onSkillEvolved?.(skill.name, "created");
 
-      const autoInstall = this.ctx.config.skillEvolution?.autoInstall ?? DEFAULTS.skillAutoInstall;
-      if (autoInstall && skill.status === "active") {
-        this.installer.install(skill.id);
-      }
+      this.autoInstallIfNeeded(skill);
     } else {
       const reason = evalResult.reason || `confidence不足 (${evalResult.confidence} < ${minConfidence})`;
       this.ctx.log.debug(`SkillEvolver: task "${task.title}" not worth generating skill — ${reason}`);
@@ -331,6 +348,41 @@ Use selectedIndex 0 when none is highly relevant.`;
     this.ctx.log.debug(`SkillEvolver: marked ${chunks.length} chunks with skill_id=${skillId}`);
   }
 
+  private async findSkillByNameSimilarity(task: Task): Promise<Skill | null> {
+    const query = task.title.slice(0, 200);
+    const owner = task.owner ?? "agent:main";
+
+    try {
+      const ftsHits = this.store.skillFtsSearch(query, 5, "mix", owner);
+      for (const hit of ftsHits) {
+        if (hit.score < 0.5) continue;
+        const skill = this.store.getSkill(hit.skillId);
+        if (skill && (skill.status === "active" || skill.status === "draft")) {
+          return skill;
+        }
+      }
+    } catch { /* best-effort */ }
+
+    return null;
+  }
+
+  private autoInstallIfNeeded(skill: Skill): void {
+    if (skill.status !== "active") return;
+
+    const explicitAutoInstall = this.ctx.config.skillEvolution?.autoInstall ?? DEFAULTS.skillAutoInstall;
+    if (explicitAutoInstall) {
+      this.installer.install(skill.id);
+      this.ctx.log.info(`SkillEvolver: auto-installed "${skill.name}" (explicit autoInstall=true)`);
+      return;
+    }
+
+    const manifest = SkillInstaller.buildManifest(skill.dirPath, !!skill.installed, skill.name);
+    if (manifest.installMode === "install_recommended") {
+      this.installer.install(skill.id);
+      this.ctx.log.info(`SkillEvolver: auto-installed "${skill.name}" (install_recommended: ${manifest.scriptsCount} scripts, ${Math.round(manifest.totalSize / 1024)}KB)`);
+    }
+  }
+
   private readSkillContent(skill: Skill): string | null {
     const filePath = path.join(skill.dirPath, "SKILL.md");
     try {

package/src/skill/generator.ts

@@ -484,14 +484,55 @@ export class SkillGenerator {
 
   private buildConversationText(chunks: Chunk[]): string {
     const lines: string[] = [];
+    const redact = this.ctx.config.skillEvolution?.redactSensitiveInSkill ?? true;
+
     for (const c of chunks) {
-      if (c.role !== "user" && c.role !== "assistant") continue;
-      const roleLabel = c.role === "user" ? "User" : "Assistant";
-      lines.push(`[${roleLabel}]: ${c.content}`);
+      let roleLabel: string;
+      switch (c.role) {
+        case "user": roleLabel = "User"; break;
+        case "assistant": roleLabel = "Assistant"; break;
+        case "tool": roleLabel = "Tool"; break;
+        case "system": roleLabel = "System"; break;
+        default: continue;
+      }
+
+      let content = c.content;
+      if (c.role === "system") continue;
+
+      if (c.role === "tool") {
+        content = this.truncateToolOutput(content);
+      }
+
+      if (redact) {
+        content = SkillGenerator.redactSensitive(content);
+      }
+
+      lines.push(`[${roleLabel}]: ${content}`);
     }
     return lines.join("\n\n");
   }
 
+  private truncateToolOutput(content: string): string {
+    const MAX_TOOL_OUTPUT = 1500;
+    if (content.length <= MAX_TOOL_OUTPUT) return content;
+    const head = content.slice(0, MAX_TOOL_OUTPUT * 0.6);
+    const tail = content.slice(-MAX_TOOL_OUTPUT * 0.3);
+    return `${head}\n... (truncated ${content.length - MAX_TOOL_OUTPUT} chars) ...\n${tail}`;
+  }
+
+  static redactSensitive(text: string): string {
+    let result = text;
+    result = result.replace(/\bsk-[a-zA-Z0-9]{20,}\b/g, "sk-***REDACTED***");
+    result = result.replace(/\bBearer\s+[a-zA-Z0-9_\-.]{20,}\b/g, "Bearer ***REDACTED***");
+    result = result.replace(/\bAKIA[0-9A-Z]{16}\b/g, "AKIA***REDACTED***");
+    result = result.replace(/(api[_-]?key|secret|token|password|credential)\s*[:=]\s*["']([^"']{8,})["']/gi,
+      (match, key) => `${key}="***REDACTED***"`);
+    result = result.replace(/\/Users\/[a-zA-Z0-9._-]+\//g, "/Users/****/");
+    result = result.replace(/\/home\/[a-zA-Z0-9._-]+\//g, "/home/****/");
+    result = result.replace(/C:\\Users\\[a-zA-Z0-9._-]+\\/g, "C:\\Users\\****\\");
+    return result;
+  }
+
   private parseDescription(content: string): string {
     const match = content.match(/description:\s*"([^"]+)"/);
     if (match) return match[1];
@@ -499,6 +540,4 @@ export class SkillGenerator {
     if (match2) return match2[1];
     return "";
   }
-
-
 }

package/src/skill/installer.ts

@@ -3,6 +3,26 @@ import * as path from "path";
 import type { SqliteStore } from "../storage/sqlite";
 import type { PluginContext } from "../types";
 
+export type SkillInstallMode = "inline" | "on_demand" | "install_recommended";
+
+export interface CompanionFileInfo {
+  relativePath: string;
+  size: number;
+  type: "script" | "reference" | "eval" | "other";
+}
+
+export interface SkillCompanionManifest {
+  hasCompanionFiles: boolean;
+  installMode: SkillInstallMode;
+  installed: boolean;
+  installedPath?: string;
+  files: CompanionFileInfo[];
+  totalSize: number;
+  scriptsCount: number;
+  referencesCount: number;
+  evalsCount: number;
+}
+
 export class SkillInstaller {
   private workspaceSkillsDir: string;
 
@@ -13,6 +33,82 @@ export class SkillInstaller {
     this.workspaceSkillsDir = path.join(ctx.workspaceDir, "skills");
   }
 
+  getCompanionManifest(skillId: string): SkillCompanionManifest | null {
+    const skill = this.store.getSkill(skillId);
+    if (!skill) return null;
+    return SkillInstaller.buildManifest(skill.dirPath, !!skill.installed, skill.name, this.workspaceSkillsDir);
+  }
+
+  static buildManifest(dirPath: string, installed: boolean, skillName: string, workspaceSkillsDir?: string): SkillCompanionManifest {
+    const files: CompanionFileInfo[] = [];
+
+    const scanDir = (subDir: string, type: CompanionFileInfo["type"]) => {
+      const fullDir = path.join(dirPath, subDir);
+      if (!fs.existsSync(fullDir)) return;
+      try {
+        for (const f of fs.readdirSync(fullDir)) {
+          const fp = path.join(fullDir, f);
+          try {
+            const stat = fs.statSync(fp);
+            if (stat.isFile()) {
+              files.push({ relativePath: `${subDir}/${f}`, size: stat.size, type });
+            }
+          } catch { /* best-effort */ }
+        }
+      } catch { /* best-effort */ }
+    };
+
+    scanDir("scripts", "script");
+    scanDir("references", "reference");
+    scanDir("evals", "eval");
+
+    const scriptsCount = files.filter(f => f.type === "script").length;
+    const referencesCount = files.filter(f => f.type === "reference").length;
+    const evalsCount = files.filter(f => f.type === "eval").length;
+    const totalSize = files.reduce((sum, f) => sum + f.size, 0);
+    const hasCompanionFiles = files.filter(f => f.type !== "eval").length > 0;
+
+    let installMode: SkillInstallMode = "inline";
+    if (hasCompanionFiles) {
+      const executableScripts = files.filter(f => f.type === "script");
+      const largeFiles = files.filter(f => f.size > 5000);
+      if (executableScripts.length >= 3 || largeFiles.length >= 2 || totalSize > 20000) {
+        installMode = "install_recommended";
+      } else {
+        installMode = "on_demand";
+      }
+    }
+
+    const installedPath = installed && workspaceSkillsDir
+      ? path.join(workspaceSkillsDir, skillName)
+      : undefined;
+
+    return { hasCompanionFiles, installMode, installed, installedPath, files, totalSize, scriptsCount, referencesCount, evalsCount };
+  }
+
+  readCompanionFile(skillId: string, relativePath: string): { content: string; size: number } | { error: string } {
+    const skill = this.store.getSkill(skillId);
+    if (!skill) return { error: "Skill not found" };
+
+    const normalized = relativePath.replace(/\.\./g, "");
+    const fullPath = path.join(skill.dirPath, normalized);
+
+    if (!fullPath.startsWith(skill.dirPath)) {
+      return { error: "Path traversal not allowed" };
+    }
+
+    if (!fs.existsSync(fullPath)) {
+      return { error: `File not found: ${relativePath}` };
+    }
+
+    try {
+      const content = fs.readFileSync(fullPath, "utf-8");
+      return { content, size: content.length };
+    } catch (err) {
+      return { error: `Cannot read file: ${err}` };
+    }
+  }
+
   install(skillId: string): { installed: boolean; path: string; message: string } {
     const skill = this.store.getSkill(skillId);
     if (!skill) return { installed: false, path: "", message: "Skill not found" };
@@ -22,8 +118,7 @@ export class SkillInstaller {
     }
 
     const dstDir = path.join(this.workspaceSkillsDir, skill.name);
-    fs.mkdirSync(dstDir, { recursive: true });
-    fs.cpSync(skill.dirPath, dstDir, { recursive: true });
+    this.cleanSync(skill.dirPath, dstDir);
     this.store.updateSkill(skillId, { installed: 1 });
 
     this.ctx.log.info(`Skill installed: "${skill.name}" v${skill.version} → ${dstDir}`);
@@ -51,9 +146,17 @@ export class SkillInstaller {
     if (!skill || !skill.installed) return;
 
     const dstDir = path.join(this.workspaceSkillsDir, skill.name);
-    if (fs.existsSync(dstDir) && fs.existsSync(skill.dirPath)) {
-      fs.cpSync(skill.dirPath, dstDir, { recursive: true });
+    if (fs.existsSync(skill.dirPath)) {
+      this.cleanSync(skill.dirPath, dstDir);
       this.ctx.log.info(`Skill synced: "${skill.name}" v${skill.version} → workspace`);
     }
   }
+
+  private cleanSync(srcDir: string, dstDir: string): void {
+    if (fs.existsSync(dstDir)) {
+      fs.rmSync(dstDir, { recursive: true });
+    }
+    fs.mkdirSync(dstDir, { recursive: true });
+    fs.cpSync(srcDir, dstDir, { recursive: true });
+  }
 }