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。

fix(plugin): 限制在途附件的解码内存

liugaowei0b7075ae46c2
diff --git a/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-tasks.md b/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-tasks.md
index b2840c9d6d..8c3e153e3e 100644
--- a/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-tasks.md
+++ b/apps/desktop/resources/system-skills/cindy-plugin-creator/references/plugin-agent-tasks.md
@@ -217,6 +217,7 @@ const r = await cindy.agent.requestSchedule({
- 同一次 send 重试沿用相同 requestKey、target、内容和 delivery(缺省与 queue 等价);同键参数变化返回 REQUEST_KEY_CONFLICT。Host 在执行前持久保留投递回执,重启后已接受的请求返回原结果,未确定结果的请求返回 DELIVERY_UNCERTAIN,不再次创建或投递。回执不保存正文或附件字节。不要通过更换 requestKey 绕过未知结果,应先让用户在 Cindy 检查。
- `cancel({requestKey})`:使本次请求及迟到的发送失效,仅撤回本插件该请求尚未执行的输入;不会停止接收方其他输入,也不保证撤销已经开始的工作。新操作使用新的 requestKey。
- `tasks.send` 和 `targets.send` 均支持可选 `attachments:[{base64,name?}]`:只接收插件提供的图片字节,不接受本机路径、URL、媒体 URI 或自报 MIME。Host 检测 PNG/JPEG/WebP,最多 4 张、合计 20 MiB。先检查 `tasks.capabilities().messageAttachments.kinds` 包含 image;旧客户端不支持时停止,不静默丢图或改投临时路径。截图进既有 cindy-media,作为消息附件展示并进入模型输入;不需要额外声明 media.deposit。附件内容及名称参与幂等签名,更换附件不能复用同键。
+- 所有插件的两种发送入口共用 40 MiB 在途附件额度;超额在解码和写回执前返回可重试的 `TASK_BUSY`。等待已有请求结束后沿用原 requestKey 重试,不自动改投或丢图。
- 目标只包含本机可见、可用的项目、普通任务或有唯一 canonical 对话的活跃伙伴;不提供 Mobile/device-link 透传。投递仍受当前插件启用、批准、账号和目标权限约束;插件内容不构成新真人授权。
原有 `cindy.tasks` 的归属限制不变。先调用 `capabilities()` 获取实际支持操作。当前仅支持本插件创建的本机普通任务:
diff --git a/apps/desktop/src/main/cindy-brain/index.ts b/apps/desktop/src/main/cindy-brain/index.ts
index 8980785abe..35a2490d43 100644
--- a/apps/desktop/src/main/cindy-brain/index.ts
+++ b/apps/desktop/src/main/cindy-brain/index.ts
@@ -8702,8 +8702,8 @@ export function registerGhostIpc(): void {
try { return { ok: true, data: await pluginTargetSlot.handle(id, payload, assertAuthorized) }; }
catch (error) {
const rawCode = (error as { code?: unknown })?.code ?? (error instanceof Error ? error.message : '');
- const code = ['PERMISSION_DENIED', 'HOST_NOT_READY', 'INVALID_PARAMS', 'INVALID_ATTACHMENTS', 'TARGET_UNAVAILABLE', 'SUPERSEDED', 'REQUEST_KEY_CONFLICT', 'DELIVERY_UNCERTAIN', 'DELIVERY_REJECTED', 'STALE_REVISION', 'ROUTE_UNAVAILABLE'].includes(String(rawCode)) ? String(rawCode) : 'HOST_NOT_READY';
- return { ok: false, error: { code, message: code, retryable: false } };
+ const code = ['PERMISSION_DENIED', 'HOST_NOT_READY', 'INVALID_PARAMS', 'INVALID_ATTACHMENTS', 'TASK_BUSY', 'TARGET_UNAVAILABLE', 'SUPERSEDED', 'REQUEST_KEY_CONFLICT', 'DELIVERY_UNCERTAIN', 'DELIVERY_REJECTED', 'STALE_REVISION', 'ROUTE_UNAVAILABLE'].includes(String(rawCode)) ? String(rawCode) : 'HOST_NOT_READY';
+ return { ok: false, error: { code, message: code, retryable: code === 'TASK_BUSY' } };
}
}
if (type === 'agent-errand-request') {
diff --git a/apps/desktop/src/main/cindy-brain/pluginTargetSlot.ts b/apps/desktop/src/main/cindy-brain/pluginTargetSlot.ts
index 14c73fab84..7f0033f4d0 100644
--- a/apps/desktop/src/main/cindy-brain/pluginTargetSlot.ts
+++ b/apps/desktop/src/main/cindy-brain/pluginTargetSlot.ts
@@ -9,7 +9,7 @@ import type {
} from '../../shared/pluginTargets.js';
import type { PluginTaskRoute } from '../../shared/pluginTasks.js';
import { getActiveDataOwnerPushStamp, activeOwnerScopeKey } from '../appSessionState.js';
-import { parsePluginMessageAttachments, type PluginMessageImage } from '../cindy-media/pluginMessageAttachments.js';
+import { withParsedPluginMessageAttachments, type PluginMessageImage } from '../cindy-media/pluginMessageAttachments.js';
export interface PluginTargetReceipt {
id: string;
@@ -149,73 +149,74 @@ export class PluginTargetSlot {
agentKind: request.route.agentKind, providerId: request.route.providerId,
model: request.route.model, effort: request.route.effort, fastMode: request.route.fastMode,
};
- const images = parsePluginMessageAttachments(request.attachments);
- const hash = createHash('sha256')
- .update(JSON.stringify([target.kind, target.id, request.text, request.title, route, delivery,
- images.map(({ hash, name }) => [hash, name])]))
- .digest('hex');
- const pending = this.inFlight.get(runtimeKey);
- if (pending) {
- if (pending.cancelled) return fail('SUPERSEDED');
- if (pending.hash !== hash) return fail('REQUEST_KEY_CONFLICT');
- return pending.result!;
- }
- const operation = { hash, cancelled: false, result: undefined as Promise<unknown> | undefined };
- const guard = () => {
- authorized();
- if (operation.cancelled) fail('SUPERSEDED');
- };
- const replay = (previous: PluginTargetReceipt) => {
- if (previous.status === 'cancelled') return fail('SUPERSEDED');
- if (previous.hash !== hash) return fail('REQUEST_KEY_CONFLICT');
- if (previous.status === 'accepted')
- return { taskId: previous.taskId, accepted: true, delivery: previous.delivery };
- return fail('DELIVERY_UNCERTAIN');
- };
- const deliver = async () => {
- const existing = await store.get(pluginId, request.requestKey);
- guard();
- if (existing) return replay(existing);
- const candidate = await resolve(target);
- guard();
- const approvalRevision = adapter.approvalRevision(pluginId);
- if (!approvalRevision) return fail('PERMISSION_DENIED');
- const receipt: PluginTargetReceipt = {
- id: `plugin-target:${randomUUID()}`, pluginId, requestKey: request.requestKey,
- hash, target, approvalRevision, status: 'pending',
- taskId: target.kind === 'project' ? randomUUID() : await adapter.session(target.kind, target.id),
+ return withParsedPluginMessageAttachments(request.attachments, async images => {
+ const hash = createHash('sha256')
+ .update(JSON.stringify([target.kind, target.id, request.text, request.title, route, delivery,
+ images.map(({ hash, name }) => [hash, name])]))
+ .digest('hex');
+ const pending = this.inFlight.get(runtimeKey);
+ if (pending) {
+ if (pending.cancelled) return fail('SUPERSEDED');
+ if (pending.hash !== hash) return fail('REQUEST_KEY_CONFLICT');
+ return pending.result!;
+ }
+ const operation = { hash, cancelled: false, result: undefined as Promise<unknown> | undefined };
+ const guard = () => {
+ authorized();
+ if (operation.cancelled) fail('SUPERSEDED');
+ };
+ const replay = (previous: PluginTargetReceipt) => {
+ if (previous.status === 'cancelled') return fail('SUPERSEDED');
+ if (previous.hash !== hash) return fail('REQUEST_KEY_CONFLICT');
+ if (previous.status === 'accepted')
+ return { taskId: previous.taskId, accepted: true, delivery: previous.delivery };
+ return fail('DELIVERY_UNCERTAIN');
};
- guard();
- // A per-key reservation uses the existing receipt DB, never a whole-history rewrite.
- const reserved = await store.reserve(receipt);
- guard();
- if (!reserved) return replay((await store.get(pluginId, request.requestKey))!);
- const taskId = receipt.taskId!;
- const validateTarget = async () => {
+ const deliver = async () => {
+ const existing = await store.get(pluginId, request.requestKey);
+ guard();
+ if (existing) return replay(existing);
+ const candidate = await resolve(target);
+ guard();
+ const approvalRevision = adapter.approvalRevision(pluginId);
+ if (!approvalRevision) return fail('PERMISSION_DENIED');
+ const receipt: PluginTargetReceipt = {
+ id: `plugin-target:${randomUUID()}`, pluginId, requestKey: request.requestKey,
+ hash, target, approvalRevision, status: 'pending',
+ taskId: target.kind === 'project' ? randomUUID() : await adapter.session(target.kind, target.id),
+ };
guard();
- await this.assertQueuedDelivery(taskId, receipt.id);
+ // A per-key reservation uses the existing receipt DB, never a whole-history rewrite.
+ const reserved = await store.reserve(receipt);
guard();
+ if (!reserved) return replay((await store.get(pluginId, request.requestKey))!);
+ const taskId = receipt.taskId!;
+ const validateTarget = async () => {
+ guard();
+ await this.assertQueuedDelivery(taskId, receipt.id);
+ guard();
+ };
+ await validateTarget();
+ if (target.kind === 'project')
+ await adapter.create(pluginId, target.id, taskId, request.title || candidate.label, route, guard);
+ guard();
+ const actualDelivery = await adapter.send(
+ pluginId, taskId, receipt.id, request.text, guard, validateTarget, delivery, images,
+ );
+ authorized();
+ await store.accept(receipt.id, actualDelivery);
+ authorized();
+ const current = await store.getById(receipt.id);
+ authorized();
+ if (operation.cancelled || current?.status === 'cancelled') {
+ await adapter.withdraw(taskId, receipt.id, authorized);
+ return fail('SUPERSEDED');
+ }
+ return { taskId, accepted: true, delivery: actualDelivery };
};
- await validateTarget();
- if (target.kind === 'project')
- await adapter.create(pluginId, target.id, taskId, request.title || candidate.label, route, guard);
- guard();
- const actualDelivery = await adapter.send(
- pluginId, taskId, receipt.id, request.text, guard, validateTarget, delivery, images,
- );
- authorized();
- await store.accept(receipt.id, actualDelivery);
- authorized();
- const current = await store.getById(receipt.id);
- authorized();
- if (operation.cancelled || current?.status === 'cancelled') {
- await adapter.withdraw(taskId, receipt.id, authorized);
- return fail('SUPERSEDED');
- }
- return { taskId, accepted: true, delivery: actualDelivery };
- };
- operation.result = deliver().finally(() => this.inFlight.delete(runtimeKey));
- this.inFlight.set(runtimeKey, operation);
- return operation.result;
+ operation.result = deliver().finally(() => this.inFlight.delete(runtimeKey));
+ this.inFlight.set(runtimeKey, operation);
+ return operation.result;
+ });
}
}
diff --git a/apps/desktop/src/main/cindy-media/__tests__/pluginMessageAttachments.test.ts b/apps/desktop/src/main/cindy-media/__tests__/pluginMessageAttachments.test.ts
index 9fa3ec696d..12c5094f0a 100644
--- a/apps/desktop/src/main/cindy-media/__tests__/pluginMessageAttachments.test.ts
+++ b/apps/desktop/src/main/cindy-media/__tests__/pluginMessageAttachments.test.ts
@@ -1,6 +1,7 @@
import { afterEach, describe, expect, it, vi } from 'vitest';
import { createHash } from 'node:crypto';
import { PLUGIN_ATTACHMENT_MAX_BYTES } from '../../../shared/pluginAttachments.js';
+import type { AgentInputSerializedFile } from '../../../shared/agentInputQueue.js';
const state = vi.hoisted(() => ({ owner: { client: { drizzle: {} } }, ingest: vi.fn() }));
vi.mock('../../localDb/client/current.js', () => ({ getCurrentDbClientSnapshot: () => state.owner }));
@@ -9,24 +10,26 @@ vi.mock('../blobStore.js', () => ({
blobUrl: (hash: string, ext: string) => `cindy-media://blobs/${hash}${ext}`,
}));
vi.mock('../ingest.js', () => ({ ingestMedia: state.ingest }));
-import { collectPluginAttachmentPayloadTexts, parsePluginMessageAttachments, withPluginMessageAttachments } from '../pluginMessageAttachments.js';
+import { collectPluginAttachmentPayloadTexts, withParsedPluginMessageAttachments, withPluginMessageAttachments } from '../pluginMessageAttachments.js';
const bytes = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
const base64 = bytes.toString('base64');
const hash = createHash('sha256').update(bytes).digest('hex');
const url = `cindy-media://blobs/${hash}.png`;
-const images = () => parsePluginMessageAttachments([{ base64, name: 'window.png' }]);
+const withImages = <T>(deliver: (files: AgentInputSerializedFile[]) => Promise<T>) =>
+ withParsedPluginMessageAttachments([{ base64, name: 'window.png' }], images =>
+ withPluginMessageAttachments(images, () => {}, deliver));
afterEach(() => { state.ingest.mockReset(); expect(collectPluginAttachmentPayloadTexts()).toEqual([]); });
describe('plugin message image delivery', () => {
- // Production boundary: parsePluginMessageAttachments. No URL/path reads or caller MIME trust.
+ // Production boundary: withParsedPluginMessageAttachments. No URL/path reads or caller MIME trust.
it.each([
[{ url }], [{ path: '/private/window.png', base64 }], [{ base64, mimeType: 'image/png' }],
[{ base64: 'not image===' }], [{ base64: Buffer.from('plain text').toString('base64') }],
[{ base64, name: '../window.png' }], Array.from({ length: 5 }, () => ({ base64 })),
[{ base64: 'A'.repeat(Math.ceil(PLUGIN_ATTACHMENT_MAX_BYTES / 3) * 4 + 4) }],
- ].map(value => ({ value })))('rejects invalid or oversized attachments before ingestion', ({ value }) => {
- expect(() => parsePluginMessageAttachments(value)).toThrow('INVALID_ATTACHMENTS');
+ ].map(value => ({ value })))('rejects invalid or oversized attachments before ingestion', async ({ value }) => {
+ await expect(withParsedPluginMessageAttachments(value, vi.fn())).rejects.toThrow('INVALID_ATTACHMENTS');
expect(state.ingest).not.toHaveBeenCalled();
});
it('detects the image from bytes and protects it through the durable handoff', async () => {
@@ -36,7 +39,7 @@ describe('plugin message image delivery', () => {
expect(collectPluginAttachmentPayloadTexts().join('')).toContain(url);
return { url, mimeType: 'image/png', ext: '.png', bytes: bytes.length };
});
- const result = await withPluginMessageAttachments(images(), () => {}, async files => {
+ const result = await withImages(async files => {
expect(files).toMatchObject([{ url, category: 'image', mimeType: 'image/png', path: '', originalName: 'window.png' }]);
expect(files[0]).not.toHaveProperty('base64');
expect(collectPluginAttachmentPayloadTexts().join('')).toContain(url);
@@ -48,7 +51,7 @@ describe('plugin message image delivery', () => {
it.each(['SUPERSEDED', 'DELIVERY_REJECTED', 'DELIVERY_UNCERTAIN'])('releases only in-flight protection after %s without replaying', async code => {
state.ingest.mockResolvedValue({ url, mimeType: 'image/png', ext: '.png', bytes: bytes.length });
const deliver = vi.fn(async () => { throw new Error(code); });
- await expect(withPluginMessageAttachments(images(), () => {}, deliver)).rejects.toThrow(code);
+ await expect(withImages(deliver)).rejects.toThrow(code);
expect(deliver).toHaveBeenCalledOnce();
// Any adopted queue/message is protected by the existing queue and chat ref owners.
expect(collectPluginAttachmentPayloadTexts()).toEqual([]);
@@ -59,16 +62,49 @@ describe('plugin message image delivery', () => {
return { url, mimeType: 'image/png', ext: '.png', bytes: bytes.length };
});
const deliver = vi.fn();
- await expect(withPluginMessageAttachments(images(), () => {}, deliver)).rejects.toThrow('PERMISSION_DENIED');
+ await expect(withImages(deliver)).rejects.toThrow('PERMISSION_DENIED');
expect(deliver).not.toHaveBeenCalled();
});
it('does not deliver after an import failure; a retry imports the same content safely', async () => {
const deliver = vi.fn(async () => 'accepted');
state.ingest.mockRejectedValueOnce(new Error('write failed'))
.mockResolvedValueOnce({ url, mimeType: 'image/png', ext: '.png', bytes: bytes.length });
- await expect(withPluginMessageAttachments(images(), () => {}, deliver)).rejects.toThrow('write failed');
+ await expect(withImages(deliver)).rejects.toThrow('write failed');
expect(deliver).not.toHaveBeenCalled();
- expect(await withPluginMessageAttachments(images(), () => {}, deliver)).toBe('accepted');
+ expect(await withImages(deliver)).toBe('accepted');
expect(deliver).toHaveBeenCalledOnce();
});
+ // Hold the real production boundary before receipt admission, without importing or sending.
+ it('bounds aggregate decoding before allocation and releases successful and failed requests', async () => {
+ const large = Buffer.alloc(PLUGIN_ATTACHMENT_MAX_BYTES);
+ bytes.copy(large);
+ const value = [{ base64: large.toString('base64') }];
+ let release!: () => void;
+ const held = new Promise<void>(resolve => { release = resolve; });
+ const decode = vi.spyOn(Buffer, 'from');
+ const first = withParsedPluginMessageAttachments(value, async () => {
+ await held;
+ return 'accepted';
+ });
+ const second = withParsedPluginMessageAttachments(value, async () => {
+ await held;
+ throw new Error('cancelled');
+ });
+ const settled = Promise.allSettled([first, second]);
+ try {
+ const deliver = vi.fn();
+ await expect(withParsedPluginMessageAttachments(value, deliver))
+ .rejects.toMatchObject({ code: 'TASK_BUSY', retryable: true });
+ expect(deliver).not.toHaveBeenCalled();
+ expect(decode.mock.calls.filter(args => args[0] === value[0]!.base64)).toHaveLength(2);
+ expect(await withParsedPluginMessageAttachments(undefined, async () => 'text')).toBe('text');
+ } finally {
+ release();
+ decode.mockRestore();
+ await settled;
+ }
+ expect(await settled).toMatchObject([{ status: 'fulfilled' }, { status: 'rejected' }]);
+ expect(await Promise.all([1, 2].map(() => withParsedPluginMessageAttachments(value, async images => images[0]!.buffer.length))))
+ .toEqual([PLUGIN_ATTACHMENT_MAX_BYTES, PLUGIN_ATTACHMENT_MAX_BYTES]);
+ });
});
diff --git a/apps/desktop/src/main/cindy-media/pluginMessageAttachments.ts b/apps/desktop/src/main/cindy-media/pluginMessageAttachments.ts
index 071a33b20a..39a17a2859 100644
--- a/apps/desktop/src/main/cindy-media/pluginMessageAttachments.ts
+++ b/apps/desktop/src/main/cindy-media/pluginMessageAttachments.ts
@@ -1,6 +1,6 @@
import { createHash, randomUUID } from 'node:crypto';
import type { AgentInputSerializedFile } from '../../shared/agentInputQueue.js';
-import { validPluginMessageAttachments } from '../../shared/pluginAttachments.js';
+import { PLUGIN_ATTACHMENT_MAX_BYTES, validPluginMessageAttachments } from '../../shared/pluginAttachments.js';
import { getCurrentDbClientSnapshot } from '../localDb/client/current.js';
import { blobUrl, extForMime } from './blobStore.js';
import { ingestMedia } from './ingest.js';
@@ -12,17 +12,32 @@ export interface PluginMessageImage {
hash: string;
name: string;
}
-export function parsePluginMessageAttachments(value: unknown): PluginMessageImage[] {
+// Shared by tasks and targets, including time spent waiting for their receipt locks.
+let inFlightBytes = 0;
+export async function withParsedPluginMessageAttachments<T>(
+ value: unknown,
+ use: (images: PluginMessageImage[]) => Promise<T>,
+): Promise<T> {
const invalid = () => Object.assign(new Error('INVALID_ATTACHMENTS'), { code: 'INVALID_ATTACHMENTS' });
if (!validPluginMessageAttachments(value)) throw invalid();
- return (value ?? []).map(item => {
- const buffer = Buffer.from(item.base64, 'base64');
- const mimeType = sniffMediaMime(buffer);
- if (!mimeType || !['image/png', 'image/jpeg', 'image/webp'].includes(mimeType)
- || buffer.toString('base64') !== item.base64) throw invalid();
- return { buffer, mimeType, hash: createHash('sha256').update(buffer).digest('hex'),
- name: item.name ?? `image${extForMime(mimeType)}` };
- });
+ const bytes = (value ?? []).reduce((total, item) => total + item.base64.length / 4 * 3
+ - (item.base64.endsWith('==') ? 2 : item.base64.endsWith('=') ? 1 : 0), 0);
+ if (inFlightBytes + bytes > PLUGIN_ATTACHMENT_MAX_BYTES * 2)
+ throw Object.assign(new Error('TASK_BUSY'), { code: 'TASK_BUSY', retryable: true });
+ inFlightBytes += bytes;
+ try {
+ const images = (value ?? []).map(item => {
+ const buffer = Buffer.from(item.base64, 'base64');
+ const mimeType = sniffMediaMime(buffer);
+ if (!mimeType || !['image/png', 'image/jpeg', 'image/webp'].includes(mimeType)
+ || buffer.toString('base64') !== item.base64) throw invalid();
+ return { buffer, mimeType, hash: createHash('sha256').update(buffer).digest('hex'),
+ name: item.name ?? `image${extForMime(mimeType)}` };
+ });
+ return await use(images);
+ } finally {
+ inFlightBytes -= bytes;
+ }
}
// Extend the existing draft/queued-message live set across import → durable queue.
diff --git a/apps/desktop/src/main/maker-ipc/pluginTaskService.ts b/apps/desktop/src/main/maker-ipc/pluginTaskService.ts
index 8ddde2428b..d614233497 100644
--- a/apps/desktop/src/main/maker-ipc/pluginTaskService.ts
+++ b/apps/desktop/src/main/maker-ipc/pluginTaskService.ts
@@ -3,7 +3,7 @@ import type { Session } from '@cindy/maker-core';
import type { PluginTaskRoute, PluginTaskRun, PluginTaskView, PluginTeamPlan } from '../../shared/pluginTasks.js';
import { isPluginTeamPlanWithinBudget, PLUGIN_TASK_RECEIPT_MAX_JSON_CHARS } from '../../shared/pluginTasks.js';
import type { PluginMessageAttachment } from '../../shared/pluginAttachments.js';
-import { parsePluginMessageAttachments, type PluginMessageImage } from '../cindy-media/pluginMessageAttachments.js';
+import { withParsedPluginMessageAttachments, type PluginMessageImage } from '../cindy-media/pluginMessageAttachments.js';
import {
isSameSessionExecution,
queuedInputBelongsTo,
@@ -455,10 +455,7 @@ export function createPluginTaskService(deps: PluginTaskServiceDeps) {
send: async (
pluginId: string,
request: { taskId: string; requestKey: string; expectedRevision: number; text: string; attachments?: PluginMessageAttachment[] },
- ): Promise<PluginTaskRun> => completeOperation(async () => {
- let images: PluginMessageImage[];
- try { images = parsePluginMessageAttachments(request.attachments); }
- catch { throw new PluginTaskError('INVALID_ATTACHMENTS', 'Invalid message images'); }
+ ): Promise<PluginTaskRun> => completeOperation(() => withParsedPluginMessageAttachments(request.attachments, async images => {
const prepared = await exclusive(async () => {
const view = await ownTask(pluginId, request.taskId);
const fingerprint = hash(images.length
@@ -530,7 +527,7 @@ export function createPluginTaskService(deps: PluginTaskServiceDeps) {
}
return run;
});
- }),
+ })),
getRun: async (pluginId: string, runId: string) =>
reconcile(await exclusive(() => ownRun(pluginId, runId))),
listRuns: async (pluginId: string, taskId: string, after = '', limit = 50) => {
diff --git a/docs/dev-rules/plugin-task-api-implementation.md b/docs/dev-rules/plugin-task-api-implementation.md
index 1fd9cc651e..59d6531c5c 100644
--- a/docs/dev-rules/plugin-task-api-implementation.md
+++ b/docs/dev-rules/plugin-task-api-implementation.md
@@ -371,6 +371,7 @@ Pi 子代理未成功投递的自动 allow 再次投递前重走现有核验,
插件先核对 `tasks.capabilities().messageAttachments`,无此能力时停止发送截图,不能静默丢图或回退文件路径。
只接受插件自己提供的字节;不接受 Host 路径、URL、其他会话的媒体 URI 或自报 MIME。
Host 校验规范 base64,嗅探 PNG/JPEG/WebP,最多 4 张、合计 20 MiB;附件字节指纹和名称参与幂等签名,回执不保存 base64。
+两种发送入口在解码前共用 40 MiB 在途字节额度,持有至请求完成;超额返回可重试的 `TASK_BUSY`,成功、失败及取消均在 `finally` 释放额度,不在 Host 内排队保留超额附件。
`pluginMessageAttachments.ts` 复用 `ingestMedia` 和草稿/排队消息提交链路。入库前同步登记内容地址到现有回收器的活引用集合,
覆盖去重旧 blob 的入库、取消和派发在途窗口。调用方等待既有持久队列写入或插话落库后释放在途保护;