Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(ios): 伙伴推送显示头像和名字 (#5268)

Chris Zhangac0c2a4a6337
diff --git a/apps/desktop/src/main/__tests__/notificationAvatar.test.ts b/apps/desktop/src/main/__tests__/notificationAvatar.test.ts
new file mode 100644
index 0000000000..ea8eee7955
--- /dev/null
+++ b/apps/desktop/src/main/__tests__/notificationAvatar.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it, vi } from 'vitest';
+import sharp from 'sharp';
+
+const readAvatarFile = vi.hoisted(() => vi.fn());
+vi.mock('node:fs/promises', () => ({ readFile: readAvatarFile }));
+vi.mock('../cindy-media/blobStore', () => ({ resolveSafe: vi.fn(() => ({ absPath: '/managed/avatar.png' })) }));
+import { encodeNotificationAvatar, notificationAvatar } from '../notificationAvatar';
+
+describe('notification avatars', () => {
+ it('carries bundled identities and emoji without a network lookup', async () => {
+ expect(await notificationAvatar('cindy://avatar/preset/cindy')).toEqual({ kind: 'preset', value: 'cindy' });
+ expect(await notificationAvatar('🐸')).toEqual({ kind: 'symbol', value: '🐸' });
+ expect(await notificationAvatar('cindy://avatar/unknown')).toBeUndefined();
+ expect(await notificationAvatar('https://example.com/avatar.jpg')).toBeUndefined();
+ expect(await notificationAvatar('/private/avatar.jpg')).toBeUndefined();
+ });
+
+ it('keeps a reply deliverable when the managed avatar is unavailable', async () => {
+ readAvatarFile.mockRejectedValueOnce(new Error('Missing media'));
+ expect(await notificationAvatar(`cindy-media://blobs/${'a'.repeat(64)}.png`)).toBeUndefined();
+ });
+
+ it('aborts slow avatar reads before they consume the reply preview window', async () => {
+ vi.useFakeTimers();
+ try {
+ readAvatarFile.mockImplementationOnce((_path, { signal }) => new Promise((_resolve, reject) => {
+ signal.addEventListener('abort', () => reject(new Error('Aborted')), { once: true });
+ }));
+ const result = notificationAvatar(`cindy-media://blobs/${'b'.repeat(64)}.png`);
+ await vi.advanceTimersByTimeAsync(150);
+ expect(await result).toBeUndefined();
+ expect(readAvatarFile.mock.lastCall?.[1].signal.aborted).toBe(true);
+ expect(vi.getTimerCount()).toBe(0);
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it('produces a bounded decodable thumbnail for a detailed uploaded portrait', async () => {
+ const pixels = Buffer.alloc(256 * 256 * 3);
+ for (let i = 0; i < pixels.length; i++) pixels[i] = (i * 197 + (i >> 5) * 53) % 256;
+ const input = await sharp(pixels, { raw: { width: 256, height: 256, channels: 3 } }).png().toBuffer();
+ const result = await encodeNotificationAvatar(input, sharp);
+ expect(result?.kind).toBe('jpeg');
+ expect(result!.value.length).toBeLessThanOrEqual(2048);
+ const metadata = await sharp(Buffer.from(result!.value, 'base64')).metadata();
+ expect(metadata.format).toBe('jpeg');
+ expect(metadata.width).toBeLessThanOrEqual(72);
+ expect(metadata.width).toBe(metadata.height);
+ });
+});
diff --git a/apps/desktop/src/main/__tests__/notificationService.test.ts b/apps/desktop/src/main/__tests__/notificationService.test.ts
index 7d5e753c92..0b4da24a71 100644
--- a/apps/desktop/src/main/__tests__/notificationService.test.ts
+++ b/apps/desktop/src/main/__tests__/notificationService.test.ts
@@ -478,11 +478,12 @@ describe('notificationService — channels 分发', () => {
initNotificationService(baseDeps(makeFeishuIm('ou_owner')));
readSessionNotificationPreview.mockImplementation(async (_id, includeReply = true) => ({
teammateName: 'Cindy', teammateBotId: 'bot-1', eventId: 'turn:100:200',
+ teammateAvatar: { kind: 'preset', value: 'cindy' },
...(includeReply ? { reply: { clientId: 'final-2', text: 'Done' } } : {}),
}));
await invokeHandler({ sessionId: 's1', title: 'Cindy', kind: 'done', channels: { desktop: false, feishu: false, mobile: true } });
await flushAsync();
- expect(sendMobileSessionNotify).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 's1', teammateBotId: 'bot-1' }));
+ expect(sendMobileSessionNotify).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 's1', teammateBotId: 'bot-1', teammateAvatar: { kind: 'preset', value: 'cindy' } }));
});
it('routes a teammate approval push to the teammate chat without changing its title or fallback', async () => {
diff --git a/apps/desktop/src/main/__tests__/sessionNotificationPreview.test.ts b/apps/desktop/src/main/__tests__/sessionNotificationPreview.test.ts
index fd324b72ce..1ffaed6857 100644
--- a/apps/desktop/src/main/__tests__/sessionNotificationPreview.test.ts
+++ b/apps/desktop/src/main/__tests__/sessionNotificationPreview.test.ts
@@ -26,17 +26,21 @@ afterEach(() => { clearCurrentDbClient(client); sqlite.close(); });
function add(id: string, role: string, content: string, createdAt: number, meta = {}) {
sqlite.prepare('INSERT INTO messages (id, client_id, session_id, role, content, created_at, agent_meta) VALUES (?, ?, ?, ?, ?, ?, ?)').run(id, id, 'main', role, content, createdAt, JSON.stringify(meta));
}
-it('reads canonical teammate identity and this turn final from the durable transcript', async () => {
+it.each([
+ { avatar: '🤖', expected: { kind: 'symbol', value: '🤖' } },
+ { avatar: 'cindy://avatar/preset/dash', expected: { kind: 'preset', value: 'dash' } },
+])('reads canonical teammate identity ($avatar) and this turn final from the durable transcript', async ({ avatar, expected }) => {
+ drizzle(sqlite).update(botProfiles).set({ avatar }).run();
add('final-2', 'assistant', '**完成**', 150, { turnCompleted: true, assistantPhase: 'final_answer' });
- expect(await readSessionNotificationPreview('main')).toEqual({ teammateName: 'Cindy', teammateBotId: 'bot-1', reply: { clientId: 'final-2', text: '**完成**' }, eventId: 'turn:100:200' });
+ expect(await readSessionNotificationPreview('main')).toEqual({ teammateName: 'Cindy', teammateBotId: 'bot-1', teammateAvatar: expected, reply: { clientId: 'final-2', text: '**完成**' }, eventId: 'turn:100:200' });
});
it('suppresses an old idle event after a new input started', async () => {
drizzle(sqlite).update(sessions).set({ activeTurnStartedAt: 300 }).run();
- expect(await readSessionNotificationPreview('main')).toEqual({ teammateName: 'Cindy', teammateBotId: 'bot-1', suppress: true });
+ expect(await readSessionNotificationPreview('main')).toEqual({ teammateName: 'Cindy', teammateBotId: 'bot-1', teammateAvatar: { kind: 'symbol', value: '🤖' }, suppress: true });
});
it('does not reuse an older final in a tool-only completed turn', async () => {
add('old', 'assistant', 'Old answer', 10, { turnCompleted: true });
- expect(await readSessionNotificationPreview('main')).toEqual({ teammateName: 'Cindy', teammateBotId: 'bot-1', eventId: 'turn:100:200' });
+ expect(await readSessionNotificationPreview('main')).toEqual({ teammateName: 'Cindy', teammateBotId: 'bot-1', teammateAvatar: { kind: 'symbol', value: '🤖' }, reply: undefined, eventId: 'turn:100:200' });
});
it('uses insertion order for a tool and final arriving in the same millisecond', async () => {
add('z-tool', 'tool_result', 'tool output', 150);
diff --git a/apps/desktop/src/main/device-link/__tests__/mobileNotify.test.ts b/apps/desktop/src/main/device-link/__tests__/mobileNotify.test.ts
index 7430d0df4c..93fc2a230d 100644
--- a/apps/desktop/src/main/device-link/__tests__/mobileNotify.test.ts
+++ b/apps/desktop/src/main/device-link/__tests__/mobileNotify.test.ts
@@ -4,6 +4,17 @@ import { NOTIFY_TITLE_MAX_LENGTH, NOTIFY_BODY_MAX_LENGTH, NOTIFY_DEEP_LINK_MAX_L
import { MobileNotifyDeduper, buildBotGroupNotifyPayload, buildSessionNotifyPayload } from '../mobileNotify';
describe('buildSessionNotifyPayload', () => {
+ it('identifies only teammate replies and isolates the same bot on different hosts', () => {
+ const opts = { sessionId: 's1', title: 'Mika', kind: 'done' as const, selfDeviceId: 'd1', fallbackBody: 'Reply', teammateBotId: 'b1', teammateAvatar: { kind: 'symbol' as const, value: '🐸' } };
+ const first = buildSessionNotifyPayload(opts);
+ expect(first.sender?.avatar).toEqual(opts.teammateAvatar);
+ expect(first.sender?.id).toMatch(/^[a-f0-9]{64}$/);
+ expect(buildSessionNotifyPayload({ ...opts, selfDeviceId: 'd2' }).sender?.id).not.toBe(first.sender?.id);
+ expect(buildSessionNotifyPayload({ ...opts, sessionId: 's2' }).sender?.id).toBe(first.sender?.id);
+ expect(buildSessionNotifyPayload({ ...opts, kind: 'needs-reply' }).sender).toBeUndefined();
+ expect(buildSessionNotifyPayload({ ...opts, kind: 'error' }).sender).toBeUndefined();
+ expect(buildSessionNotifyPayload({ ...opts, teammateBotId: undefined }).sender).toBeUndefined();
+ });
const base = {
sessionId: 'session-1234',
title: '修复登录问题',
diff --git a/apps/desktop/src/main/device-link/index.ts b/apps/desktop/src/main/device-link/index.ts
index dc7ab6f129..e21b9bccc2 100644
--- a/apps/desktop/src/main/device-link/index.ts
+++ b/apps/desktop/src/main/device-link/index.ts
@@ -44,6 +44,7 @@ import {
type LinkClosePayload,
type Envelope,
type PushPayload,
+ type NotifySender,
DeviceLinkError,
resolveRemoteInvokeTimeoutMs,
} from '@cindy/device-link';
@@ -1918,6 +1919,7 @@ export function sendMobileSessionNotify(payload: {
eventId?: string;
/** 伙伴主任务的 Bot id;让手机按伙伴聊天打开通知。 */
teammateBotId?: string;
+ teammateAvatar?: NotifySender['avatar'];
/**
* 发起时捕获的 getMobileNotifyGeneration()。调用路径里有 await(取正文/等
* 其它通道)时必传:与当前代次不一致说明期间发生过登出/失去持有权,任务
@@ -1951,6 +1953,7 @@ export function sendMobileSessionNotify(payload: {
fallbackBody: payload.fallbackBody ?? getSessionNotificationBody(payload.kind),
detail: payload.detail,
...(payload.teammateBotId ? { teammateBotId: payload.teammateBotId } : {}),
+ ...(payload.teammateAvatar ? { teammateAvatar: payload.teammateAvatar } : {}),
}),
);
if (sent) {
diff --git a/apps/desktop/src/main/device-link/mobileNotify.ts b/apps/desktop/src/main/device-link/mobileNotify.ts
index 1ff8584996..47667f0a69 100644
--- a/apps/desktop/src/main/device-link/mobileNotify.ts
+++ b/apps/desktop/src/main/device-link/mobileNotify.ts
@@ -6,6 +6,7 @@ import {
NOTIFY_TITLE_MAX_LENGTH,
type NotifyCategory,
type NotifyPayload,
+ type NotifySender,
} from '@cindy/device-link';
/**
@@ -43,6 +44,7 @@ export function buildSessionNotifyPayload(opts: {
* 而不是普通任务视图;参数与名册进入聊天时相同,旧手机同样识别,缺省保持原深链。
*/
teammateBotId?: string;
+ teammateAvatar?: NotifySender['avatar'];
}): NotifyPayload {
const safeTitle = (opts.title.trim() || opts.sessionId.slice(0, 8)).slice(
0,
@@ -54,6 +56,12 @@ export function buildSessionNotifyPayload(opts: {
title: safeTitle,
body: detail || opts.fallbackBody.slice(0, NOTIFY_BODY_MAX_LENGTH),
deepLink: sessionDeepLink(opts.sessionId, opts.selfDeviceId, opts.teammateBotId),
+ ...(opts.kind === 'done' && opts.teammateBotId ? {
+ sender: {
+ id: createHash('sha256').update(`${opts.selfDeviceId}:bot:${opts.teammateBotId}`).digest('hex'),
+ ...(opts.teammateAvatar ? { avatar: opts.teammateAvatar } : {}),
+ },
+ } : {}),
// 同会话的通知在系统层合并(APNs collapse-id / thread-id);混入 srcDeviceId,
// 多台桌面推同名会话时互不顶替。原样拼接不可行:deviceId 可能是 64 位
// machineId,拼出 100+ 字符会被 APNs 的 64 字节 collapse-id 上限截断成
diff --git a/apps/desktop/src/main/localDb/sessionNotificationPreview.ts b/apps/desktop/src/main/localDb/sessionNotificationPreview.ts
index 3a6f0d88d4..032689d123 100644
--- a/apps/desktop/src/main/localDb/sessionNotificationPreview.ts
+++ b/apps/desktop/src/main/localDb/sessionNotificationPreview.ts
@@ -4,11 +4,14 @@ import { botProfiles, botSessionLinks, messages, sessions } from './schema.js';
import { isTopLevelTitleAssistant } from './latestMessageText.logic.js';
import { extractText } from '../sessionTaskSummary.logic.js';
import { selectNotificationReply } from './sessionNotificationPreview.logic.js';
+import { notificationAvatar } from '../notificationAvatar.js';
+import type { NotifySender } from '@cindy/device-link';
export interface SessionNotificationPreview {
teammateName?: string;
/** The canonical Session's Bot, so remote controllers can open it as that teammate. */
teammateBotId?: string;
+ teammateAvatar?: NotifySender['avatar'];
reply?: { clientId: string; text: string };
eventId?: string;
suppress?: boolean;
@@ -20,10 +23,14 @@ export async function readSessionNotificationPreview(sessionId: string, includeR
const rows = await db.select().from(sessions).where(eq(sessions.id, sessionId)).limit(1);
const current = rows[0];
if (!current) return {};
- const profile = current.source === 'bot' ? await db.select({ id: botProfiles.id, name: botProfiles.displayName })
+ const profile = current.source === 'bot' ? await db.select({ id: botProfiles.id, name: botProfiles.displayName, avatar: botProfiles.avatar })
.from(botProfiles).innerJoin(botSessionLinks, eq(botSessionLinks.botId, botProfiles.id))
.where(and(eq(botSessionLinks.sessionId, sessionId), eq(botSessionLinks.role, 'canonical'))).get() : undefined;
- const teammate = profile ? { teammateName: profile.name, teammateBotId: profile.id } : {};
+ const avatar = profile && includeReply ? await notificationAvatar(profile.avatar) : undefined;
+ const teammate = profile ? {
+ teammateName: profile.name, teammateBotId: profile.id,
+ ...(avatar ? { teammateAvatar: avatar } : {}),
+ } : {};
// A delayed idle event may arrive after the next input has already started.
// Do not notify that unfinished turn or reuse a pre-upgrade historical final.
const startedAt = current.activeTurnStartedAt ?? 0;
diff --git a/apps/desktop/src/main/notificationAvatar.ts b/apps/desktop/src/main/notificationAvatar.ts
new file mode 100644
index 0000000000..b2a8b77e5d
--- /dev/null
+++ b/apps/desktop/src/main/notificationAvatar.ts
@@ -0,0 +1,48 @@
+import { readFile } from 'node:fs/promises';
+import sharp from 'sharp';
+import { NOTIFY_AVATAR_JPEG_MAX_LENGTH, type NotifySender } from '@cindy/device-link';
+import { isManagedBotAvatarUrl, isSingleBotAvatarGrapheme, BOT_AVATAR_MAX_BYTES } from '../shared/botAvatarValue';
+import { resolveSafe } from './cindy-media/blobStore';
+
+/** No public avatar upload, remote URL, extra credential or persistent thumbnail cache. */
+export async function notificationAvatar(value: string): Promise<NotifySender['avatar']> {
+ const preset = /^cindy:\/\/avatar\/preset\/(cindy|dash|lizi)$/.exec(value.toLowerCase())?.[1];
+ if (preset) return { kind: 'preset', value: preset };
+ if (value.length <= 32 && isSingleBotAvatarGrapheme(value)) return { kind: 'symbol', value };
+ if (!isManagedBotAvatarUrl(value)) return undefined;
+ const controller = new AbortController();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ try {
+ return await Promise.race([
+ (async () => {
+ const bytes = await readFile(resolveSafe(value).absPath, { signal: controller.signal });
+ if (controller.signal.aborted || bytes.length > BOT_AVATAR_MAX_BYTES) return undefined;
+ return encodeNotificationAvatar(bytes, sharp, controller.signal);
+ })(),
+ // Never spend the transcript's entire preview deadline on optional artwork.
+ new Promise<undefined>((resolve) => {
+ timer = setTimeout(() => { controller.abort(); resolve(undefined); }, 150);
+ }),
+ ]);
+ } catch {
+ // Identity enrichment must never suppress an otherwise deliverable reply.
+ return undefined;
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+export async function encodeNotificationAvatar(
+ bytes: Buffer,
+ sharp: typeof import('sharp').default,
+ signal?: AbortSignal,
+): Promise<NotifySender['avatar']> {
+ for (const [size, quality] of [[72, 65], [56, 50], [40, 35]]) {
+ if (signal?.aborted) return undefined;
+ const jpeg = await sharp(bytes, { limitInputPixels: 16_777_216 })
+ .rotate().resize(size, size, { fit: 'cover' }).jpeg({ quality }).toBuffer();
+ const value = jpeg.toString('base64');
+ if (value.length <= NOTIFY_AVATAR_JPEG_MAX_LENGTH) return { kind: 'jpeg', value };
+ }
+ return undefined;
+}
diff --git a/apps/desktop/src/main/notificationService.ts b/apps/desktop/src/main/notificationService.ts
index a9688e9c98..9d888db692 100644
--- a/apps/desktop/src/main/notificationService.ts
+++ b/apps/desktop/src/main/notificationService.ts
@@ -314,6 +314,7 @@ export function initNotificationService(deps: NotificationServiceDeps): void {
sessionId, title: notificationTitle, kind, generation, ...(detail ? { detail } : {}),
...(fallbackBody ? { fallbackBody } : {}), ...(mobileEventId ? { eventId: mobileEventId } : {}),
...(mobileTeammateBotId ? { teammateBotId: mobileTeammateBotId } : {}),
+ ...(preview?.teammateAvatar ? { teammateAvatar: preview.teammateAvatar } : {}),
});
if (kind === 'done' && accepted) {
notifiedReplies.set(mobileKey, eventId ? { eventId } : { fallbackSentAt: Date.now() });
diff --git a/apps/mobile/app.json b/apps/mobile/app.json
index 46a678f6b5..4258fb7319 100644
--- a/apps/mobile/app.json
+++ b/apps/mobile/app.json
@@ -91,6 +91,7 @@
"expo-router",
"expo-apple-authentication",
"expo-notifications",
+ "./plugins/with-communication-notifications",
"expo-secure-store",
"expo-web-browser",
[
diff --git a/apps/mobile/fingerprint.config.cjs b/apps/mobile/fingerprint.config.cjs
index 608ed85f6d..dfe515b246 100644
--- a/apps/mobile/fingerprint.config.cjs
+++ b/apps/mobile/fingerprint.config.cjs
@@ -52,6 +52,16 @@ module.exports = {
reasons: ["native message menu assets"],
}))
.concat([
+ {
+ type: "dir",
+ filePath: "plugins/communication-notifications",
+ reasons: ["notification service extension native source"],
+ },
+ ...[
+ "../desktop/src/renderer/assets/bot-presets/cindy.png",
+ "../desktop/resources/legacy-teammate-avatars/dash.png",
+ "../desktop/resources/legacy-teammate-avatars/lizi.png",
+ ].map((filePath) => ({ type: "file", filePath, reasons: ["notification sender portraits"] })),
{
type: "dir",
filePath: "../../packages/remote-credentials-native/Sources",
diff --git a/apps/mobile/plugins/communication-notifications/NotificationService.swift b/apps/mobile/plugins/communication-notifications/NotificationService.swift
new file mode 100644
index 0000000000..d107c96b3a
--- /dev/null
+++ b/apps/mobile/plugins/communication-notifications/NotificationService.swift
@@ -0,0 +1,104 @@
+import Intents
+import UIKit
+import UserNotifications
+
+/// Enrich only teammate replies. No network or access to the app's account storage.
+final class NotificationService: UNNotificationServiceExtension {
+ private let completionLock = NSLock()
+ private var handler: ((UNNotificationContent) -> Void)?
+ private var original: UNNotificationContent?
+
+ override func didReceive(
+ _ request: UNNotificationRequest,
+ withContentHandler contentHandler: @escaping (UNNotificationContent) -> Void
+ ) {
+ completionLock.lock()
+ handler = contentHandler
+ original = request.content
+ completionLock.unlock()
+
+ let content = request.content
+ guard content.userInfo["category"] as? String == "session-done",
+ let senderData = content.userInfo["sender"] as? [String: Any],
+ let id = senderData["id"] as? String, !id.isEmpty, id.utf8.count <= 128,
+ !content.title.isEmpty, !content.threadIdentifier.isEmpty else {
+ finish(content)
+ return
+ }
+ let sender = INPerson(
+ personHandle: INPersonHandle(value: id, type: .unknown),
+ nameComponents: nil,
+ displayName: content.title,
+ image: Self.avatar(senderData["avatar"], name: content.title),
+ contactIdentifier: nil,
+ customIdentifier: id
+ )
+ let intent = INSendMessageIntent(
+ recipients: nil,
+ outgoingMessageType: .outgoingMessageText,
+ content: content.body,
+ speakableGroupName: nil,
+ conversationIdentifier: content.threadIdentifier,
+ serviceName: nil,
+ sender: sender,
+ attachments: nil
+ )
+ let interaction = INInteraction(intent: intent, response: nil)
+ interaction.direction = .incoming
+ interaction.donate { [weak self] error in
+ guard let self else { return }
+ guard error == nil else { self.finish(content); return }
+ do {
+ self.finish(try content.updating(from: intent))
+ } catch {
+ self.finish(content)
+ }
+ }
+ }
+
+ override func serviceExtensionTimeWillExpire() {
+ completionLock.lock()
+ let fallback = original
+ completionLock.unlock()
+ if let fallback { finish(fallback) }
+ }
+
+ /// Donation can finish concurrently with expiry. Deliver exactly once in either case.
+ private func finish(_ content: UNNotificationContent) {
+ completionLock.lock()
+ let callback = handler
+ handler = nil
+ original = nil
+ completionLock.unlock()
+ callback?(content)
+ }
+
+ static func avatar(_ input: Any?, name: String) -> INImage? {
+ let avatar = input as? [String: String]
+ let value = avatar?["value"] ?? ""
+ if avatar?["kind"] == "jpeg", value.utf8.count <= 2048,
+ let data = Data(base64Encoded: value),
+ let image = UIImage(data: data), image.size.width <= 128, image.size.height <= 128 {
+ return INImage(imageData: data)
+ }
+ if avatar?["kind"] == "preset", ["cindy", "dash", "lizi"].contains(value),
+ let image = UIImage(named: "teammate-" + value), let data = image.pngData() {
+ return INImage(imageData: data)
+ }
+ let symbol = avatar?["kind"] == "symbol" && value.count == 1 && value.utf16.count <= 32
+ ? value : String(name.prefix(1)).uppercased()
+ let format = UIGraphicsImageRendererFormat()
+ format.scale = 1
+ let image = UIGraphicsImageRenderer(size: CGSize(width: 80, height: 80), format: format).image { context in
+ UIColor.systemGray5.setFill()
+ context.fill(CGRect(x: 0, y: 0, width: 80, height: 80))
+ let text = symbol as NSString
+ let attributes: [NSAttributedString.Key: Any] = [
+ .font: UIFont.systemFont(ofSize: 44), .foregroundColor: UIColor.label,
+ ]
+ let size = text.size(withAttributes: attributes)
+ text.draw(at: CGPoint(x: (80 - size.width) / 2, y: (80 - size.height) / 2), withAttributes: attributes)
+ }
+ return image.pngData().map { INImage(imageData: $0) }
+ }
+}
diff --git a/apps/mobile/plugins/with-communication-notifications.js b/apps/mobile/plugins/with-communication-notifications.js
new file mode 100644
index 0000000000..223e4458fd
--- /dev/null
+++ b/apps/mobile/plugins/with-communication-notifications.js
@@ -0,0 +1,99 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const plist = require('@expo/plist');
+const { withEntitlementsPlist, withInfoPlist, withXcodeProject } = require('@expo/config-plugins');
+
+const TARGET = 'CindyNotificationService';
+const ENTITLEMENT = 'com.apple.developer.usernotifications.communication';
+
+function extensionInfo() {
+ return {
+ CFBundleDisplayName: 'Cindy',
+ CFBundleIdentifier: '$(PRODUCT_BUNDLE_IDENTIFIER)',
+ CFBundleExecutable: '$(EXECUTABLE_NAME)',
+ CFBundleName: '$(PRODUCT_NAME)',
+ CFBundlePackageType: 'XPC!',
+ CFBundleShortVersionString: '$(MARKETING_VERSION)',
+ CFBundleVersion: '$(CURRENT_PROJECT_VERSION)',
+ NSExtension: {
+ NSExtensionPointIdentifier: 'com.apple.usernotifications.service',
+ NSExtensionPrincipalClass: '$(PRODUCT_MODULE_NAME).NotificationService',
+ },
+ NSUserActivityTypes: ['INSendMessageIntent'],
+ };
+}
+
+function configureProject(project, config, platformRoot, projectRoot) {
+ const bundleId = `${config.ios.bundleIdentifier}.${TARGET}`;
+ const directory = path.join(platformRoot, TARGET);
+ fs.mkdirSync(directory, { recursive: true });
+ fs.copyFileSync(path.join(__dirname, 'communication-notifications/NotificationService.swift'), path.join(directory, 'NotificationService.swift'));
+ fs.writeFileSync(path.join(directory, 'Info.plist'), plist.default.build(extensionInfo()));
+ fs.writeFileSync(path.join(directory, `${TARGET}.entitlements`), plist.default.build({ [ENTITLEMENT]: true }));
+ const portraits = {
+ cindy: '../desktop/src/renderer/assets/bot-presets/cindy.png',
+ dash: '../desktop/resources/legacy-teammate-avatars/dash.png',
+ lizi: '../desktop/resources/legacy-teammate-avatars/lizi.png',
+ };
+ for (const [name, file] of Object.entries(portraits)) {
+ fs.copyFileSync(path.resolve(projectRoot, file), path.join(directory, `teammate-${name}.png`));
+ }
+ let target = Object.entries(project.pbxNativeTargetSection())
+ .find(([key, value]) => !key.endsWith('_comment') && value.name?.replaceAll('"', '') === TARGET);
+ if (!target) {
+ const added = project.addTarget(TARGET, 'app_extension', TARGET, bundleId);
+ target = [added.uuid, added.pbxNativeTarget];
+ project.addBuildPhase([`${TARGET}/NotificationService.swift`], 'PBXSourcesBuildPhase', 'Sources', added.uuid);
+ project.addBuildPhase([], 'PBXFrameworksBuildPhase', 'Frameworks', added.uuid);
+ project.addBuildPhase(Object.keys(portraits).map(name => `${TARGET}/teammate-${name}.png`), 'PBXResourcesBuildPhase', 'Resources', added.uuid);
+ }
+ const [, nativeTarget] = target;
+ const configurations = project.pbxXCConfigurationList()[nativeTarget.buildConfigurationList].buildConfigurations;
+ for (const item of configurations) {
+ const settings = project.pbxXCBuildConfigurationSection()[item.value].buildSettings;
+ Object.assign(settings, {
+ PRODUCT_BUNDLE_IDENTIFIER: `"${bundleId}"`,
+ INFOPLIST_FILE: `"${TARGET}/Info.plist"`,
+ CODE_SIGN_ENTITLEMENTS: `"${TARGET}/${TARGET}.entitlements"`,
+ CODE_SIGN_STYLE: 'Automatic',
+ SWIFT_VERSION: '5.0',
+ IPHONEOS_DEPLOYMENT_TARGET: '15.0',
+ TARGETED_DEVICE_FAMILY: '"1,2"',
+ APPLICATION_EXTENSION_API_ONLY: 'YES',
+ CURRENT_PROJECT_VERSION: `"${config.ios.buildNumber ?? '1'}"`,
+ MARKETING_VERSION: `"${config.version ?? '1.0'}"`,
+ GENERATE_INFOPLIST_FILE: 'NO',
+ ...(config.ios.appleTeamId ? { DEVELOPMENT_TEAM: config.ios.appleTeamId } : {}),
+ });
+ }
+ return project;
+}
+
+module.exports = function withCommunicationNotifications(config) {
+ config = withEntitlementsPlist(config, mod => {
+ mod.modResults[ENTITLEMENT] = true;
+ return mod;
+ });
+ config = withInfoPlist(config, mod => {
+ mod.modResults.NSUserActivityTypes = [...new Set([...(mod.modResults.NSUserActivityTypes ?? []), 'INSendMessageIntent'])];
+ return mod;
+ });
+ // EAS needs extension credentials before prebuild creates the native target.
+ const experimental = config.extra?.eas?.build?.experimental ?? {};
+ config.extra = { ...config.extra, eas: { ...config.extra?.eas, build: {
+ ...config.extra?.eas?.build,
+ experimental: { ...experimental, ios: {
+ ...experimental.ios,
+ appExtensions: [
+ ...(experimental.ios?.appExtensions ?? []).filter(item => item.targetName !== TARGET),
+ { targetName: TARGET, bundleIdentifier: `${config.ios.bundleIdentifier}.${TARGET}`, entitlements: { [ENTITLEMENT]: true } },
+ ],
+ } },
+ } } };
+ return withXcodeProject(config, mod => {
+ configureProject(mod.modResults, mod, mod.modRequest.platformProjectRoot, mod.modRequest.projectRoot);
+ return mod;
+ });
+};
+module.exports.configureProject = configureProject;
+module.exports.extensionInfo = extensionInfo;
diff --git a/apps/mobile/src/__tests__/communicationNotificationsPlugin.test.ts b/apps/mobile/src/__tests__/communicationNotificationsPlugin.test.ts
new file mode 100644
index 0000000000..8c6ccfbd74
--- /dev/null
+++ b/apps/mobile/src/__tests__/communicationNotificationsPlugin.test.ts
@@ -0,0 +1,59 @@
+import { createRequire } from 'node:module';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+
+const require = createRequire(import.meta.url);
+const xcode = require('xcode');
+const plist = require('@expo/plist').default;
+const plugin = require('../../plugins/with-communication-notifications');
+const roots: string[] = [];
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }); });
+
+// A minimal real node-xcode project, not mocks of the mutation API.
+function project() {
+ const result = xcode.project('unused.pbxproj');
+ result.hash = { project: { rootObject: 'ROOT', objects: {
+ PBXProject: { ROOT: { isa: 'PBXProject', targets: [{ value: 'APP', comment: 'App' }], mainGroup: 'GROUP', attributes: {} } },
+ PBXNativeTarget: { APP: { isa: 'PBXNativeTarget', name: 'App', buildPhases: [], dependencies: [], buildConfigurationList: 'CONFIG' } },
+ PBXGroup: { GROUP: { isa: 'PBXGroup', children: [], sourceTree: '"<group>"' }, PRODUCTS: { isa: 'PBXGroup', name: 'Products', children: [], sourceTree: '"<group>"' } },
+ PBXFileReference: {}, PBXBuildFile: {}, PBXTargetDependency: {}, PBXContainerItemProxy: {},
+ XCConfigurationList: { CONFIG: { buildConfigurations: [{ value: 'DEBUG', comment: 'Debug' }] } },
+ XCBuildConfiguration: { DEBUG: { isa: 'XCBuildConfiguration', name: 'Debug', buildSettings: {} } },
+ } } };
+ return result;
+}
+
+describe('communication notification extension', () => {
+ it.each(['com.xd.cindy', 'com.xd.cindycn', 'org.example.selfhost'])('embeds one extension with the actual %s identity', (bundleIdentifier) => {
+ const root = mkdtempSync(path.join(tmpdir(), 'cindy-notification-plugin-'));
+ roots.push(root);
+ const pbx = project();
+ const config = { name: 'Cindy', slug: 'cindy', version: '2.3.4', ios: { bundleIdentifier, buildNumber: '123', appleTeamId: 'TESTTEAM' } };
+ const mobile = path.resolve(import.meta.dirname, '../..');
+ plugin.configureProject(pbx, config, root, mobile);
+ plugin.configureProject(pbx, config, root, mobile);
+ const targets = Object.values(pbx.pbxNativeTargetSection()).filter((item: any) => item?.isa === 'PBXNativeTarget') as any[];
+ expect(targets).toHaveLength(2);
+ const extension = targets.find(item => item.name === '"CindyNotificationService"');
+ expect(extension.buildPhases).toHaveLength(3);
+ expect(targets[0].dependencies).toHaveLength(1);
+ const configs = pbx.pbxXCConfigurationList()[extension.buildConfigurationList].buildConfigurations;
+ for (const entry of configs) {
+ const settings = pbx.pbxXCBuildConfigurationSection()[entry.value].buildSettings;
+ expect(settings.PRODUCT_BUNDLE_IDENTIFIER).toBe(`"${bundleIdentifier}.CindyNotificationService"`);
+ expect(settings.CURRENT_PROJECT_VERSION).toBe('"123"');
+ expect(settings.DEVELOPMENT_TEAM).toBe('TESTTEAM');
+ expect(settings.APPLICATION_EXTENSION_API_ONLY).toBe('YES');
+ }
+ const info = plist.parse(readFileSync(path.join(root, 'CindyNotificationService/Info.plist'), 'utf8'));
+ expect(info.NSExtension.NSExtensionPointIdentifier).toBe('com.apple.usernotifications.service');
+ expect(readFileSync(path.join(root, 'CindyNotificationService/teammate-cindy.png')).length).toBeGreaterThan(0);
+ const configured = plugin(config);
+ expect(configured.extra.eas.build.experimental.ios.appExtensions).toEqual([{
+ targetName: 'CindyNotificationService', bundleIdentifier: `${bundleIdentifier}.CindyNotificationService`,
+ entitlements: { 'com.apple.developer.usernotifications.communication': true },
+ }]);
+ });
+});
diff --git a/docs/dev-rules/mobile-development.md b/docs/dev-rules/mobile-development.md
index dbe9c43159..70d0e01c9f 100644
--- a/docs/dev-rules/mobile-development.md
+++ b/docs/dev-rules/mobile-development.md
@@ -158,6 +158,16 @@ pnpm --filter mobile test:smoke
## 原生配置与 runtime fingerprint(冷更边界)
+### 伙伴通信通知
+
+`plugins/with-communication-notifications.js` 为当前 bundle identity 生成
+`CindyNotificationService` 扩展,启用 Communication Notifications,并向 EAS 登记扩展签名。
+扩展仅消费伙伴回复的可选 `sender` 数据;保留正文、深链和系统隐私设置,任何处理失败或
+系统超时都回退原通知,且只交付一次。头像不发起网络请求、不读取用户账号存储。
+Swift 源码和打包头像显式进入 fingerprint。首次发布需要原生新包和重新生成的签名配置;
+服务端须先支持可选发送者透传和 `aps.mutable-content = 1`,未升级双方保持普通推送。
+这不是 OTA 可独立交付的功能,仍受下述冷更审核门约束。
+
Mobile 用 `runtimeVersion.policy: "fingerprint"`:OTA 热更只在**指纹一致**的装机上生效,
指纹一旦变化就必须**冷更出包**(新商店包 / 自建重装),存量装机拿不到该次热更。
diff --git a/docs/product-rules/cindy-bots-runtime.md b/docs/product-rules/cindy-bots-runtime.md
index fc07085609..ab29cf6cc5 100644
--- a/docs/product-rules/cindy-bots-runtime.md
+++ b/docs/product-rules/cindy-bots-runtime.md
@@ -431,6 +431,11 @@ Session 任务遵守同一套机制与呈现契约:
- 伙伴私聊的结构化入口不触发通知;接收伙伴随后产出的正常回复才有提醒价值。
- 点击伙伴任务的通知必须回到伙伴自己的主任务或历史任务路由,不能把隐藏的 `source=bot`
Session 丢进普通任务列表。
+- iOS 的伙伴正常回复使用系统通信通知:伙伴名字、头像与回复摘要,应用角标由系统绘制。
+ 普通任务、报错和待处理事项保留原通知语义。头像仅携带有界缩略图、内置头像标识或
+ 单个字符,不上传公开头像地址;缺失头像回退名字首字,扩展失败仍交付原通知。
+ 此展示依赖服务端透传发送者和 `mutable-content`、以及包含通知扩展的新版 iOS 安装包;
+ 旧服务端或旧安装包继续显示原通知,不因客户端单侧升级停止推送。
## 7. 实现红线
diff --git a/docs/teammate-communication-notifications.md b/docs/teammate-communication-notifications.md
new file mode 100644
index 0000000000..42dcada3db
--- /dev/null
+++ b/docs/teammate-communication-notifications.md
@@ -0,0 +1,69 @@
+# Teammate communication notifications
+
+Incoming teammate replies carry the teammate's name and avatar in iOS communication
+notifications. The OS supplies the Cindy app badge, layout, light/dark styling and
+notification-preview privacy behavior. Ordinary task events keep their existing semantics.
+
+## Wire contract and server prerequisite
+
+The client adds optional `NotifyPayload.sender` to `session-done` only:
+
+```ts
+sender?: {
+ id: string; // 64 hex characters, SHA-256 of device id + Bot id
+ avatar?: {
+ kind: 'jpeg' | 'symbol' | 'preset';
+ value: string;
+ };
+};
+```
+
+The existing `title` supplies the sender name. The existing `collapseId` supplies the
+conversation identifier, and `deepLink` retains teammate chat routing. Thumbnail generation
+reads only the profile's managed avatar; it has a 150 ms budget and creates no persistent
+cache or public URL. Presets are `cindy`, `dash`, and `lizi`; symbols are one grapheme with
+at most 32 UTF-16 code units. JPEG base64 is at most 2048 characters and generated at
+72×72 or smaller. No avatar value is interpreted as a URL or path on the phone.
+
+The independently maintained server requires these coordinated changes before this feature
+can appear on devices:
+
+1. Extend its local `packages/device-link-protocol` with the same optional sender shape.
+2. In `device-link-server/src/device-link/notify.ts`, validate and retain the sender on
+ `session-done`. Require the 64-character hex identity; whitelist avatar kinds and presets,
+ bound symbols and base64, and ignore malformed optional enrichment while preserving the
+ valid original notification. Never accept arbitrary URLs or local file paths.
+3. In `services/pushSender.ts`, copy a valid sender into APNs custom data and set
+ `aps['mutable-content'] = 1`. Keep alert, sound, category, deepLink, collapse and thread id.
+4. Measure the final serialized APNs body in UTF-8 against 4096 bytes. If enrichment exceeds
+ the budget, remove the avatar first, then sender and mutable-content if necessary, keeping
+ the original message deliverable. Include maximum-length CJK/emoji and JSON-escaping cases
+ in the server's existing notify and pushSender tests.
+
+The current server strips unknown fields and does not set mutable-content. A client-only
+change therefore continues delivering ordinary notifications but cannot activate the new
+appearance. Server support is a deployment prerequisite, not evidence supplied by client
+type checks or a native compile.
+
+## Native delivery and compatibility
+
+`with-communication-notifications` generates a notification service extension for the
+resolved app bundle identifier and records it for EAS signing. The extension donates an
+incoming `INSendMessageIntent`, then updates the original notification content. Donation or
+update errors and extension expiry deliver the original notification exactly once. No
+contacts permission, app-account credentials or network avatar fetch is needed.
+
+Deploy the compatible server first, then the desktop producer and a new signed mobile
+installation containing the extension. Old desktops send ordinary payloads; old servers
+discard the optional sender; old mobile installations display the original alert.
+No database migration or mandatory coordinated upgrade is required for existing delivery.
+
+The native source, plugin configuration and bundled avatar assets change the shared Expo
+fingerprint; both platform hashes must be checked when preparing the native release.
+Do not publish this as an OTA-only feature or fake compatibility with an older runtime.
+Before merge, obtain the repository's explicit cold-release review; before claiming user
+delivery, verify a real APNs reply on a signed iPhone installation, including locked/unlocked
+preview settings and tapping through to the teammate chat. Simulator compilation alone
+does not verify notification-center rendering.
+
+Apple reference: [Implementing communication notifications](https://developer.apple.com/documentation/usernotifications/implementing-communication-notifications).
diff --git a/packages/device-link-protocol/src/protocol.ts b/packages/device-link-protocol/src/protocol.ts
index be7ca85d2c..e402d1e9f1 100644
--- a/packages/device-link-protocol/src/protocol.ts
+++ b/packages/device-link-protocol/src/protocol.ts
@@ -145,6 +145,14 @@ export const NOTIFY_TITLE_MAX_LENGTH = 120;
export const NOTIFY_BODY_MAX_LENGTH = 240;
export const NOTIFY_DEEP_LINK_MAX_LENGTH = 512;
export const NOTIFY_COLLAPSE_ID_MAX_LENGTH = 128;
+/** Small offline thumbnail; relay must still enforce APNs' total 4096-byte budget. */
+export const NOTIFY_AVATAR_JPEG_MAX_LENGTH = 2048;
+
+export interface NotifySender {
+ /** Device-scoped opaque Bot identity. Display name is the notification title. */
+ id: string;
+ avatar?: { kind: 'jpeg' | 'symbol' | 'preset'; value: string };
+}
/**
* notify 帧 payload(client→server;server 消费,不转发)。
@@ -169,6 +177,8 @@ export interface NotifyPayload {
collapseId: string;
/** 只推给指定设备;缺省 = 本账号全部已注册推送 token 的设备(不含发送方) */
targetDeviceId?: string;
+ /** Incoming teammate reply only. Older relays ignore this optional enrichment. */
+ sender?: NotifySender;
}
/** 设备识别用的轻量硬件 / 系统信息。所有字段 best-effort,可缺省。 */
diff --git a/packages/device-link/src/protocol.ts b/packages/device-link/src/protocol.ts
index 63a0455ed4..8a0fde130c 100644
--- a/packages/device-link/src/protocol.ts
+++ b/packages/device-link/src/protocol.ts
@@ -7,6 +7,7 @@
import {
MAX_FRAME_BYTES,
NOTIFY_BODY_MAX_LENGTH,
+ NOTIFY_AVATAR_JPEG_MAX_LENGTH,
NOTIFY_COLLAPSE_ID_MAX_LENGTH,
NOTIFY_DEEP_LINK_MAX_LENGTH,
NOTIFY_TITLE_MAX_LENGTH,
@@ -19,6 +20,7 @@ import {
type HelloPayload,
type NotifyCategory,
type NotifyPayload,
+ type NotifySender,
type PresenceSetPayload,
type PresenceSnapshot,
type RelayErrorCode,
@@ -32,6 +34,7 @@ export type { SharedTaskPeer } from './sharedTaskPeer.js';
export {
MAX_FRAME_BYTES,
NOTIFY_BODY_MAX_LENGTH,
+ NOTIFY_AVATAR_JPEG_MAX_LENGTH,
NOTIFY_COLLAPSE_ID_MAX_LENGTH,
NOTIFY_DEEP_LINK_MAX_LENGTH,
NOTIFY_TITLE_MAX_LENGTH,
@@ -46,6 +49,7 @@ export type {
HelloPayload,
NotifyCategory,
NotifyPayload,
+ NotifySender,
PresenceSetPayload,
PresenceSnapshot,
RelayErrorCode,