@downcity/plugins 1.0.254 → 1.0.280

package/src/contact/runtime/ContactStore.ts

@@ -147,7 +147,7 @@ export function normalizeContactEndpoint(endpoint: string): string {
  * 保存 contact。
  */
 export async function saveContact(
-  project_root: string,
+  data_path: string,
   contact: AgentContact,
 ): Promise<AgentContact> {
   const normalized: AgentContact = {
@@ -171,11 +171,11 @@ export async function saveContact(
   if (normalized.reachability !== "outbound" && !normalized.inboundTokenHash) {
     throw new Error("contact inbound token hash is required for inbound contacts");
   }
-  await fs.ensureDir(getContactDirectoryPath(project_root, normalized.id));
-  await fs.writeJson(getContactJsonPath(project_root, normalized.id), normalized, {
+  await fs.ensureDir(getContactDirectoryPath(data_path, normalized.id));
+  await fs.writeJson(getContactJsonPath(data_path, normalized.id), normalized, {
     spaces: 2,
   });
-  await fs.ensureFile(getContactMessagesPath(project_root, normalized.id));
+  await fs.ensureFile(getContactMessagesPath(data_path, normalized.id));
   return normalized;
 }
 
@@ -183,10 +183,10 @@ export async function saveContact(
  * 读取 contact。
  */
 export async function readContact(
-  project_root: string,
+  data_path: string,
   contactId: string,
 ): Promise<AgentContact | null> {
-  const filePath = getContactJsonPath(project_root, contactId);
+  const filePath = getContactJsonPath(data_path, contactId);
   if (!(await fs.pathExists(filePath))) return null;
   const raw = await fs.readJson(filePath).catch(() => null);
   // 关键点（中文）：读取时归一化可恢复字段，避免一次局部写入让已收到的 contact 在列表中消失。
@@ -196,14 +196,14 @@ export async function readContact(
 /**
  * 列出全部 contact。
  */
-export async function listContacts(project_root: string): Promise<AgentContact[]> {
-  const root = getContactsRootPath(project_root);
+export async function listContacts(data_path: string): Promise<AgentContact[]> {
+  const root = getContactsRootPath(data_path);
   if (!(await fs.pathExists(root))) return [];
   const entries = await fs.readdir(root, { withFileTypes: true });
   const contacts: AgentContact[] = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const contact = await readContact(project_root, entry.name);
+    const contact = await readContact(data_path, entry.name);
     if (contact) contacts.push(contact);
   }
   return contacts.sort((a, b) => a.name.localeCompare(b.name));
@@ -213,12 +213,12 @@ export async function listContacts(project_root: string): Promise<AgentContact[]
  * 按 id/name 查找 contact。
  */
 export async function findContact(
-  project_root: string,
+  data_path: string,
   query: string,
 ): Promise<AgentContact | null> {
   const value = String(query || "").trim();
   if (!value) return null;
-  const contacts = await listContacts(project_root);
+  const contacts = await listContacts(data_path);
   const lower = value.toLowerCase();
   return (
     contacts.find((item) => item.id.toLowerCase() === lower) ||
@@ -232,11 +232,11 @@ export async function findContact(
  * 根据入站 token 查找 contact。
  */
 export async function findContactByInboundToken(
-  project_root: string,
+  data_path: string,
   token: string,
 ): Promise<AgentContact | null> {
   const token_hash = hashContactToken(token);
-  const contacts = await listContacts(project_root);
+  const contacts = await listContacts(data_path);
   return contacts.find((item) => item.inboundTokenHash === token_hash) || null;
 }
 
@@ -244,13 +244,13 @@ export async function findContactByInboundToken(
  * 更新 contact 最近在线时间。
  */
 export async function touchContactSeen(
-  project_root: string,
+  data_path: string,
   contactId: string,
   seenAt: number = Date.now(),
 ): Promise<AgentContact | null> {
-  const contact = await readContact(project_root, contactId);
+  const contact = await readContact(data_path, contactId);
   if (!contact) return null;
-  return await saveContact(project_root, {
+  return await saveContact(data_path, {
     ...contact,
     lastSeenAt: seenAt,
   });
@@ -260,11 +260,11 @@ export async function touchContactSeen(
  * 追加 contact chat 消息。
  */
 export async function appendContactMessage(
-  project_root: string,
+  data_path: string,
   contactId: string,
   message: ContactChatMessage,
 ): Promise<void> {
-  const filePath = getContactMessagesPath(project_root, contactId);
+  const filePath = getContactMessagesPath(data_path, contactId);
   await fs.ensureDir(path.dirname(filePath));
   await fs.appendFile(filePath, `${JSON.stringify(message)}\n`, "utf-8");
 }
@@ -273,10 +273,10 @@ export async function appendContactMessage(
  * 读取 contact chat 历史。
  */
 export async function readContactMessages(
-  project_root: string,
+  data_path: string,
   contactId: string,
 ): Promise<ContactChatMessage[]> {
-  const filePath = getContactMessagesPath(project_root, contactId);
+  const filePath = getContactMessagesPath(data_path, contactId);
   if (!(await fs.pathExists(filePath))) return [];
   const text = await fs.readFile(filePath, "utf-8");
   const out: ContactChatMessage[] = [];

package/src/contact/runtime/EndpointNotice.ts

@@ -60,7 +60,7 @@ export function buildContactLinkNotes(params: {
   if (reachability === "loopback") {
     return [
       "This link endpoint is local-only. Only an agent on the same machine can approve it; a server agent cannot approve a link generated by this local agent.",
-      "Start city from a reachable environment before generating a new link; downcity start automatically writes the public host used by contact links when it can detect one.",
+      "Start City from a reachable environment before generating a new link; `city on` writes the public host used by contact links when it can detect one.",
     ];
   }
   if (reachability === "private") {
@@ -118,7 +118,7 @@ export function buildContactApproveNotes(params: {
     );
   } else {
     notes.push(
-      "This contact is outbound-only from this side: this agent can call the peer, but the peer cannot call back unless this agent was started with a reachable address that downcity start can provide to contact.",
+      "This contact is outbound-only from this side: this agent can call the peer, but the peer cannot call back unless City is running with a reachable address.",
     );
   }
   return notes;

package/src/contact/runtime/InboxStore.ts

@@ -52,11 +52,11 @@ function isMeta(input: unknown): input is ContactInboxShareMeta {
  * 保存 inbox share。
  */
 export async function saveContactInboxShare(
-  project_root: string,
+  data_path: string,
   input: SaveContactInboxShareInput,
 ): Promise<ContactInboxShareMeta> {
-  const inboxRoot = getContactInboxRootPath(project_root);
-  const sharePath = getContactInboxSharePath(project_root, input.meta.id);
+  const inboxRoot = getContactInboxRootPath(data_path);
+  const sharePath = getContactInboxSharePath(data_path, input.meta.id);
   const tempRoot = path.join(path.dirname(inboxRoot), ".inbox-tmp");
   const tempPath = path.join(
     tempRoot,
@@ -103,10 +103,10 @@ export async function saveContactInboxShare(
  * 读取 inbox share meta。
  */
 export async function readContactInboxShareMeta(
-  project_root: string,
+  data_path: string,
   shareId: string,
 ): Promise<ContactInboxShareMeta | null> {
-  const filePath = getContactInboxShareMetaPath(project_root, shareId);
+  const filePath = getContactInboxShareMetaPath(data_path, shareId);
   if (!(await fs.pathExists(filePath))) return null;
   const raw = await fs.readJson(filePath).catch(() => null);
   return isMeta(raw) ? raw : null;
@@ -116,10 +116,10 @@ export async function readContactInboxShareMeta(
  * 读取 inbox share payload。
  */
 export async function readContactInboxSharePayload(
-  project_root: string,
+  data_path: string,
   shareId: string,
 ): Promise<ContactInboxSharePayload | null> {
-  const filePath = getContactInboxSharePayloadPath(project_root, shareId);
+  const filePath = getContactInboxSharePayloadPath(data_path, shareId);
   if (!(await fs.pathExists(filePath))) return null;
   const raw = await fs.readJson(filePath).catch(() => null);
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
@@ -131,15 +131,15 @@ export async function readContactInboxSharePayload(
  * 列出 inbox share。
  */
 export async function listContactInboxShares(
-  project_root: string,
+  data_path: string,
 ): Promise<ContactInboxShareMeta[]> {
-  const root = getContactInboxRootPath(project_root);
+  const root = getContactInboxRootPath(data_path);
   if (!(await fs.pathExists(root))) return [];
   const entries = await fs.readdir(root, { withFileTypes: true });
   const shares: ContactInboxShareMeta[] = [];
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
-    const meta = await readContactInboxShareMeta(project_root, entry.name);
+    const meta = await readContactInboxShareMeta(data_path, entry.name);
     if (meta) shares.push(meta);
   }
   return shares.sort((a, b) => b.receivedAt - a.receivedAt);
@@ -149,22 +149,22 @@ export async function listContactInboxShares(
  * 标记 share 已接收，并复制轻量状态到 received。
  */
 export async function markContactInboxShareReceived(
-  project_root: string,
+  data_path: string,
   shareId: string,
 ): Promise<ContactInboxShareMeta> {
-  const meta = await readContactInboxShareMeta(project_root, shareId);
+  const meta = await readContactInboxShareMeta(data_path, shareId);
   if (!meta) throw new Error(`Share not found: ${shareId}`);
   const next: ContactInboxShareMeta = {
     ...meta,
     status: "received",
   };
-  const receivedPath = getContactReceivedSharePath(project_root, shareId);
+  const receivedPath = getContactReceivedSharePath(data_path, shareId);
   await fs.ensureDir(receivedPath);
   await fs.writeJson(path.join(receivedPath, "meta.json"), next, {
     spaces: 2,
   });
   // received 区先完整写入，最后再更新 inbox meta，避免列表状态提前变成 received。
-  await fs.writeJson(getContactInboxShareMetaPath(project_root, shareId), next, {
+  await fs.writeJson(getContactInboxShareMetaPath(data_path, shareId), next, {
     spaces: 2,
   });
   return next;
@@ -173,6 +173,6 @@ export async function markContactInboxShareReceived(
 /**
  * 读取 share 文件根目录。
  */
-export function getInboxShareFilesRoot(project_root: string, shareId: string): string {
-  return getContactInboxShareFilesPath(project_root, shareId);
+export function getInboxShareFilesRoot(data_path: string, shareId: string): string {
+  return getContactInboxShareFilesPath(data_path, shareId);
 }

package/src/contact/runtime/LinkApproval.ts

@@ -99,31 +99,31 @@ function readCallbackCandidate(
 }
 
 async function findApprovedContact(params: {
-  project_root: string;
+  data_path: string;
   agentName: string;
 }) {
   const stable = await readContact(
-    params.project_root,
+    params.data_path,
     createStableContactId(params.agentName),
   );
   if (stable) return stable;
-  const contacts = await listContacts(params.project_root);
+  const contacts = await listContacts(params.data_path);
   const lower = params.agentName.trim().toLowerCase();
   return contacts.find((item) => item.name.toLowerCase() === lower) || null;
 }
 
 async function saveApprovedInboundContact(params: {
-  project_root: string;
+  data_path: string;
   agentName: string;
   tokenForOwner: string;
   nowMs: number;
 }) {
   const existing = await findApprovedContact({
-    project_root: params.project_root,
+    data_path: params.data_path,
     agentName: params.agentName,
   });
   const hasOutboundSide = Boolean(existing?.endpoint && existing?.outboundToken);
-  await saveContact(params.project_root, {
+  await saveContact(params.data_path, {
     id: existing?.id || createStableContactId(params.agentName),
     name: existing?.name || params.agentName,
     endpoint: existing?.endpoint || null,
@@ -143,7 +143,7 @@ export async function approveContactLinkRequest(
   input: ApproveContactLinkRequestInput,
 ): Promise<ContactApproveLinkResponse> {
   const nowMs = input.nowMs ?? Date.now();
-  const link = await readContactLinkRecord(input.project_root, input.request.linkId);
+  const link = await readContactLinkRecord(input.data_path, input.request.linkId);
   if (!link) {
     return failure({
       ownerAgentName: input.ownerAgentName,
@@ -185,10 +185,10 @@ export async function approveContactLinkRequest(
           tokenForRequester: callbackCandidate.token,
           callbackReason: input.request.callbackReason || link.callbackReason || null,
         };
-        await saveContactLinkRecord(input.project_root, nextLink);
+        await saveContactLinkRecord(input.data_path, nextLink);
       }
       await saveApprovedInboundContact({
-        project_root: input.project_root,
+        data_path: input.data_path,
         agentName: input.request.agentName,
         tokenForOwner: link.tokenForOwner,
         nowMs,
@@ -219,9 +219,9 @@ export async function approveContactLinkRequest(
   };
 
   // 先消费 link，再派生 contact；重试时以 link 记录为来源修复 contact，避免孤儿 trusted contact。
-  await saveContactLinkRecord(input.project_root, approvedLink);
+  await saveContactLinkRecord(input.data_path, approvedLink);
   await saveApprovedInboundContact({
-    project_root: input.project_root,
+    data_path: input.data_path,
     agentName: input.request.agentName,
     tokenForOwner,
     nowMs,
@@ -242,7 +242,7 @@ export async function confirmContactLinkRequest(
   input: ConfirmContactLinkRequestInput,
 ): Promise<ContactConfirmResponse> {
   const nowMs = input.nowMs ?? Date.now();
-  const link = await readContactLinkRecord(input.project_root, input.request.linkId);
+  const link = await readContactLinkRecord(input.data_path, input.request.linkId);
   if (!link) {
     return confirmFailure({
       ownerAgentName: input.ownerAgentName,
@@ -309,7 +309,7 @@ export async function confirmContactLinkRequest(
     });
   }
   const contact = await findApprovedContact({
-    project_root: input.project_root,
+    data_path: input.data_path,
     agentName: input.request.agentName,
   });
   if (!contact || contact.status !== "trusted") {
@@ -332,7 +332,7 @@ export async function confirmContactLinkRequest(
   ) {
     if (!link.confirmedAt) {
       // contact 已经完成双向升级时，重试 confirm 需要补齐 link 状态，避免最终状态分裂。
-      await saveContactLinkRecord(input.project_root, {
+      await saveContactLinkRecord(input.data_path, {
         ...link,
         approvedEndpoint: endpoint,
         tokenForRequester: token,
@@ -363,7 +363,7 @@ export async function confirmContactLinkRequest(
     };
   }
 
-  await saveContact(input.project_root, {
+  await saveContact(input.data_path, {
     ...contact,
     endpoint,
     reachability: "bidirectional",
@@ -371,7 +371,7 @@ export async function confirmContactLinkRequest(
     inboundTokenHash: contact.inboundTokenHash,
     lastSeenAt: nowMs,
   });
-  await saveContactLinkRecord(input.project_root, {
+  await saveContactLinkRecord(input.data_path, {
     ...link,
     approvedEndpoint: endpoint,
     tokenForRequester: token,

package/src/contact/runtime/LinkStore.ts

@@ -27,11 +27,11 @@ function isLinkRecord(input: unknown): input is ContactLinkRecord {
  * 保存 link 记录。
  */
 export async function saveContactLinkRecord(
-  project_root: string,
+  data_path: string,
   record: ContactLinkRecord,
 ): Promise<void> {
-  await fs.ensureDir(getContactLinksRootPath(project_root));
-  await fs.writeJson(getContactLinkPath(project_root, record.id), record, {
+  await fs.ensureDir(getContactLinksRootPath(data_path));
+  await fs.writeJson(getContactLinkPath(data_path, record.id), record, {
     spaces: 2,
   });
 }
@@ -40,10 +40,10 @@ export async function saveContactLinkRecord(
  * 读取 link 记录。
  */
 export async function readContactLinkRecord(
-  project_root: string,
+  data_path: string,
   linkId: string,
 ): Promise<ContactLinkRecord | null> {
-  const filePath = getContactLinkPath(project_root, linkId);
+  const filePath = getContactLinkPath(data_path, linkId);
   if (!(await fs.pathExists(filePath))) return null;
   const raw = await fs.readJson(filePath).catch(() => null);
   return isLinkRecord(raw) ? raw : null;

package/src/contact/runtime/Paths.ts

@@ -2,7 +2,7 @@
  * contact plugin runtime 路径规则。
  *
  * 关键点（中文）
- * - 所有 contact 运行时状态都收敛在 `.downcity/contact`。
+ * - 所有 contact 运行时状态都收敛在 Agent private runtime directory 私有 `contact` 目录。
  * - 每个 contact 一个目录；每条 inbox share 一个目录。
  */
 
@@ -22,118 +22,118 @@ function cleanSegment(input: string, label: string): string {
 /**
  * contact 根目录。
  */
-export function getContactRootPath(project_root: string): string {
-  return path.join(project_root, ".downcity", "contact");
+export function getContactRootPath(data_path: string): string {
+  return path.join(data_path, "contact");
 }
 
 /**
  * contacts 根目录。
  */
-export function getContactsRootPath(project_root: string): string {
-  return path.join(getContactRootPath(project_root), "contacts");
+export function getContactsRootPath(data_path: string): string {
+  return path.join(getContactRootPath(data_path), "contacts");
 }
 
 /**
  * 单个 contact 目录。
  */
 export function getContactDirectoryPath(
-  project_root: string,
+  data_path: string,
   contactId: string,
 ): string {
-  return path.join(getContactsRootPath(project_root), cleanSegment(contactId, "contactId"));
+  return path.join(getContactsRootPath(data_path), cleanSegment(contactId, "contactId"));
 }
 
 /**
  * 单个 contact 元信息文件。
  */
-export function getContactJsonPath(project_root: string, contactId: string): string {
-  return path.join(getContactDirectoryPath(project_root, contactId), "contact.json");
+export function getContactJsonPath(data_path: string, contactId: string): string {
+  return path.join(getContactDirectoryPath(data_path, contactId), "contact.json");
 }
 
 /**
  * 单个 contact 的长期对话历史文件。
  */
 export function getContactMessagesPath(
-  project_root: string,
+  data_path: string,
   contactId: string,
 ): string {
-  return path.join(getContactDirectoryPath(project_root, contactId), "messages.jsonl");
+  return path.join(getContactDirectoryPath(data_path, contactId), "messages.jsonl");
 }
 
 /**
  * link 根目录。
  */
-export function getContactLinksRootPath(project_root: string): string {
-  return path.join(getContactRootPath(project_root), "links");
+export function getContactLinksRootPath(data_path: string): string {
+  return path.join(getContactRootPath(data_path), "links");
 }
 
 /**
  * 单个 link 记录文件。
  */
-export function getContactLinkPath(project_root: string, linkId: string): string {
-  return path.join(getContactLinksRootPath(project_root), `${cleanSegment(linkId, "linkId")}.json`);
+export function getContactLinkPath(data_path: string, linkId: string): string {
+  return path.join(getContactLinksRootPath(data_path), `${cleanSegment(linkId, "linkId")}.json`);
 }
 
 /**
  * inbox 根目录。
  */
-export function getContactInboxRootPath(project_root: string): string {
-  return path.join(getContactRootPath(project_root), "inbox");
+export function getContactInboxRootPath(data_path: string): string {
+  return path.join(getContactRootPath(data_path), "inbox");
 }
 
 /**
  * 单个 inbox share 目录。
  */
 export function getContactInboxSharePath(
-  project_root: string,
+  data_path: string,
   shareId: string,
 ): string {
-  return path.join(getContactInboxRootPath(project_root), cleanSegment(shareId, "shareId"));
+  return path.join(getContactInboxRootPath(data_path), cleanSegment(shareId, "shareId"));
 }
 
 /**
  * 单个 inbox share 元信息文件。
  */
 export function getContactInboxShareMetaPath(
-  project_root: string,
+  data_path: string,
   shareId: string,
 ): string {
-  return path.join(getContactInboxSharePath(project_root, shareId), "meta.json");
+  return path.join(getContactInboxSharePath(data_path, shareId), "meta.json");
 }
 
 /**
  * 单个 inbox share payload 文件。
  */
 export function getContactInboxSharePayloadPath(
-  project_root: string,
+  data_path: string,
   shareId: string,
 ): string {
-  return path.join(getContactInboxSharePath(project_root, shareId), "payload.json");
+  return path.join(getContactInboxSharePath(data_path, shareId), "payload.json");
 }
 
 /**
  * 单个 inbox share 文件根目录。
  */
 export function getContactInboxShareFilesPath(
-  project_root: string,
+  data_path: string,
   shareId: string,
 ): string {
-  return path.join(getContactInboxSharePath(project_root, shareId), "files");
+  return path.join(getContactInboxSharePath(data_path, shareId), "files");
 }
 
 /**
  * received 根目录。
  */
-export function getContactReceivedRootPath(project_root: string): string {
-  return path.join(getContactRootPath(project_root), "received");
+export function getContactReceivedRootPath(data_path: string): string {
+  return path.join(getContactRootPath(data_path), "received");
 }
 
 /**
  * 单个 received share 目录。
  */
 export function getContactReceivedSharePath(
-  project_root: string,
+  data_path: string,
   shareId: string,
 ): string {
-  return path.join(getContactReceivedRootPath(project_root), cleanSegment(shareId, "shareId"));
+  return path.join(getContactReceivedRootPath(data_path), cleanSegment(shareId, "shareId"));
 }

package/src/contact/runtime/ShareBundle.ts

@@ -235,7 +235,7 @@ export async function receiveShare(params: {
   /**
    * 项目根目录。
    */
-  project_root: string;
+  data_path: string;
   /**
    * share id。
    */
@@ -250,22 +250,22 @@ export async function receiveShare(params: {
    */
   receivedPath: string;
 }> {
-  const payload = await readContactInboxSharePayload(params.project_root, params.shareId);
+  const payload = await readContactInboxSharePayload(params.data_path, 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.project_root, params.shareId);
+  const receivedPath = getContactReceivedSharePath(params.data_path, params.shareId);
   await fs.ensureDir(receivedPath);
   await fs.writeJson(path.join(receivedPath, "payload.json"), payload, { spaces: 2 });
 
-  const filesRoot = getInboxShareFilesRoot(params.project_root, params.shareId);
+  const filesRoot = getInboxShareFilesRoot(params.data_path, params.shareId);
   if (await fs.pathExists(filesRoot)) {
     await fs.copy(filesRoot, path.join(receivedPath, "files"), {
       overwrite: true,
     });
   }
 
-  await markContactInboxShareReceived(params.project_root, params.shareId);
+  await markContactInboxShareReceived(params.data_path, params.shareId);
   return {
     itemCount: payload.items.length,
     receivedPath,

package/src/contact/types/ContactApproval.ts

@@ -43,7 +43,7 @@ export interface ApproveContactLinkRequestInput {
   /**
    * 当前 agent 项目根目录，用于读取 link 记录并保存 contact。
    */
-  project_root: string;
+  data_path: string;
   /**
    * 当前 agent 名称，也就是 link 所属方名称。
    */
@@ -121,7 +121,7 @@ export interface ConfirmContactLinkRequestInput {
   /**
    * 当前 agent 项目根目录，用于读取 link 记录并更新 contact。
    */
-  project_root: string;
+  data_path: string;
   /**
    * 当前 agent 名称，也就是 link 所属方名称。
    */