@downcity/plugins 1.0.4

package/src/contact/runtime/Paths.ts

@@ -0,0 +1,139 @@
+/**
+ * contact plugin runtime 路径规则。
+ *
+ * 关键点（中文）
+ * - 所有 contact 运行时状态都收敛在 `.downcity/contact`。
+ * - 每个 contact 一个目录；每条 inbox share 一个目录。
+ */
+
+import path from "node:path";
+
+function cleanSegment(input: string, label: string): string {
+  const value = String(input || "").trim();
+  if (!/^[a-zA-Z0-9._-]+$/.test(value)) {
+    throw new Error(`Invalid ${label}: ${input}`);
+  }
+  if (value === "." || value === ".." || value.includes("..")) {
+    throw new Error(`Invalid ${label}: ${input}`);
+  }
+  return value;
+}
+
+/**
+ * contact 根目录。
+ */
+export function getContactRootPath(projectRoot: string): string {
+  return path.join(projectRoot, ".downcity", "contact");
+}
+
+/**
+ * contacts 根目录。
+ */
+export function getContactsRootPath(projectRoot: string): string {
+  return path.join(getContactRootPath(projectRoot), "contacts");
+}
+
+/**
+ * 单个 contact 目录。
+ */
+export function getContactDirectoryPath(
+  projectRoot: string,
+  contactId: string,
+): string {
+  return path.join(getContactsRootPath(projectRoot), cleanSegment(contactId, "contactId"));
+}
+
+/**
+ * 单个 contact 元信息文件。
+ */
+export function getContactJsonPath(projectRoot: string, contactId: string): string {
+  return path.join(getContactDirectoryPath(projectRoot, contactId), "contact.json");
+}
+
+/**
+ * 单个 contact 的长期对话历史文件。
+ */
+export function getContactMessagesPath(
+  projectRoot: string,
+  contactId: string,
+): string {
+  return path.join(getContactDirectoryPath(projectRoot, contactId), "messages.jsonl");
+}
+
+/**
+ * link 根目录。
+ */
+export function getContactLinksRootPath(projectRoot: string): string {
+  return path.join(getContactRootPath(projectRoot), "links");
+}
+
+/**
+ * 单个 link 记录文件。
+ */
+export function getContactLinkPath(projectRoot: string, linkId: string): string {
+  return path.join(getContactLinksRootPath(projectRoot), `${cleanSegment(linkId, "linkId")}.json`);
+}
+
+/**
+ * inbox 根目录。
+ */
+export function getContactInboxRootPath(projectRoot: string): string {
+  return path.join(getContactRootPath(projectRoot), "inbox");
+}
+
+/**
+ * 单个 inbox share 目录。
+ */
+export function getContactInboxSharePath(
+  projectRoot: string,
+  shareId: string,
+): string {
+  return path.join(getContactInboxRootPath(projectRoot), cleanSegment(shareId, "shareId"));
+}
+
+/**
+ * 单个 inbox share 元信息文件。
+ */
+export function getContactInboxShareMetaPath(
+  projectRoot: string,
+  shareId: string,
+): string {
+  return path.join(getContactInboxSharePath(projectRoot, shareId), "meta.json");
+}
+
+/**
+ * 单个 inbox share payload 文件。
+ */
+export function getContactInboxSharePayloadPath(
+  projectRoot: string,
+  shareId: string,
+): string {
+  return path.join(getContactInboxSharePath(projectRoot, shareId), "payload.json");
+}
+
+/**
+ * 单个 inbox share 文件根目录。
+ */
+export function getContactInboxShareFilesPath(
+  projectRoot: string,
+  shareId: string,
+): string {
+  return path.join(getContactInboxSharePath(projectRoot, shareId), "files");
+}
+
+/**
+ * received 根目录。
+ */
+export function getContactReceivedRootPath(projectRoot: string): string {
+  return path.join(getContactRootPath(projectRoot), "received");
+}
+
+/**
+ * 单个 received share 目录。
+ */
+export function getContactReceivedSharePath(
+  projectRoot: string,
+  shareId: string,
+): string {
+  return path.join(getContactReceivedRootPath(projectRoot), cleanSegment(shareId, "shareId"));
+}

package/src/contact/runtime/RemoteClient.ts

@@ -0,0 +1,158 @@
+/**
+ * contact 远端 HTTP 客户端。
+ *
+ * 关键点（中文）
+ * - contact 的 agent-to-agent 调用统一走 plugin runtime command 接口。
+ * - 已建联后的敏感调用必须携带 contact token。
+ */
+
+import type { JsonValue } from "@downcity/agent/internal/types/common/Json.js";
+
+type JsonRecord = Record<string, unknown>;
+
+function isRecord(value: unknown): value is JsonRecord {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function normalizeEndpoint(endpoint: string): string {
+  const raw = String(endpoint || "").trim();
+  if (!raw) throw new Error("endpoint is required");
+  const withProtocol = /^https?:\/\//i.test(raw) ? raw : `http://${raw}`;
+  const url = new URL(withProtocol);
+  url.pathname = "";
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+
+function unwrapPluginCommandEnvelope<T>(value: T): T {
+  if (!isRecord(value)) return value;
+  const inner = value.data;
+  if (typeof value.success === "boolean" && isRecord(inner)) {
+    // 关键点（中文）：统一 command 路由会包一层 `{ success, data }`。
+    return inner as T;
+  }
+  return value;
+}
+
+async function postPluginCommand<T>(params: {
+  endpoint: string;
+  command: string;
+  body?: JsonValue;
+  token?: string;
+  wrapBody?: boolean;
+}): Promise<T> {
+  const url = new URL("/api/plugins/command", normalizeEndpoint(params.endpoint)).toString();
+  const payloadBody =
+    params.wrapBody
+      ? {
+          ...(params.body !== undefined ? { body: params.body } : {}),
+          ...(params.token ? { token: params.token } : {}),
+        }
+      : params.body && isRecord(params.body)
+        ? {
+            ...params.body,
+            ...(params.token ? { token: params.token } : {}),
+          }
+        : {
+            ...(params.body !== undefined ? { body: params.body } : {}),
+            ...(params.token ? { token: params.token } : {}),
+          };
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      pluginName: "contact",
+      command: params.command,
+      payload: payloadBody,
+    }),
+  });
+  const data = (await response.json().catch(() => null)) as T & {
+    error?: string;
+    message?: string;
+  };
+  if (!response.ok) {
+    throw new Error(data?.error || data?.message || `HTTP ${response.status}`);
+  }
+  return unwrapPluginCommandEnvelope<T>(data);
+}
+
+/**
+ * 调用远端 ping。
+ */
+export async function callContactPing<T>(params: {
+  endpoint: string;
+  token?: string;
+}): Promise<T> {
+  return await postPluginCommand<T>({
+    endpoint: params.endpoint,
+    command: "remoteping",
+    token: params.token,
+  });
+}
+
+/**
+ * 调用远端 approve。
+ */
+export async function callContactApprove<T>(params: {
+  endpoint: string;
+  body: JsonValue;
+}): Promise<T> {
+  return await postPluginCommand<T>({
+    endpoint: params.endpoint,
+    command: "remoteapprove",
+    body: params.body,
+  });
+}
+
+/**
+ * 调用远端 confirm。
+ */
+export async function callContactConfirm<T>(params: {
+  endpoint: string;
+  body: JsonValue;
+}): Promise<T> {
+  return await postPluginCommand<T>({
+    endpoint: params.endpoint,
+    command: "remoteconfirm",
+    body: params.body,
+  });
+}
+
+/**
+ * 调用远端 chat。
+ */
+export async function callContactChat<T>(params: {
+  endpoint: string;
+  token: string;
+  body: JsonValue;
+}): Promise<T> {
+  return await postPluginCommand<T>({
+    endpoint: params.endpoint,
+    command: "remotechat",
+    token: params.token,
+    body: params.body,
+    wrapBody: true,
+  });
+}
+
+/**
+ * 调用远端 share。
+ */
+export async function callContactShare<T>(params: {
+  endpoint: string;
+  token: string;
+  body: JsonValue;
+}): Promise<T> {
+  return await postPluginCommand<T>({
+    endpoint: params.endpoint,
+    command: "remoteshare",
+    token: params.token,
+    body: params.body,
+    wrapBody: true,
+  });
+}

package/src/contact/runtime/ShareBundle.ts

@@ -0,0 +1,286 @@
+/**
+ * contact 通用 share 打包与接收。
+ *
+ * 关键点（中文）
+ * - share 不理解 skill，只处理文本、链接、文件和目录。
+ * - receive 不自动安装或执行内容，只把 share 标记为已接收并复制到 received 区。
+ */
+
+import crypto from "node:crypto";
+import fs from "fs-extra";
+import path from "node:path";
+import type { AgentContext } from "@downcity/agent/internal/types/runtime/agent/AgentContext.js";
+import type {
+  ContactInboxShareFileInput,
+  ContactInboxShareMeta,
+  ContactReceiveShareRequest,
+  ContactShareFileManifest,
+  ContactShareItem,
+  ContactSharePayload,
+  SaveContactInboxShareInput,
+} from "@/contact/types/ContactShare.js";
+import { createContactId } from "./Token.js";
+import {
+  getInboxShareFilesRoot,
+  markContactInboxShareReceived,
+  readContactInboxSharePayload,
+} from "./InboxStore.js";
+import { getContactReceivedSharePath } from "./Paths.js";
+
+function hashContent(content: Buffer): string {
+  return crypto.createHash("sha256").update(content).digest("hex");
+}
+
+function assertSafeRelativePath(relativePath: string): string {
+  const value = String(relativePath || "").trim();
+  if (!value) throw new Error("relativePath is required");
+  if (path.isAbsolute(value)) throw new Error(`Absolute path is not allowed: ${value}`);
+  const normalized = path.normalize(value);
+  if (normalized.startsWith("..") || normalized.includes(`${path.sep}..${path.sep}`)) {
+    throw new Error(`Unsafe relative path: ${value}`);
+  }
+  return normalized;
+}
+
+function createItemRoot(itemPath: string): string {
+  const base = path.basename(itemPath).replace(/[^a-zA-Z0-9._-]+/g, "_") || "item";
+  return `${createContactId("item")}_${base}`;
+}
+
+async function collectPathFiles(params: {
+  /**
+   * 要分享的文件或目录。
+   */
+  sourcePath: string;
+  /**
+   * share files 下的 item 根目录。
+   */
+  itemRoot: string;
+}): Promise<{
+  /**
+   * share 附带文件内容。
+   */
+  files: ContactInboxShareFileInput[];
+  /**
+   * item manifest 文件列表。
+   */
+  manifest: ContactShareFileManifest[];
+  /**
+   * item 类型。
+   */
+  itemType: "file" | "directory";
+}> {
+  const stat = await fs.stat(params.sourcePath);
+  const files: ContactInboxShareFileInput[] = [];
+  const manifest: ContactShareFileManifest[] = [];
+
+  const pushFile = async (absPath: string, relativePath: string): Promise<void> => {
+    const safeRelative = assertSafeRelativePath(relativePath);
+    const content = await fs.readFile(absPath);
+    files.push({
+      relativePath: path.join(params.itemRoot, safeRelative),
+      content: content.toString("base64"),
+      encoding: "base64",
+    });
+    manifest.push({
+      path: safeRelative,
+      sha256: hashContent(content),
+    });
+  };
+
+  if (stat.isFile()) {
+    await pushFile(params.sourcePath, path.basename(params.sourcePath));
+    return { files, manifest, itemType: "file" };
+  }
+
+  if (!stat.isDirectory()) {
+    throw new Error(`Only files and directories can be shared: ${params.sourcePath}`);
+  }
+
+  const walk = async (dir: string): Promise<void> => {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const absPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(absPath);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      await pushFile(absPath, path.relative(params.sourcePath, absPath));
+    }
+  };
+  await walk(params.sourcePath);
+  return { files, manifest, itemType: "directory" };
+}
+
+function normalizeLinks(input: string[] | undefined): string[] {
+  const values = Array.isArray(input) ? input : [];
+  return values
+    .map((item) => String(item || "").trim())
+    .filter(Boolean);
+}
+
+/**
+ * 创建通用 share。
+ */
+export async function createShareInput(params: {
+  /**
+   * 当前 agent context。
+   */
+  context: AgentContext;
+  /**
+   * 发送方 contact id。
+   */
+  fromContactId: string;
+  /**
+   * 发送方 agent 名称。
+   */
+  fromAgentName: string;
+  /**
+   * 分享文本。
+   */
+  text?: string;
+  /**
+   * 分享链接。
+   */
+  links?: string[];
+  /**
+   * 分享文件或目录路径。
+   */
+  paths?: string[];
+}): Promise<SaveContactInboxShareInput> {
+  const items: ContactShareItem[] = [];
+  const files: ContactInboxShareFileInput[] = [];
+
+  const text = String(params.text || "").trim();
+  if (text) {
+    items.push({
+      id: createContactId("item"),
+      type: "text",
+      title: "Text",
+      text,
+    });
+  }
+
+  for (const link of normalizeLinks(params.links)) {
+    items.push({
+      id: createContactId("item"),
+      type: "link",
+      title: link,
+      url: link,
+    });
+  }
+
+  for (const rawPath of Array.isArray(params.paths) ? params.paths : []) {
+    const sourcePath = path.resolve(params.context.rootPath, String(rawPath || "").trim());
+    const itemRoot = createItemRoot(sourcePath);
+    const collected = await collectPathFiles({
+      sourcePath,
+      itemRoot,
+    });
+    files.push(...collected.files);
+    items.push({
+      id: createContactId("item"),
+      type: collected.itemType,
+      title: path.basename(sourcePath),
+      root: itemRoot,
+      files: collected.manifest,
+    });
+  }
+
+  if (items.length === 0) {
+    throw new Error("Share requires at least one text, link, file, or directory item");
+  }
+
+  const sizeBytes =
+    files.reduce((sum, file) => {
+      if (file.encoding === "base64") return sum + Buffer.byteLength(file.content, "base64");
+      return sum + Buffer.byteLength(file.content, "utf-8");
+    }, 0) +
+    Buffer.byteLength(text, "utf-8") +
+    normalizeLinks(params.links).reduce(
+      (sum, link) => sum + Buffer.byteLength(link, "utf-8"),
+      0,
+    );
+  const title = items
+    .slice(0, 3)
+    .map((item) => item.title)
+    .join(", ");
+  const meta: ContactInboxShareMeta = {
+    id: createContactId("share"),
+    fromContactId: params.fromContactId,
+    fromAgentName: params.fromAgentName,
+    title: title || "Share",
+    status: "pending",
+    receivedAt: Date.now(),
+    sizeBytes,
+    itemCount: items.length,
+  };
+  const payload: ContactSharePayload = {
+    kind: "share",
+    items,
+  };
+
+  return {
+    meta,
+    payload,
+    files,
+  };
+}
+
+/**
+ * 接收通用 share。
+ */
+export async function receiveShare(params: {
+  /**
+   * 项目根目录。
+   */
+  projectRoot: string;
+  /**
+   * share id。
+   */
+  shareId: string;
+}): Promise<{
+  /**
+   * 接收后的 item 数量。
+   */
+  itemCount: number;
+  /**
+   * received 目录。
+   */
+  receivedPath: string;
+}> {
+  const payload = await readContactInboxSharePayload(params.projectRoot, params.shareId);
+  if (!payload) throw new Error(`Share payload not found: ${params.shareId}`);
+  if (payload.kind !== "share") throw new Error(`Unsupported share payload: ${payload.kind}`);
+
+  const receivedPath = getContactReceivedSharePath(params.projectRoot, params.shareId);
+  await fs.ensureDir(receivedPath);
+  await fs.writeJson(path.join(receivedPath, "payload.json"), payload, { spaces: 2 });
+
+  const filesRoot = getInboxShareFilesRoot(params.projectRoot, params.shareId);
+  if (await fs.pathExists(filesRoot)) {
+    await fs.copy(filesRoot, path.join(receivedPath, "files"), {
+      overwrite: true,
+    });
+  }
+
+  await markContactInboxShareReceived(params.projectRoot, params.shareId);
+  return {
+    itemCount: payload.items.length,
+    receivedPath,
+  };
+}
+
+/**
+ * 构造远端 receive share 请求。
+ */
+export function createReceiveShareRequest(
+  input: SaveContactInboxShareInput,
+  senderContactId: string,
+): ContactReceiveShareRequest {
+  return {
+    ...input,
+    senderContactId,
+  };
+}

package/src/contact/runtime/SystemProvider.ts

@@ -0,0 +1,15 @@
+/**
+ * contact plugin system prompt 提供器。
+ *
+ * 关键点（中文）
+ * - session system composer 通过静态 provider 清单读取 plugin system。
+ * - contact prompt 在这里统一暴露，避免 plugin 实例和 system 域产生耦合。
+ */
+import { CONTACT_SERVICE_PROMPT } from "@/contact/runtime/ContactPromptAssets.js";
+
+/**
+ * 构建 contact plugin system 文本。
+ */
+export function buildContactPluginSystemText(): string {
+  return CONTACT_SERVICE_PROMPT;
+}

package/src/contact/runtime/Token.ts

@@ -0,0 +1,40 @@
+/**
+ * contact token 工具。
+ *
+ * 关键点（中文）
+ * - contact 之间的远端调用使用随机 token。
+ * - 本地只保存入站 token hash，避免明文泄漏后可被直接冒用。
+ */
+
+import crypto from "node:crypto";
+
+/**
+ * 生成随机 token。
+ */
+export function createContactToken(): string {
+  return crypto.randomBytes(32).toString("base64url");
+}
+
+/**
+ * 计算 token hash。
+ */
+export function hashContactToken(token: string): string {
+  return crypto.createHash("sha256").update(String(token || ""), "utf-8").digest("hex");
+}
+
+/**
+ * 生成短 id。
+ */
+export function createContactId(prefix: string): string {
+  const cleanPrefix = String(prefix || "id").trim().replace(/[^a-zA-Z0-9_-]/g, "_");
+  return `${cleanPrefix}_${crypto.randomBytes(5).toString("hex")}`;
+}
+
+/**
+ * 稳定 slug。
+ */
+export function toContactSlug(input: string): string {
+  const raw = String(input || "").trim().toLowerCase();
+  const slug = raw.replace(/[^a-z0-9._-]+/g, "_").replace(/^_+|_+$/g, "");
+  return slug || createContactId("contact");
+}