From 04df551f6a63737f5a6186037bed1067318200e6 Mon Sep 17 00:00:00 2001 From: Codex Bot Date: Wed, 28 Oct 2026 23:42:18 +0800 Subject: [PATCH] Harden series validation and synchronize agent delivery contracts --- .gitea/workflows/studio.yml | 12 +++++++++ apps/studio/fixtures/autumn-journal.json | 25 +++++++++++++------ apps/studio/src/lib/series.ts | 2 +- apps/studio/src/pages/api/index.ts | 2 +- apps/studio/src/pages/api/layouts/index.ts | 4 +-- .../fixtures/autumn-journal.json | 25 +++++++++++++------ apps/waterfall-wiki/src/lib/series.ts | 2 +- apps/waterfall-wiki/src/pages/api/index.ts | 1 + content/studio-examples/autumn-journal.json | 25 +++++++++++++------ scripts/check-studio-contracts.mjs | 9 +++++++ scripts/export-studio-series.cjs | 2 +- scripts/publish-studio-library.mjs | 1 + scripts/save-studio-series.mjs | 2 +- 13 files changed, 84 insertions(+), 28 deletions(-) create mode 100644 scripts/check-studio-contracts.mjs diff --git a/.gitea/workflows/studio.yml b/.gitea/workflows/studio.yml index 8325218..301e7c5 100644 --- a/.gitea/workflows/studio.yml +++ b/.gitea/workflows/studio.yml @@ -9,6 +9,9 @@ on: - 'scripts/verify-studio-library.mjs' - 'scripts/verify-studio-visual.cjs' - '.gitea/workflows/studio.yml' + - 'scripts/*studio*' + - 'content/studio-examples/**' + - 'content/studio-tools/layouts-api.md' - 'pnpm-workspace.yaml' pull_request: paths: @@ -18,6 +21,9 @@ on: - 'scripts/verify-studio-library.mjs' - 'scripts/verify-studio-visual.cjs' - '.gitea/workflows/studio.yml' + - 'scripts/*studio*' + - 'content/studio-examples/**' + - 'content/studio-tools/layouts-api.md' - 'pnpm-workspace.yaml' workflow_dispatch: @@ -29,6 +35,12 @@ jobs: - uses: actions/checkout@v4 with: fetch-depth: 0 + - name: Check shared content and documentation contracts + run: | + node scripts/check-studio-contracts.mjs + node --check scripts/export-studio-series.cjs + node --check scripts/save-studio-series.mjs + bash -n scripts/publish-studio-guide.sh - name: Build and verify studio run: docker build -f apps/studio/Dockerfile -t "prompt-studio:${{ gitea.sha }}" . - name: Release studio diff --git a/apps/studio/fixtures/autumn-journal.json b/apps/studio/fixtures/autumn-journal.json index af769a2..9d02696 100644 --- a/apps/studio/fixtures/autumn-journal.json +++ b/apps/studio/fixtures/autumn-journal.json @@ -106,9 +106,9 @@ "images": { "I01": { "fit": "cover", - "cropX": 50, - "cropY": 50, - "zoom": 1 + "cropX": 65, + "cropY": 40, + "zoom": 1.25 } }, "decorations": {} @@ -127,10 +127,12 @@ "parameters": { "texts": { "T01": { - "value": "留一点白\n给下一次" + "value": "留一点白\n给下一次", + "align": "middle" }, "T02": { - "value": "今天,捡起一片叶子。\n用三个词记录它的颜色、纹理与心情。\n你的秋天,会从哪一页开始?" + "value": "今天,捡起一片叶子。\n用三个词记录它的颜色、纹理与心情。\n你的秋天,会从哪一页开始?", + "align": "middle" }, "T03": { "value": "YOUR TURN / 03" @@ -139,12 +141,21 @@ "images": { "I01": { "fit": "cover", - "cropX": 50, + "cropX": 65, "cropY": 50, "zoom": 1 } }, - "decorations": {} + "decorations": {}, + "layers": { + "I01": { + "x": 40, + "y": 55, + "width": 40, + "height": 40, + "radius": 20 + } + } } } ] diff --git a/apps/studio/src/lib/series.ts b/apps/studio/src/lib/series.ts index 46f4f51..214d425 100644 --- a/apps/studio/src/lib/series.ts +++ b/apps/studio/src/lib/series.ts @@ -1,7 +1,7 @@ import {parameters,LayoutParameterError,type Layout,type Parameters,type TextValue,uuid} from './layout-parameters'; export type Typography=Required>; export type Series={version:1;brief:{topic:string;audience:string;intent:string;designIntent:string;imageStrategy:string};style:{version:string;palette:{paper:string;ink:string;muted:string;accent:string};typography:Record<'title'|'body'|'caption',Typography>;spacing:{margin:number;gap:number}};sources:{assetId:string;author:string;license:string;url:string;prompt:string;tool:string}[];pages:{key:string;role:'cover'|'body'|'ending';layoutId:string;intent:string;bindings:Record;parameters:Parameters}[]}; -const fail=(message:string):never=>{throw new LayoutParameterError(message)}; +function fail(message:string):never{throw new LayoutParameterError(message)} const obj=(v:unknown)=>{if(!v||typeof v!=='object'||Array.isArray(v))return fail('作品字段必须是对象');return v as Record}; function exact(v:unknown,allowed:string[]){const o=obj(v);if(Object.keys(o).some(k=>!allowed.includes(k)))fail('作品包含未知字段');return o} function str(v:unknown,max=1000){if(typeof v!=='string'||!v.trim()||v.length>max)fail('作品文字缺失或超长');return v as string} diff --git a/apps/studio/src/pages/api/index.ts b/apps/studio/src/pages/api/index.ts index 7677ab7..6c0b54b 100644 --- a/apps/studio/src/pages/api/index.ts +++ b/apps/studio/src/pages/api/index.ts @@ -1,3 +1,3 @@ import type {NextApiRequest,NextApiResponse} from 'next'; import {ideas} from '../../content/ideas'; -export default function handler(_:NextApiRequest,res:NextApiResponse){res.setHeader('Content-Type','text/markdown; charset=utf-8');res.send('# 创作站\n\n- [27 套排版目录与 API](/studio/api/layouts?agent_mode=True)\n- [按 ID 保存效果](/api/studio/designs?agent_mode=True)\n\n'+ideas.map(i=>`- [${i.title}](/studio/ideas/${i.slug}) · [正文](/studio/api/export/${i.slug}?format=markdown)`).join('\n'));} +export default function handler(_:NextApiRequest,res:NextApiResponse){res.setHeader('Content-Type','text/markdown; charset=utf-8');res.send('# 创作站\n\n- [27 套排版目录与 API](/studio/api/layouts?agent_mode=True)\n- [多页作品与统一视觉](/api/studio/series?agent_mode=True)\n- [按 ID 保存效果](/api/studio/designs?agent_mode=True)\n\n'+ideas.map(i=>`- [${i.title}](/studio/ideas/${i.slug}) · [正文](/studio/api/export/${i.slug}?format=markdown)`).join('\n'));} diff --git a/apps/studio/src/pages/api/layouts/index.ts b/apps/studio/src/pages/api/layouts/index.ts index 9904afc..cb7cd0a 100644 --- a/apps/studio/src/pages/api/layouts/index.ts +++ b/apps/studio/src/pages/api/layouts/index.ts @@ -5,6 +5,6 @@ export default function handler(req:NextApiRequest,res:NextApiResponse){ if(!['GET','HEAD'].includes(req.method||'')){res.setHeader('Allow','GET, HEAD');return res.status(405).end()} const entries=[standard,...fixed].map(l=>({id:l.id,name:l.name,family:l.id==='standard-01'?'standard':'fixed',url:'/studio/layouts/'+l.id,api:'/studio/api/layouts/'+l.id})); res.setHeader('Cache-Control','no-store');if(req.method==='HEAD')return res.status(200).end(); - if(String(req.query.agent_mode).toLowerCase()==='true'){res.setHeader('Content-Type','text/plain; charset=utf-8');return res.send('# Studio 可视化排版 API 库\n\n'+entries.map(e=>`${e.family} / ${e.id} · ${e.name}\n页面:${e.url}\n参数:${e.api}?agent_mode=True`).join('\n\n')+'\n\nCRUD:/api/studio/designs?agent_mode=True\n统一文档:/explore/8eb8c76500580f7a4b56ba3c')} - return res.json({version:1,layouts:entries,saveApi:'/api/studio/designs',catalogUrl:'/studio',documentationUrl:'/explore/8eb8c76500580f7a4b56ba3c'}); + if(String(req.query.agent_mode).toLowerCase()==='true'){res.setHeader('Content-Type','text/plain; charset=utf-8');return res.send('# Studio 可视化排版 API 库\n\n'+entries.map(e=>`${e.family} / ${e.id} · ${e.name}\n页面:${e.url}\n参数:${e.api}?agent_mode=True`).join('\n\n')+'\n\n多页作品:/api/studio/series?agent_mode=True\n单页 CRUD:/api/studio/designs?agent_mode=True\n统一文档:/explore/8eb8c76500580f7a4b56ba3c')} + return res.json({version:1,seriesDocumentVersion:1,seriesApi:'/api/studio/series',layouts:entries,saveApi:'/api/studio/designs',catalogUrl:'/studio',documentationUrl:'/explore/8eb8c76500580f7a4b56ba3c'}); } diff --git a/apps/waterfall-wiki/fixtures/autumn-journal.json b/apps/waterfall-wiki/fixtures/autumn-journal.json index af769a2..9d02696 100644 --- a/apps/waterfall-wiki/fixtures/autumn-journal.json +++ b/apps/waterfall-wiki/fixtures/autumn-journal.json @@ -106,9 +106,9 @@ "images": { "I01": { "fit": "cover", - "cropX": 50, - "cropY": 50, - "zoom": 1 + "cropX": 65, + "cropY": 40, + "zoom": 1.25 } }, "decorations": {} @@ -127,10 +127,12 @@ "parameters": { "texts": { "T01": { - "value": "留一点白\n给下一次" + "value": "留一点白\n给下一次", + "align": "middle" }, "T02": { - "value": "今天,捡起一片叶子。\n用三个词记录它的颜色、纹理与心情。\n你的秋天,会从哪一页开始?" + "value": "今天,捡起一片叶子。\n用三个词记录它的颜色、纹理与心情。\n你的秋天,会从哪一页开始?", + "align": "middle" }, "T03": { "value": "YOUR TURN / 03" @@ -139,12 +141,21 @@ "images": { "I01": { "fit": "cover", - "cropX": 50, + "cropX": 65, "cropY": 50, "zoom": 1 } }, - "decorations": {} + "decorations": {}, + "layers": { + "I01": { + "x": 40, + "y": 55, + "width": 40, + "height": 40, + "radius": 20 + } + } } } ] diff --git a/apps/waterfall-wiki/src/lib/series.ts b/apps/waterfall-wiki/src/lib/series.ts index 46f4f51..214d425 100644 --- a/apps/waterfall-wiki/src/lib/series.ts +++ b/apps/waterfall-wiki/src/lib/series.ts @@ -1,7 +1,7 @@ import {parameters,LayoutParameterError,type Layout,type Parameters,type TextValue,uuid} from './layout-parameters'; export type Typography=Required>; export type Series={version:1;brief:{topic:string;audience:string;intent:string;designIntent:string;imageStrategy:string};style:{version:string;palette:{paper:string;ink:string;muted:string;accent:string};typography:Record<'title'|'body'|'caption',Typography>;spacing:{margin:number;gap:number}};sources:{assetId:string;author:string;license:string;url:string;prompt:string;tool:string}[];pages:{key:string;role:'cover'|'body'|'ending';layoutId:string;intent:string;bindings:Record;parameters:Parameters}[]}; -const fail=(message:string):never=>{throw new LayoutParameterError(message)}; +function fail(message:string):never{throw new LayoutParameterError(message)} const obj=(v:unknown)=>{if(!v||typeof v!=='object'||Array.isArray(v))return fail('作品字段必须是对象');return v as Record}; function exact(v:unknown,allowed:string[]){const o=obj(v);if(Object.keys(o).some(k=>!allowed.includes(k)))fail('作品包含未知字段');return o} function str(v:unknown,max=1000){if(typeof v!=='string'||!v.trim()||v.length>max)fail('作品文字缺失或超长');return v as string} diff --git a/apps/waterfall-wiki/src/pages/api/index.ts b/apps/waterfall-wiki/src/pages/api/index.ts index a9b70e9..e7332db 100644 --- a/apps/waterfall-wiki/src/pages/api/index.ts +++ b/apps/waterfall-wiki/src/pages/api/index.ts @@ -7,6 +7,7 @@ export default function handler(req:NextApiRequest,res:NextApiResponse){ {path:'/studio/api/layouts',title:'标准与27套固定排版目录',methods:'GET',documentation:'/studio/api/layouts?agent_mode=True'}, {path:'/studio/api/layouts/{id}',title:'排版参数与 SVG 渲染',methods:'GET, POST',documentation:'/studio/api/layouts/{id}?agent_mode=True'}, {path:'/api/studio/series',title:'原子保存多页图文作品',methods:'POST',documentation:'/api/studio/series?agent_mode=True'}, + {path:'/api/studio/series/{id}/export',title:'多页原生高清导出计划',methods:'GET',documentation:'/api/studio/series/{id}/export?agent_mode=True'}, {path:'/api/studio/series/{id}',title:'读取、修订与归档多页作品',methods:'GET, PATCH, DELETE, POST',documentation:'/api/studio/series/{id}?agent_mode=True'}, {path:'/api/studio/designs',title:'保存与列举 Studio 效果',methods:'GET, POST',documentation:'/api/studio/designs?agent_mode=True'}, {path:'/api/studio/designs/{id}',title:'读取、更新与可恢复删除页面',methods:'GET, PATCH, DELETE, POST',documentation:'/api/studio/designs/{id}?agent_mode=True'}, diff --git a/content/studio-examples/autumn-journal.json b/content/studio-examples/autumn-journal.json index af769a2..9d02696 100644 --- a/content/studio-examples/autumn-journal.json +++ b/content/studio-examples/autumn-journal.json @@ -106,9 +106,9 @@ "images": { "I01": { "fit": "cover", - "cropX": 50, - "cropY": 50, - "zoom": 1 + "cropX": 65, + "cropY": 40, + "zoom": 1.25 } }, "decorations": {} @@ -127,10 +127,12 @@ "parameters": { "texts": { "T01": { - "value": "留一点白\n给下一次" + "value": "留一点白\n给下一次", + "align": "middle" }, "T02": { - "value": "今天,捡起一片叶子。\n用三个词记录它的颜色、纹理与心情。\n你的秋天,会从哪一页开始?" + "value": "今天,捡起一片叶子。\n用三个词记录它的颜色、纹理与心情。\n你的秋天,会从哪一页开始?", + "align": "middle" }, "T03": { "value": "YOUR TURN / 03" @@ -139,12 +141,21 @@ "images": { "I01": { "fit": "cover", - "cropX": 50, + "cropX": 65, "cropY": 50, "zoom": 1 } }, - "decorations": {} + "decorations": {}, + "layers": { + "I01": { + "x": 40, + "y": 55, + "width": 40, + "height": 40, + "radius": 20 + } + } } } ] diff --git a/scripts/check-studio-contracts.mjs b/scripts/check-studio-contracts.mjs new file mode 100644 index 0000000..73e75fb --- /dev/null +++ b/scripts/check-studio-contracts.mjs @@ -0,0 +1,9 @@ +/** Source-only parity and syntax checks; no compilation or generated output. */ +import {readFile} from 'node:fs/promises'; +import assert from 'node:assert/strict'; +const root=new URL('../',import.meta.url),read=path=>readFile(new URL(path,root),'utf8'); +for(const file of ['layout-parameters.ts','series.ts'])assert.equal(await read('apps/studio/src/lib/'+file),await read('apps/waterfall-wiki/src/lib/'+file),file+' contract drift'); +const canonical=await read('content/studio-examples/autumn-journal.json');for(const app of ['studio','waterfall-wiki'])assert.equal(canonical,await read('apps/'+app+'/fixtures/autumn-journal.json'),'Example fixture drift'); +const doc=await read('apps/waterfall-wiki/src/lib/studio-design-documentation.ts'),encoded=doc.match(/export const designDocs=(.*);\n/); +assert.ok(encoded);assert.equal(JSON.parse(encoded[1]),(await read('content/studio-tools/layouts-api.md')).replace('{{LAYOUTS}}','读取 /studio/api/layouts 获取全部27套构图。'),'Wiki/agent documentation drift'); +console.log('Studio content, validation and documentation contracts agree'); diff --git a/scripts/export-studio-series.cjs b/scripts/export-studio-series.cjs index cb2a8aa..02c43e7 100644 --- a/scripts/export-studio-series.cjs +++ b/scripts/export-studio-series.cjs @@ -25,7 +25,7 @@ const assert=require('node:assert/strict'); for(const i of m.images){assert.equal(new URL(i.src).pathname,'/api/preview');assert.equal(new URL(i.src).searchParams.get('profile'),'export');assert.ok(i.width>=i.displayWidth*i.zoom&&i.height>=i.displayHeight*i.zoom,'Source image too small for crop/zoom')} // Record actual glyph-rendering fonts, including the CJK fallback used by Chromium. const cdp=await context.newCDPSession(page);await cdp.send('DOM.enable');await cdp.send('CSS.enable');const root=await cdp.send('DOM.getDocument'),nodes=await cdp.send('DOM.querySelectorAll',{nodeId:root.root.nodeId,selector:'.native-copy'}),fonts=[]; - for(const nodeId of nodes.nodeIds){const f=await cdp.send('CSS.getPlatformFontsForNode',{nodeId});fonts.push(f.fonts);assert.ok(f.fonts.length,'No rendered fonts')} + for(const nodeId of nodes.nodeIds){const text=await cdp.send('DOM.getOuterHTML',{nodeId});if(!text.outerHTML.replace(/<[^>]*>/g,'').trim())continue;const f=await cdp.send('CSS.getPlatformFontsForNode',{nodeId});fonts.push(f.fonts);assert.ok(f.fonts.length,'No rendered fonts')} await cdp.detach();const bytes=await page.locator('article.native-layout').screenshot({path:dir+'/'+p.filename,animations:'disabled'}),meta=await sharp(bytes).metadata();assert.equal(meta.width,p.width);assert.equal(meta.height,p.height);evidence.files.push({...p,bytes:bytes.length,sha256:createHash('sha256').update(bytes).digest('hex'),fonts,metrics:m}); } assert.equal((await api('/api/studio/series/'+id)).design.revision,plan.revision,'Revision changed during export');assert.deepEqual(evidence.errors,[]); diff --git a/scripts/publish-studio-library.mjs b/scripts/publish-studio-library.mjs index 0076752..e76c4b3 100644 --- a/scripts/publish-studio-library.mjs +++ b/scripts/publish-studio-library.mjs @@ -10,6 +10,7 @@ async function api(path,body,method=body?'POST':'GET'){ return response.json(); } const capability=await fetch(base+'/api/studio/series?agent_mode=True');if(!capability.ok||!(await capability.text()).includes('schemaVersion 2'))throw Error('Series API is not deployed; refusing to publish future documentation'); +const studioCapability=await api('/studio/api/layouts');if(studioCapability.seriesDocumentVersion!==1)throw Error('Studio renderer is not deployed; refusing to publish future documentation'); const canonical='8eb8c76500580f7a4b56ba3c',legacy='9ebd8f78d54b4b9db741b4e8'; const {entry:current,tags}=await api('/api/notes/'+canonical),{entry:old}=await api('/api/notes/'+legacy); // Snapshot only non-secret editorial state. Retain the first backup across repeat publication. diff --git a/scripts/save-studio-series.mjs b/scripts/save-studio-series.mjs index e7962d8..ef0897a 100644 --- a/scripts/save-studio-series.mjs +++ b/scripts/save-studio-series.mjs @@ -12,6 +12,6 @@ if(state.pending)throw Error('Previous request outcome unknown; reconcile '+stat const save=()=>writeFile(statePath,JSON.stringify(state,null,2)); if(!state.assetId){state.pending='upload';await save();const form=new FormData();form.set('kind','image');form.set('assetOnly','true');form.append('files',new Blob([await readFile(image)],{type:'image/png'}),'ginkgo-master.png');const r=await fetch(base+'/api/upload',{method:'POST',body:form});if(!r.ok)throw Error('Upload failed: '+r.status);const uploaded=await r.json();state.assetId=uploaded.assets[0];delete state.pending;await save()} const body=JSON.parse(await readFile(input,'utf8')),source=JSON.parse(await readFile(provenance,'utf8')); -body.document.sources=[{assetId:state.assetId,...source}];for(const page of body.document.pages)page.parameters.images.I01={...page.parameters.images.I01,assetId:state.assetId}; +body.document.sources=[{...source,assetId:state.assetId}];for(const page of body.document.pages)page.parameters.images.I01={...page.parameters.images.I01,assetId:state.assetId}; await writeFile(dir+'/series-request.json',JSON.stringify(body,null,2));state.pending='create';await save(); const r=await fetch(base+'/api/studio/series',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(body)});if(!r.ok)throw Error('Create failed: '+r.status+' '+await r.text());const {design}=await r.json();state.designId=design.id;delete state.pending;await save();await writeFile(dir+'/design.json',JSON.stringify(design,null,2));console.log(JSON.stringify({id:design.id,url:base+design.url,revision:design.revision,pages:design.document.pages.length}));