✨ Support image and file attachments on wishes

Wishes can now carry screenshots, designs, logs and documents: upload,
drag-and-drop, or paste into the goal/criteria boxes. The files are stored
as attachment records, written into the executor's workspace under a
Git-ignored directory, and pointed out to the agent in its prompt. People
fetch them back one at a time (images inline, everything else downloads)
with nosniff and a sandbox CSP.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
eust-w 2026-11-09 14:17:52 +08:00
parent 4e0ac6bdfd
commit 3a2296e9d7
15 changed files with 702 additions and 14 deletions

View File

@ -24,6 +24,10 @@ import {
type Project,
type Wish,
type Run,
type Attachment,
base64Size,
MAX_ATTACHMENT_BYTES,
MAX_ATTACHMENTS_TOTAL_BYTES,
type Evidence,
type Release,
type Environment,
@ -412,8 +416,13 @@ export class ControlPlane {
: 'This project offers no choice of model',
400,
);
const { model: chosenModel, ...runInput } = data;
const { model: chosenModel, attachments: files = [], ...runInput } = data;
const model = chosenModel ?? defaultProjectModel(models);
const sizes = files.map(file => base64Size(file.data));
if (sizes.some(size => size > MAX_ATTACHMENT_BYTES))
throw new DomainError('ATTACHMENT_TOO_LARGE', 'Each attachment may be at most 5 MB', 413);
if (sizes.reduce((sum, size) => sum + size, 0) > MAX_ATTACHMENTS_TOTAL_BYTES)
throw new DomainError('ATTACHMENTS_TOO_LARGE', 'Attachments may be at most 10 MB together', 413);
return idempotent(tx, `wish:${actor.userId}:${projectId}:${key ?? ''}`, { projectId, ...data }, async () => {
const tenant = await tx.tenant();
const runs = await tx.list<Run>('run');
@ -460,12 +469,31 @@ export class ControlPlane {
...(frontendOnly !== undefined ? { frontendOnly } : {}),
...(extras.revertOf ? { revertOf: extras.revertOf } : {}),
} as Run;
const attachments: Attachment[] = files.map((file, index) => ({
...record(actor.tenantId),
projectId,
runId: run.id,
name: file.name,
mediaType: file.mediaType,
size: sizes[index]!,
data: file.data,
}));
if (attachments.length)
run.attachments = attachments.map(({ id, name, mediaType, size }) => ({ id, name, mediaType, size }));
const blocked = startBlocker(provider, project);
if (blocked) setWaiting(run, blocked.reason, blocked.detail);
else run.pendingStartId = randomUUID();
await tx.put('wish', wish);
await tx.put('run', run);
await tx.event(run.id, 'wish.submitted', '愿望已受理,验收标准已记录。', { revision: 1 });
for (const attachment of attachments) await tx.put('attachment', attachment);
await tx.event(
run.id,
'wish.submitted',
attachments.length
? `愿望已受理,验收标准和 ${attachments.length} 个附件已记录。`
: '愿望已受理,验收标准已记录。',
{ revision: 1 },
);
if (run.pendingStartId) await tx.enqueue('run.start', { runId: run.id, revision: 1 }, run.pendingStartId);
else await tx.event(run.id, 'run.waiting', run.waitingDetail!, { reason: run.waitingReason });
return { wish_id: wish.id, run_id: run.id, status_url: `/runs/${run.id}` };
@ -498,6 +526,16 @@ export class ControlPlane {
return run;
});
}
/** One file attached to a run's wish, for someone who may see the run. */
async attachment(actor: Actor, runId: string, attachmentId: string) {
return this.store.read(actor.tenantId, async tx => {
const run = await must<Run>(tx, 'run', runId);
await projectAccess(tx, actor, run.projectId);
const attachment = await tx.get<Attachment>('attachment', attachmentId);
if (!attachment || attachment.runId !== run.id) throw new DomainError('NOT_FOUND', 'Attachment not found', 404);
return attachment;
});
}
async events(actor: Actor, id: string, after = 0) {
return this.store.read(actor.tenantId, async tx => {
const run = await must<Run>(tx, 'run', id);
@ -1416,6 +1454,16 @@ export class ControlPlane {
connectionId: connection?.id ?? null,
bundleConfig: await resolveBundle(tx, run.bundleVersion),
skills: await projectSkills(tx, run.projectId),
// Only the executor writes the files into its workspace; people fetch them one at a time.
attachments:
actor.kind === 'worker' && run.attachments?.length
? await Promise.all(
run.attachments.map(async info => {
const file = await must<Attachment>(tx, 'attachment', info.id);
return { id: file.id, name: file.name, mediaType: file.mediaType, data: file.data };
}),
)
: [],
executorSettings: await runExecutorSettings(tx, run.provider),
delivery: {
release,

View File

@ -26,6 +26,7 @@ import {
projectModelsInput,
commandList,
gitBranchName,
inlineImageTypes,
wishRulesInput,
type Actor,
type Run,
@ -439,6 +440,25 @@ export class ApiController {
@Patch('runs/:id/budget') async updateBudget(@Req() r: AuthRequest, @Param('id') id: string, @Body() b: unknown) {
return ok(await this.s.control.updateBudget(r.actor, id, b, key(r)));
}
@Get('runs/:id/attachments/:attachmentId') async attachment(
@Req() r: AuthRequest,
@Res() res: Response,
@Param('id') id: string,
@Param('attachmentId') attachmentId: string,
) {
const file = await this.s.control.attachment(r.actor, id, attachmentId);
// Images show inline; anything else downloads, so uploaded HTML or SVG never runs here.
const inline = inlineImageTypes.includes(file.mediaType);
res
.type(inline ? file.mediaType : 'application/octet-stream')
.setHeader(
'Content-Disposition',
`${inline ? 'inline' : 'attachment'}; filename*=UTF-8''${encodeURIComponent(file.name)}`,
)
.setHeader('X-Content-Type-Options', 'nosniff')
.setHeader('Content-Security-Policy', "default-src 'none'; sandbox")
.send(Buffer.from(file.data, 'base64'));
}
@Get('runs/:id/events') async events(@Req() r: AuthRequest, @Param('id') id: string, @Query('after') after?: string) {
return ok(await this.s.control.events(r.actor, id, Math.max(0, Number(after) || 0)));
}

View File

@ -43,16 +43,20 @@ export async function bootstrap() {
})
class AppModule {}
const app = await NestFactory.create(AppModule, { logger: ['error', 'warn', 'log'], bodyParser: false });
// Bodies are parsed before authentication, so only the checkpoint upload may be large.
// Bodies are parsed before authentication, so only checkpoint uploads and wishes with files may be large.
const checkpointBody = express.json({ limit: '16mb' }),
proxyBody = express.json({ limit: '2mb' }),
// A wish may carry up to 10 MB of attachments, base64-encoded.
wishBody = express.json({ limit: '15mb' }),
defaultBody = express.json({ limit: '1mb' });
app.use((req: express.Request, res: express.Response, next: express.NextFunction) =>
(/^\/internal\/runs\/[^/]+\/checkpoint$/.test(req.path)
? checkpointBody
: req.path.startsWith('/provider-proxy/')
? proxyBody
: defaultBody)(req, res, next),
: req.method === 'POST' && /^\/v1\/projects\/[^/]+\/wishes$/.test(req.path)
? wishBody
: req.path.startsWith('/provider-proxy/')
? proxyBody
: defaultBody)(req, res, next),
);
app.useGlobalFilters(new Errors());
const raw = app.getHttpAdapter().getInstance();

View File

@ -68,6 +68,10 @@ async function proxy(request: NextRequest, context: Context) {
});
const disposition = upstream.headers.get('content-disposition');
if (disposition) responseHeaders.set('Content-Disposition', disposition);
// Files people uploaded come back as what they say they are, and never run as a page.
responseHeaders.set('X-Content-Type-Options', 'nosniff');
const policy = upstream.headers.get('content-security-policy');
if (policy) responseHeaders.set('Content-Security-Policy', policy);
if (stream) {
responseHeaders.set('X-Accel-Buffering', 'no');
responseHeaders.set('Connection', 'keep-alive');

View File

@ -3253,3 +3253,85 @@ fieldset:disabled label {
break-inside: auto;
}
}
.attachment-drop {
display: flex;
align-items: center;
gap: 12px;
flex-wrap: wrap;
padding: 12px 14px;
border: 1px dashed #c8d3df;
border-radius: var(--radius);
background: var(--bg);
transition:
border-color 0.15s,
background 0.15s;
}
.attachment-drop.dragging {
border-color: var(--teal);
background: var(--teal-pale);
}
.attachment-drop .field-hint {
flex: 1 1 260px;
}
.attachment-pick {
position: relative;
cursor: pointer;
}
.attachment-pick input {
position: absolute;
inset: 0;
opacity: 0;
cursor: pointer;
width: 100%;
}
.attachment-list {
list-style: none;
margin: 4px 0 0;
padding: 0;
display: grid;
grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));
gap: 8px;
}
.attachment-list li {
display: flex;
align-items: center;
gap: 10px;
min-width: 0;
padding: 6px 8px;
border: 1px solid var(--border);
border-radius: var(--radius);
background: var(--surface);
}
.attachment-list img,
.attachment-icon {
flex: none;
width: 44px;
height: 44px;
border-radius: 4px;
object-fit: cover;
background: var(--bg);
display: grid;
place-items: center;
color: var(--muted);
}
.attachment-list a {
display: contents;
color: inherit;
}
.attachment-name {
flex: 1;
min-width: 0;
display: flex;
flex-direction: column;
font-size: 12px;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
.attachment-name small {
color: var(--muted);
font-size: 11px;
}
.panel-body-list {
padding: 0 22px 4px;
}

View File

@ -1,6 +1,6 @@
'use client';
import Link from 'next/link';
import { useEffect, useState } from 'react';
import { useEffect, useRef, useState } from 'react';
import { useRouter } from 'next/navigation';
import {
ArrowRight,
@ -11,6 +11,7 @@ import {
FileDown,
GitBranch,
LockOpen,
Paperclip,
Pause,
Play,
Plus,
@ -64,6 +65,14 @@ import { credentialSourceLabel, initialWishProvider, wishProviderReady } from '@
import { personName } from '@/lib/people';
import { mayWishBackend, useMayWish, wishScopeFor } from '@/lib/permissions';
import type { CodeReview } from '@/lib/types';
import { inlineImageTypes } from '@wishforge/contracts/attachments';
import {
addAttachments,
attachmentLimitsText,
formatBytes,
pastedFiles,
type PendingAttachment,
} from '@/lib/attachments';
export function RunsView() {
const mayWish = useMayWish();
@ -418,6 +427,86 @@ function RefineAction({
</div>
);
}
/** Files for the agent to look at: chosen, dropped, or pasted into the wish. */
function AttachmentField({
attachments,
onAdd,
onRemove,
problem,
}: {
attachments: PendingAttachment[];
onAdd: (files: File[]) => void;
onRemove: (key: string) => void;
problem?: string;
}) {
const [dragging, setDragging] = useState(false);
return (
<div className="field">
<span className="field-label">附件</span>
<div
className={dragging ? 'attachment-drop dragging' : 'attachment-drop'}
onDragOver={event => {
if (![...event.dataTransfer.types].includes('Files')) return;
event.preventDefault();
setDragging(true);
}}
onDragLeave={() => setDragging(false)}
onDrop={event => {
event.preventDefault();
setDragging(false);
onAdd([...event.dataTransfer.files]);
}}
>
<label className="button button-secondary attachment-pick">
<Paperclip size={15} />
添加文件
<input
type="file"
multiple
aria-label="添加附件"
onChange={event => {
onAdd([...(event.target.files ?? [])]);
event.target.value = '';
}}
/>
</label>
<span className="field-hint">
截图、设计稿、日志或文档都可以:点按钮选择、拖到这里,或在「你的愿望」「验收标准」里直接粘贴截图。
{attachmentLimitsText}。
</span>
</div>
<FormError message={problem} />
{attachments.length ? (
<ul className="attachment-list" aria-label="已添加的附件">
{attachments.map(file => (
<li key={file.key}>
{file.preview ? (
// eslint-disable-next-line @next/next/no-img-element
<img src={file.preview} alt="" />
) : (
<span className="attachment-icon">
<Paperclip size={16} />
</span>
)}
<span className="attachment-name" title={file.name}>
{file.name}
<small>{formatBytes(file.size)}</small>
</span>
<button
type="button"
className="icon-button"
aria-label={`移除附件 ${file.name}`}
onClick={() => onRemove(file.key)}
>
<X size={15} />
</button>
</li>
))}
</ul>
) : null}
</div>
);
}
export function NewWishView() {
const projects = useResource<Project[]>('/projects');
const providers = useResource<ProviderInfo[]>('/providers');
@ -441,6 +530,42 @@ export function NewWishView() {
const [frontendOnly, setFrontendOnly] = useState(true);
const [refining, setRefining] = useState<RefineFocus>();
const [suggestion, setSuggestion] = useState<WishSuggestion & { focus: RefineFocus }>();
const [attachments, setAttachments] = useState<PendingAttachment[]>([]);
const [attachmentProblem, setAttachmentProblem] = useState<string>();
const [reading, setReading] = useState(0);
// Adds run one after another on the latest list, so a paste and a drop in quick succession both count.
const latestAttachments = useRef<PendingAttachment[]>([]);
const attaching = useRef<Promise<void>>(Promise.resolve());
function attach(files: File[]) {
if (!files.length) return;
setReading(count => count + 1);
attaching.current = attaching.current.then(async () => {
try {
const result = await addAttachments(latestAttachments.current, files);
latestAttachments.current = result.attachments;
setAttachments(result.attachments);
setAttachmentProblem(result.problem);
} catch {
setAttachmentProblem('读取文件失败,请重试。');
} finally {
setReading(count => count - 1);
}
});
}
function detach(key: string) {
const removed = latestAttachments.current.find(file => file.key === key);
if (removed?.preview) URL.revokeObjectURL(removed.preview);
latestAttachments.current = latestAttachments.current.filter(file => file.key !== key);
setAttachments(latestAttachments.current);
setAttachmentProblem(undefined);
}
/** A screenshot pasted into a text box becomes an attachment; text pastes as usual. */
const onPaste = (event: React.ClipboardEvent) => {
const files = pastedFiles(event.clipboardData);
if (!files.length) return;
event.preventDefault();
attach(files);
};
useEffect(() => {
const query = new URLSearchParams(window.location.search);
const selected = query.get('project');
@ -458,8 +583,7 @@ export function NewWishView() {
const provider = chosenProvider ?? initialWishProvider(providers.data, Boolean(localPoc));
// The project's models, flash when offered; a choice made for another project does not carry over.
const projectModels = project?.models ?? [];
const model =
chosenModel && projectModels.includes(chosenModel) ? chosenModel : defaultProjectModel(projectModels);
const model = chosenModel && projectModels.includes(chosenModel) ? chosenModel : defaultProjectModel(projectModels);
// The choice exists where the project says which code is backend.
const scopePolicy = project?.codeReview?.paths.length ? project.codeReview : undefined;
const scope = wishScopeFor(identity.data, project);
@ -520,6 +644,9 @@ export function NewWishView() {
...(model ? { model } : {}),
budget: { maxTokens, maxMinutes, maxRepairRounds },
...(scopePolicy ? { frontendOnly: frontendOnly || scope === 'frontend' } : {}),
...(attachments.length
? { attachments: attachments.map(({ name, mediaType, data }) => ({ name, mediaType, data })) }
: {}),
},
'POST',
idempotencyKey,
@ -577,9 +704,11 @@ export function NewWishView() {
}
value={goal}
onChange={event => setGoal(event.target.value)}
onPaste={onPaste}
/>
</Field>
{refineAction('goal')}
<AttachmentField attachments={attachments} onAdd={attach} onRemove={detach} problem={attachmentProblem} />
{scopePolicy && scope && scope !== 'none' ? (
<ScopeChoice
policy={scopePolicy}
@ -598,6 +727,7 @@ export function NewWishView() {
placeholder={'搜索结果遵循当前用户的项目权限\n筛选条件在刷新后保留\n新增功能通过集成测试'}
value={criteria}
onChange={event => setCriteria(event.target.value)}
onPaste={onPaste}
/>
</Field>
{refineAction('criteria')}
@ -712,7 +842,9 @@ export function NewWishView() {
<p>提交后可在运行详情中补充信息、暂停或取消。</p>
<Button
busy={busy}
disabled={!effectiveProject || !goal.trim() || !criteria.trim() || !providerReady || !mayWish}
disabled={
!effectiveProject || !goal.trim() || !criteria.trim() || !providerReady || !mayWish || reading > 0
}
>
<Send size={16} />
提交愿望
@ -1087,6 +1219,34 @@ export function RunDetailView({ id }: { id: string }) {
<p className="pre-wrap">{wishDetails(run.goal)}</p>
</Panel>
) : null}
{tab === 'overview' && run.attachments?.length ? (
<Panel title={`附件(${run.attachments.length})`}>
<ul className="attachment-list panel-body-list">
{run.attachments.map(file => {
const href = `/api/runs/${run.id}/attachments/${file.id}`;
return (
<li key={file.id}>
<a href={href} target="_blank" rel="noreferrer" title={file.name}>
{inlineImageTypes.includes(file.mediaType) ? (
// eslint-disable-next-line @next/next/no-img-element
<img src={href} alt={file.name} loading="lazy" />
) : (
<span className="attachment-icon">
<Paperclip size={16} />
</span>
)}
<span className="attachment-name">
{file.name}
<small>{formatBytes(file.size)}</small>
</span>
</a>
</li>
);
})}
</ul>
<p className="panel-note">提交愿望时附上的文件,执行器会在工作区里读取它们。</p>
</Panel>
) : null}
{tab === 'overview' && run.implementationSummary ? (
<Panel title="改动说明">
<p className="pre-wrap">{run.implementationSummary}</p>

View File

@ -0,0 +1,99 @@
import {
MAX_ATTACHMENT_BYTES,
MAX_ATTACHMENTS,
MAX_ATTACHMENTS_TOTAL_BYTES,
inlineImageTypes,
} from '@wishforge/contracts/attachments';
/** A file chosen for a wish, read and ready to send. */
export interface PendingAttachment {
key: string;
name: string;
mediaType: string;
size: number;
/** base64 */
data: string;
/** An object URL for images the browser shows, revoked when the file is removed. */
preview?: string;
}
export const attachmentLimitsText = `最多 ${MAX_ATTACHMENTS} 个,单个不超过 ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB,合计不超过 ${MAX_ATTACHMENTS_TOTAL_BYTES / 1024 / 1024} MB`;
export function formatBytes(size: number) {
if (size < 1024) return `${size} B`;
if (size < 1024 * 1024) return `${(size / 1024).toFixed(size < 10 * 1024 ? 1 : 0)} KB`;
return `${(size / 1024 / 1024).toFixed(1)} MB`;
}
/** A pasted screenshot has no useful name; give it one with the time it was pasted. */
function nameOf(file: File, index: number) {
if (file.name && file.name !== 'image.png') return file.name;
const extension = file.type.split('/')[1]?.replace('jpeg', 'jpg') ?? 'png';
const now = new Date();
const two = (n: number) => String(n).padStart(2, '0');
const stamp = `${now.getFullYear()}${two(now.getMonth() + 1)}${two(now.getDate())}-${two(now.getHours())}${two(now.getMinutes())}${two(now.getSeconds())}`;
return `粘贴图片-${stamp}${index ? `-${index + 1}` : ''}.${extension}`;
}
async function base64Of(file: Blob) {
const bytes = new Uint8Array(await file.arrayBuffer());
let binary = '';
for (let i = 0; i < bytes.length; i += 0x8000) binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
return btoa(binary);
}
/**
* Adds files to those already chosen, within the limits; returns the new list and, when some
* did not fit, why.
*/
export async function addAttachments(
current: PendingAttachment[],
files: File[],
): Promise<{ attachments: PendingAttachment[]; problem?: string }> {
const attachments = [...current];
const problems: string[] = [];
let total = current.reduce((sum, file) => sum + file.size, 0);
for (const [index, file] of files.entries()) {
const name = nameOf(file, index);
if (attachments.length >= MAX_ATTACHMENTS) {
problems.push(`最多只能附 ${MAX_ATTACHMENTS} 个文件`);
break;
}
if (file.size === 0) {
problems.push(`「${name}」是空文件`);
continue;
}
if (file.size > MAX_ATTACHMENT_BYTES) {
problems.push(`「${name}」超过 ${MAX_ATTACHMENT_BYTES / 1024 / 1024} MB`);
continue;
}
if (total + file.size > MAX_ATTACHMENTS_TOTAL_BYTES) {
problems.push(`附件合计不能超过 ${MAX_ATTACHMENTS_TOTAL_BYTES / 1024 / 1024} MB`);
continue;
}
const mediaType = file.type || 'application/octet-stream';
attachments.push({
key: `${Date.now()}-${Math.random().toString(36).slice(2)}`,
name,
mediaType,
size: file.size,
data: await base64Of(file),
...(inlineImageTypes.includes(mediaType) ? { preview: URL.createObjectURL(file) } : {}),
});
total += file.size;
}
return { attachments, ...(problems.length ? { problem: `${[...new Set(problems)].join(';')}。` } : {}) };
}
/**
* The files a paste carries, unless it is text: copying cells or a document often brings a
* picture of them along, and then the text is what the person meant.
*/
export function pastedFiles(data: DataTransfer | null): File[] {
if (!data) return [];
const files = [...data.files];
if (!files.length) return [];
const text = data.getData('text/plain').trim();
if (text && !files.some(file => file.name === text)) return [];
return files;
}

View File

@ -72,6 +72,8 @@ export type Run = {
revertOf?: { runId: string; integratedCommit: string; targetCommit: string };
/** The wish may change only frontend code; a change to backend code is put back and redone. */
frontendOnly?: boolean;
/** Files attached to the wish; each is at /runs/{id}/attachments/{attachmentId}. */
attachments?: Array<{ id: string; name: string; mediaType: string; size: number }>;
/** The model the run was pinned to at submission, when one was chosen. */
providerModel?: string;
};

View File

@ -53,6 +53,8 @@ export interface RunContext {
bundleConfig?: AgentBundleConfig;
/** The project's active skills (workflows, pitfalls, conventions), most recently changed first. */
skills?: PromptSkill[];
/** Files attached to the wish, base64; the executor writes them into its workspace. */
attachments?: Array<{ id: string; name: string; mediaType: string; data: string }>;
delivery?: {
release?: { id: string; status: string };
verificationEvidenceId?: string;

View File

@ -1,6 +1,6 @@
import path from 'node:path';
import { rm, writeFile } from 'node:fs/promises';
import { countedTokens, type Run } from '@wishforge/contracts';
import { appendFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
import { ATTACHMENT_DIRECTORY, attachmentFileName, countedTokens, type Run } from '@wishforge/contracts';
import { BASELINE_BUNDLE, BASELINE_VERSION, bundleDigest, bundlePrompt, questionsIn } from '@wishforge/agent';
import {
executeCommand,
@ -93,6 +93,30 @@ function createProvider(config: WorkerConfig, context: RunContext, isolatedHome:
return providerRegistry[context.run.provider]?.(config, context, isolatedHome);
}
/**
* Writes the files attached to the wish into the workspace for the agent to read, in a directory
* Git ignores, so they never reach a checkpoint or a commit.
*/
export async function writeAttachments(workspace: string, files: RunContext['attachments']) {
if (!files?.length) return [];
const directory = path.join(workspace, ATTACHMENT_DIRECTORY);
await mkdir(directory, { recursive: true });
const exclude = path.join(workspace, '.git', 'info', 'exclude');
const pattern = `/${ATTACHMENT_DIRECTORY}/`;
const excluded = await readFile(exclude, 'utf8').catch(() => '');
if (!excluded.split('\n').includes(pattern)) {
await mkdir(path.dirname(exclude), { recursive: true });
await appendFile(exclude, `${excluded && !excluded.endsWith('\n') ? '\n' : ''}${pattern}\n`);
}
return Promise.all(
files.map(async (file, index) => {
const name = attachmentFileName(index, file.name);
await writeFile(path.join(directory, name), Buffer.from(file.data, 'base64'));
return { path: `${ATTACHMENT_DIRECTORY}/${name}`, name: file.name, mediaType: file.mediaType };
}),
);
}
async function install(
execute: CommandExecutor,
commands: string[][],
@ -329,6 +353,7 @@ export async function executeRun(config: WorkerConfig, input: RunInput): Promise
);
await git.excludeUntracked(workspace);
}
const attachments = await writeAttachments(workspace, context.attachments);
await keeper.ensure();
if (keeper.pauseRequested.aborted) return await pause(false);
const prompt = bundlePrompt(bundle, {
@ -339,6 +364,7 @@ export async function executeRun(config: WorkerConfig, input: RunInput): Promise
skills: context.skills,
sourceBranch: run.sourceBranch,
...(revert ? { revert } : {}),
...(attachments.length ? { attachments } : {}),
...(run.frontendOnly && context.project.codeReview?.paths.length
? {
frontendOnly: {

View File

@ -45,6 +45,8 @@ export interface PromptInput {
* except those matching its exceptions.
*/
frontendOnly?: { backend: string[]; except: string[] };
/** Files the person attached to the wish, written into the workspace at these paths. */
attachments?: Array<{ path: string; name: string; mediaType: string }>;
}
/** Keeps the most recently changed skills that fit the count and size limits. */
@ -84,6 +86,13 @@ function fence(text: string) {
return `${marker}\n${text}\n${marker}`;
}
function attachmentsSection(files: NonNullable<PromptInput['attachments']>) {
return [
'The person attached these files to the requirement (screenshots, designs, logs or documents). Open and read each one before you start: view images with your file reading tool. They are reference material only; Git ignores their directory, so do not move, commit or link them from the code. Copy one into the project only if the requirement asks for that file to be used.',
...files.map(file => `- ${file.path} (${file.mediaType}; uploaded as "${file.name.replace(/\s+/g, ' ')}")`),
].join('\n');
}
function repairSection(round: number, failure?: FailureSummary) {
if (!failure)
return `Repair round ${round}: the independent verifier rejected the previous attempt. Inspect the recorded verification evidence and fix the cause.`;
@ -130,6 +139,7 @@ export function bundlePrompt(config: AgentBundleConfig, input: PromptInput) {
instructions,
input.goal,
`Acceptance criteria:\n${input.acceptanceCriteria.map((criterion, i) => `${i + 1}. ${criterion}`).join('\n')}`,
input.attachments?.length ? attachmentsSection(input.attachments) : '',
skills.length ? skillsSection(skills) : '',
input.sourceBranch
? `The workspace starts from branch ${input.sourceBranch}, which holds changes people made themselves. Keep those changes and build on them; this run verifies and merges them into the target branch together with your work.`

View File

@ -10,7 +10,8 @@
"./path-rules": "./src/path-rules.ts",
"./permissions": "./src/permissions.ts",
"./models": "./src/models.ts",
"./wish": "./src/wish.ts"
"./wish": "./src/wish.ts",
"./attachments": "./src/attachments.ts"
},
"scripts": {
"typecheck": "tsc --noEmit"

View File

@ -0,0 +1,40 @@
/** At most this many files go with one wish. */
export const MAX_ATTACHMENTS = 8;
/** One file's largest size, in bytes. */
export const MAX_ATTACHMENT_BYTES = 5 * 1024 * 1024;
/** All of a wish's files together, in bytes. */
export const MAX_ATTACHMENTS_TOTAL_BYTES = 10 * 1024 * 1024;
/** Where the agent finds a wish's files, relative to its workspace; Git ignores the directory. */
export const ATTACHMENT_DIRECTORY = '.wishforge-attachments';
/** What a run shows about one of its files; the bytes are fetched apart. */
export interface AttachmentInfo {
id: string;
name: string;
mediaType: string;
size: number;
}
/** Bytes of a base64 string, without decoding it. */
export function base64Size(data: string): number {
const padding = data.endsWith('==') ? 2 : data.endsWith('=') ? 1 : 0;
return Math.max(0, (data.length / 4) * 3 - padding);
}
/**
* A file name safe to write into a workspace: no directories, no control or shell-unfriendly
* characters, numbered so two files with the same name stay apart.
*/
export function attachmentFileName(index: number, name: string): string {
const base = name.split(/[\\/]/).pop() ?? '';
const clean = base
.replace(/[\u0000-\u001f\u007f]/g, '')
.replace(/[^\p{L}\p{N}._ -]/gu, '_')
.replace(/^[.\s]+/, '')
.trim()
.slice(-120);
return `${String(index + 1).padStart(2, '0')}-${clean || 'file'}`;
}
/** Images a browser shows inline; SVG stays out, since it can carry script. */
export const inlineImageTypes = ['image/png', 'image/jpeg', 'image/gif', 'image/webp', 'image/bmp'];

View File

@ -13,6 +13,7 @@ import { EXECUTOR_TIMEOUT_MINUTES, providerEventTypes, providers, type ProviderI
import { CODE_REVIEW_PATTERN_LIMIT, invalidGlob, type CodeReviewPolicy } from './path-rules.js';
import { MAX_PROJECT_MODELS } from './models.js';
import { accountTypeNames, wishScopes, type AccountType, type Permissions } from './permissions.js';
import { MAX_ATTACHMENT_BYTES, MAX_ATTACHMENTS, type AttachmentInfo } from './attachments.js';
export const API_VERSION = 1;
export const roles = ['owner', 'admin', 'developer', 'deployer', 'viewer'] as const;
@ -69,7 +70,8 @@ export type EntityKind =
| 'notification'
| 'skill'
| 'skill_harvest'
| 'skill_usage';
| 'skill_usage'
| 'attachment';
export interface Entity {
id: string;
tenantId: string;
@ -182,6 +184,16 @@ export interface Wish extends Entity {
goal: string;
acceptanceCriteria: string[];
}
/** The bytes of a file attached to a wish; its run lists it in `attachments`. */
export interface Attachment extends Entity {
projectId: string;
runId: string;
name: string;
mediaType: string;
size: number;
/** base64 */
data: string;
}
export interface Lease {
token: number;
workerId: string;
@ -219,6 +231,8 @@ export interface Run extends Entity {
* paths, minus their exceptions). A change to one goes back to the agent before any check runs.
*/
frontendOnly?: boolean;
/** Files attached to the wish; their bytes are `attachment` records. */
attachments?: AttachmentInfo[];
executionGeneration?: string;
/** Outbox item that will start the current generation. */
pendingStartId?: string;
@ -583,6 +597,26 @@ export const executorSettingsInput = z
})
.strict();
export type ExecutorSettingsInput = z.infer<typeof executorSettingsInput>;
/** A file someone attached to a wish (a screenshot, a design, a log), as the API receives it. */
export const attachmentInput = z
.object({
name: z.string().trim().min(1).max(200),
mediaType: z
.string()
.trim()
.toLowerCase()
.regex(/^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/)
.max(127)
.default('application/octet-stream'),
/** The file's bytes, base64. */
data: z
.string()
.max(Math.ceil(MAX_ATTACHMENT_BYTES / 3) * 4)
.regex(/^[A-Za-z0-9+/]*={0,2}$/, 'Attachment data must be base64'),
})
.strict();
export type AttachmentInput = z.infer<typeof attachmentInput>;
export const wishInput = z
.object({
goal: text.max(20000),
@ -601,6 +635,12 @@ export const wishInput = z
.describe(
'Change only frontend code: no file the project counts as backend (its code review paths, minus their exceptions)',
),
/** Screenshots, designs, logs or documents the agent should look at. */
attachments: z
.array(attachmentInput)
.max(MAX_ATTACHMENTS)
.optional()
.describe('Files for the agent to look at (screenshots, designs, logs), base64-encoded'),
})
.strict();
export const commandInput = z
@ -915,4 +955,5 @@ export * from './change-paths.js';
export * from './release-risk.js';
export * from './path-rules.js';
export * from './permissions.js';
export * from './attachments.js';
export * from './wish.js';

149
tests/attachments.test.ts Normal file
View File

@ -0,0 +1,149 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { mkdtemp, readFile, mkdir, rm } from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import {
ATTACHMENT_DIRECTORY,
attachmentFileName,
base64Size,
wishInput,
type Actor,
type Project,
} from '@wishforge/contracts';
import { BASELINE_BUNDLE, bundlePrompt } from '@wishforge/agent';
import { ControlPlane } from '../apps/api/src/domain/control-plane.js';
import { writeAttachments } from '../apps/worker/src/executor.js';
import { MemoryStore } from './helpers/memory-store.js';
// A wish may carry screenshots, designs and logs for the agent to look at.
const env = {
NODE_ENV: 'test',
WF_DISPATCH_TENANTS: 'demo',
WF_GIT_SERVICE_URL: 'http://127.0.0.1:4504',
WF_GIT_ADMIN_TOKEN: 'git-admin-token-for-tests-only-0001',
};
const owner: Actor = { tenantId: 'demo', userId: 'owner', role: 'owner', kind: 'human' };
const worker: Actor = { ...owner, userId: 'worker', kind: 'worker' };
const png = Buffer.from('89504e470d0a1a0a0000000d49484452', 'hex').toString('base64');
let store: MemoryStore;
let project: Project;
beforeEach(async () => {
vi.stubGlobal('fetch', async (input: string | URL, init: RequestInit) => {
const body = JSON.parse(String(init.body));
if (new URL(String(input)).pathname === '/repos')
return Response.json({
repositoryUrl: `https://git.test/git/${body.tenantId}/${body.projectId}.git`,
initialCommit: 'a'.repeat(40),
defaultBranch: 'main',
});
return Response.json({ token: 'payload.signature', expiresAt: new Date(Date.now() + 900_000).toISOString() });
});
store = new MemoryStore();
store.seed('demo');
project = await new ControlPlane(store, env).createProject(owner, { name: 'Todo App' });
});
afterEach(() => vi.unstubAllGlobals());
describe('wish attachments', () => {
it('keeps the files apart from the run, lists them on it, and gives the bytes to the executor only', async () => {
const control = new ControlPlane(store, env);
const { run_id } = await control.submit(
owner,
project.id,
{
goal: 'Make the login page look like the design',
acceptanceCriteria: ['Matches the screenshot'],
attachments: [
{ name: 'design.png', mediaType: 'image/png', data: png },
{ name: 'notes.txt', mediaType: 'text/plain', data: Buffer.from('左对齐').toString('base64') },
],
},
'attachments-0001',
);
const run = await control.run(owner, run_id);
expect(run.attachments).toEqual([
{ id: expect.any(String), name: 'design.png', mediaType: 'image/png', size: 16 },
{ id: expect.any(String), name: 'notes.txt', mediaType: 'text/plain', size: 9 },
]);
expect(JSON.stringify(run)).not.toContain(png);
const events = await control.events(owner, run_id);
expect(events[0]!.message).toContain('2 个附件');
const file = await control.attachment(owner, run_id, run.attachments![0]!.id);
expect(Buffer.from(file.data, 'base64').toString('hex')).toBe('89504e470d0a1a0a0000000d49484452');
await expect(control.attachment(owner, run_id, 'missing')).rejects.toMatchObject({ code: 'NOT_FOUND' });
const forWorker = await control.context(worker, run_id);
expect(forWorker.attachments.map(item => item.name)).toEqual(['design.png', 'notes.txt']);
expect(forWorker.attachments[0]!.data).toBe(png);
expect((await control.context(owner, run_id)).attachments).toEqual([]);
});
it('refuses files beyond the limits', async () => {
const control = new ControlPlane(store, env);
const big = Buffer.alloc(4 * 1024 * 1024).toString('base64');
await expect(
control.submit(
owner,
project.id,
{
goal: 'Too much to look at',
acceptanceCriteria: ['n/a'],
attachments: [1, 2, 3].map(n => ({ name: `${n}.bin`, data: big })),
},
'attachments-0002',
),
).rejects.toMatchObject({ code: 'ATTACHMENTS_TOO_LARGE' });
expect(() =>
wishInput.parse({
goal: 'x',
acceptanceCriteria: ['y'],
attachments: Array.from({ length: 9 }, () => ({ name: 'a.png', data: png })),
}),
).toThrow();
expect(() =>
wishInput.parse({ goal: 'x', acceptanceCriteria: ['y'], attachments: [{ name: 'a', data: 'not base64!' }] }),
).toThrow();
});
it('names files safely and counts base64 bytes', () => {
expect(attachmentFileName(0, '../../etc/passwd')).toBe('01-passwd');
expect(attachmentFileName(2, '.env')).toBe('03-env');
expect(attachmentFileName(9, '登录页 截图(1).png')).toBe('10-登录页 截图_1_.png');
expect(attachmentFileName(0, '')).toBe('01-file');
expect(base64Size(Buffer.from('abcd').toString('base64'))).toBe(4);
expect(base64Size(Buffer.from('abcde').toString('base64'))).toBe(5);
});
it('writes the files into an ignored workspace directory and points the prompt at them', async () => {
const workspace = await mkdtemp(path.join(os.tmpdir(), 'wf-attach-'));
try {
await mkdir(path.join(workspace, '.git', 'info'), { recursive: true });
const files = [{ id: 'a', name: 'design.png', mediaType: 'image/png', data: png }];
const written = await writeAttachments(workspace, files);
// A second round (a repair, a resume) writes them again without repeating the ignore rule.
await writeAttachments(workspace, files);
expect(written).toEqual([
{ path: `${ATTACHMENT_DIRECTORY}/01-design.png`, name: 'design.png', mediaType: 'image/png' },
]);
expect((await readFile(path.join(workspace, written[0]!.path))).toString('base64')).toBe(png);
expect(await readFile(path.join(workspace, '.git', 'info', 'exclude'), 'utf8')).toBe(
`/${ATTACHMENT_DIRECTORY}/\n`,
);
const prompt = bundlePrompt(BASELINE_BUNDLE, {
goal: 'Match the design',
acceptanceCriteria: ['Looks right'],
repairCount: 0,
attachments: written,
});
expect(prompt).toContain(`- ${ATTACHMENT_DIRECTORY}/01-design.png (image/png; uploaded as "design.png")`);
expect(prompt).toContain('view images with your file reading tool');
expect(bundlePrompt(BASELINE_BUNDLE, { goal: 'x', acceptanceCriteria: ['y'], repairCount: 0 })).not.toContain(
ATTACHMENT_DIRECTORY,
);
} finally {
await rm(workspace, { recursive: true, force: true });
}
});
});