From 7358d3cbf0bc46c830f55e76e2ef578ead862f19 Mon Sep 17 00:00:00 2001
From: wuli666 <421774554@qq.com>
Date: Sun, 8 Nov 2026 12:12:34 +0800
Subject: [PATCH 01/61] [bugfix] providers: treat chatgpt-image models as
gpt-image (#221)
## summary
- Match chatgpt-image-* model ids in the openai-gpt-image profile.
Image tools stop sending response_format, which OpenAI rejects
for these models, and reference edits use image[] parts with the
documented 16-image limit.
- Parametrize the profile and adapter tests over gpt-image-1 and
chatgpt-image-latest.
## validation
- pytest tests/test_openai_images.py: 16 passed; the two new
chatgpt-image-latest cases fail without the fix.
- pytest tests: 1098 passed, 6 skipped.
- lint-imports: 4 kept; generate_contracts.py --check: verified.
- npm test: 675 passed.
Fixes: #219
---
packages/core/src/opendirector/domain/input_rules.py | 5 +++--
tests/test_openai_images.py | 11 +++++++----
2 files changed, 10 insertions(+), 6 deletions(-)
diff --git a/packages/core/src/opendirector/domain/input_rules.py b/packages/core/src/opendirector/domain/input_rules.py
index eb618ee2b..5989181c7 100644
--- a/packages/core/src/opendirector/domain/input_rules.py
+++ b/packages/core/src/opendirector/domain/input_rules.py
@@ -95,8 +95,9 @@ def _adapter_rules(config):
# Self-hosted vLLM-Omni text-to-image: it draws from the prompt alone, so
# documents are inlined as text and reference images are not accepted.
rules.update(profile='vllm-omni-image', allowedKinds=['text'], maxImages=0)
- if kind == 'image' and config.get('protocol') in {None, 'openai'} and name.startswith('gpt-image'):
- # OpenAI gpt-image: documented text-to-image plus reference editing with at
+ if kind == 'image' and config.get('protocol') in {None, 'openai'} and name.startswith(('gpt-image', 'chatgpt-image')):
+ # OpenAI gpt-image (and the chatgpt-image-* aliases on the same Images API):
+ # documented text-to-image plus reference editing with at
# most 16 images, each under 25 MB and under 50 MB for the whole request.
rules.update(profile='openai-gpt-image', allowedKinds=['text', 'image'], maxImages=16,
imageBytes=25 * 1024 * 1024, requestBytes=50 * 1024 * 1024)
diff --git a/tests/test_openai_images.py b/tests/test_openai_images.py
index ebc5471cb..3d9e1be67 100644
--- a/tests/test_openai_images.py
+++ b/tests/test_openai_images.py
@@ -33,8 +33,9 @@ def png():
return out.getvalue()
-def test_gpt_image_profile_declares_the_documented_limits():
- rules = input_rules(GPT_IMAGE)
+@pytest.mark.parametrize('model', ['gpt-image-1', 'chatgpt-image-latest'])
+def test_gpt_image_profile_declares_the_documented_limits(model):
+ rules = input_rules({**GPT_IMAGE, 'modelId': model})
assert rules['profile'] == 'openai-gpt-image'
assert rules['allowedKinds'] == ['text', 'image'] and rules['maxImages'] == 16
assert rules['imageBytes'] == 25 * 1024 * 1024 and rules['requestBytes'] == 50 * 1024 * 1024
@@ -44,8 +45,10 @@ def test_gpt_image_profile_declares_the_documented_limits():
assert input_rules({**GPT_IMAGE, 'kind': 'video'})['profile'] != 'openai-gpt-image'
-def test_adapter_drops_response_format_only_for_gpt_image():
- adapter = adapter_for(GPT_IMAGE)
+@pytest.mark.parametrize('model', ['gpt-image-1', 'chatgpt-image-latest'])
+def test_adapter_drops_response_format_only_for_gpt_image(model):
+ # chatgpt-image-* rejects `response_format` exactly like gpt-image (#219).
+ adapter = adapter_for({**GPT_IMAGE, 'modelId': model})
assert isinstance(adapter, OpenAIImages) and adapter.response_format is False
assert adapter.reference_field == 'image[]' and adapter.max_images == 16
assert adapter.capabilities == {'image.generate', 'image.edit', 'image.cutout'}
From abf3db37d0e07ce1c510c511a94a16bffe2d7285 Mon Sep 17 00:00:00 2001
From: Hongsheng Liu
Date: Sun, 8 Nov 2026 14:28:31 +0800
Subject: [PATCH 02/61] [refactor] projects: split oversized storage and tool
modules (#217)
## summary
- Split creation project storage into commit documents, catalog scans,
commit-log reads, and publication. Lifecycle commands stay on
CreationProjects.
- Keep command routing in application.creation_commands. execute()
still delegates there and does not import application services.
- Split canvas tool recipes into context, image edits, segmentation,
and video. The catalog still exports TOOLS, Source, ToolContext,
Output, and select_image_objects.
- Point storage tests at the module that now owns each patched helper.
## validation
- lint-imports kept all four layer contracts.
- pytest on creation, tool, agent, canvas-source, library, and moss
modules: 679 passed, 3 skipped.
- test_rejects_removed_runtime_and_invalid_selection_before_acceptance
also fails on main in this environment with 503 because the bundled
agent CLI is not installed. The full tests tree was not run.
Fixes: #177
Co-authored-by: Cursor Agent
---
.../opendirector/application/tool_context.py | 195 ++++
.../application/tool_image_edits.py | 254 +++++
.../application/tool_image_segments.py | 113 +++
.../application/tool_operations.py | 808 +---------------
.../application/tool_video_recipes.py | 212 +++++
.../infrastructure/creation_catalog.py | 187 ++++
.../infrastructure/creation_commit_log.py | 376 ++++++++
.../infrastructure/creation_projects.py | 897 +-----------------
.../infrastructure/creation_publication.py | 252 +++++
.../infrastructure/creation_records.py | 119 +++
tests/test_creation_storage.py | 24 +-
11 files changed, 1757 insertions(+), 1680 deletions(-)
create mode 100644 packages/core/src/opendirector/application/tool_context.py
create mode 100644 packages/core/src/opendirector/application/tool_image_edits.py
create mode 100644 packages/core/src/opendirector/application/tool_image_segments.py
create mode 100644 packages/core/src/opendirector/application/tool_video_recipes.py
create mode 100644 packages/core/src/opendirector/infrastructure/creation_catalog.py
create mode 100644 packages/core/src/opendirector/infrastructure/creation_commit_log.py
create mode 100644 packages/core/src/opendirector/infrastructure/creation_publication.py
create mode 100644 packages/core/src/opendirector/infrastructure/creation_records.py
diff --git a/packages/core/src/opendirector/application/tool_context.py b/packages/core/src/opendirector/application/tool_context.py
new file mode 100644
index 000000000..703609d36
--- /dev/null
+++ b/packages/core/src/opendirector/application/tool_context.py
@@ -0,0 +1,195 @@
+"""Inputs and model capabilities a canvas tool recipe may use.
+
+Recipes never see a model name, protocol, or endpoint. The context serves each
+capability through whichever configured model offers it.
+"""
+import io
+import math
+import re
+from dataclasses import dataclass
+
+from PIL import Image
+
+from opendirector.domain.capabilities import (
+ ChatRequest, CutoutRequest, DepthRequest, ImageRequest, SegmentRequest, TrackRequest,
+ Tracks, VideoEditRequest, VideoRequest,
+)
+from opendirector.domain.projects import ProjectError
+from opendirector.media import processing as media
+
+
+@dataclass(frozen=True)
+class Source:
+ kind: str
+ data: bytes
+ name: str
+
+@dataclass(frozen=True)
+class Output:
+ kind: str
+ data: bytes
+ suffix: str
+ title: str
+
+class ToolContext:
+ """What a recipe may use: inputs, model capabilities and progress reporting."""
+
+ def __init__(self, *, sources, mask, boxes, parameters, image_model, video_model, progress, video_submitted=None, cutout_model=None,
+ edit_model=None, edit_seconds=(4.0, 15.0), chat_model=None, segment_model=None, track_model=None,
+ edit_keeps_layout=True, annotation=None, edit_max_images=1, segment_available=False, depth_model=None):
+ self.sources: list[Source] = sources
+ self.mask: bytes | None = mask
+ self.annotation: bytes | None = annotation
+ self.edit_max_images = edit_max_images
+ self.segment_available = segment_available
+ self.boxes: list[dict] = boxes
+ self.parameters: dict = parameters
+ self._image, self._video, self._cutout, self._edit = image_model, video_model, cutout_model, edit_model
+ self._segment, self._track, self._depth = segment_model, track_model, depth_model
+ # img2img models redraw in place by strength; instruction editors recompose the picture.
+ self.edit_keeps_layout = edit_keeps_layout
+ # Shortest and longest clip one redraw accepts; longer sources are processed piecewise.
+ self.edit_seconds = edit_seconds
+ # Optional: a chat model only improves prompts; tools never require it.
+ self._chat = chat_model
+ self._progress, self._video_submitted = progress, video_submitted
+
+ def text(self, key, default=''):
+ value = self.parameters.get(key, default)
+ return value.strip() if isinstance(value, str) else default
+
+ def number(self, key, default, low=None, high=None):
+ value = self.parameters.get(key, default)
+ if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
+ raise ProjectError(f'参数 {key} 无效。', 422)
+ if (low is not None and value < low) or (high is not None and value > high):
+ raise ProjectError(f'参数 {key} 超出范围。', 422)
+ return value
+
+ def choice(self, key, options, default=None):
+ value = self.parameters.get(key, default)
+ if value not in options:
+ raise ProjectError(f'参数 {key} 不在可选范围内。', 422)
+ return value
+
+ async def progress(self, message):
+ await self._progress(message)
+
+ async def edit(self, image: Image.Image, prompt: str, strength: float, *, references=()) -> Image.Image:
+ """Image-to-image at the source's aspect; the result is resampled back to the source size."""
+ result = await self._image(ImageRequest(prompt=prompt, width=image.width, height=image.height,
+ image=media.rgb_png(image), strength=strength, references=tuple(references)))
+ return media.resize(media.open_image(result.data), image.width, image.height)
+
+ async def reframe(self, image: Image.Image, width: int, height: int, prompt: str) -> Image.Image:
+ """An instruction edit of image rendered on a width x height frame."""
+ result = await self._image(ImageRequest(prompt=prompt, width=width, height=height, image=media.rgb_png(image)))
+ return media.resize(media.open_image(result.data), width, height)
+
+ async def cutout(self, image: Image.Image, subject: str = '') -> Image.Image:
+ """The subject on transparency, at the source size."""
+ result = await self._cutout(CutoutRequest(image=media.rgb_png(image), width=image.width, height=image.height, subject=subject))
+ return media.resize(media.open_image(result.data), image.width, image.height)
+
+ async def segment(self, image: Image.Image, concept: str = '', boxes=()) -> list[tuple[Image.Image, float, tuple]]:
+ """Instances of an English concept or of exemplar boxes: (mask at the image size, score, box)."""
+ segments = await self._segment(SegmentRequest(image=media.rgb_png(image), concept=concept, boxes=tuple(boxes)))
+ return [(media.resize(media.open_image(item.mask).convert('L'), image.width, image.height), item.score, item.box)
+ for item in segments]
+
+ async def track(self, clip: bytes, concepts: tuple[str, ...]) -> Tracks:
+ return await self._track(TrackRequest(video=clip, concepts=concepts))
+
+ async def depth(self, clip: bytes) -> bytes:
+ """A grayscale depth video of clip at its size and rate; near is bright."""
+ return (await self._depth(DepthRequest(video=clip))).data
+
+ async def concepts(self, text: str, default: tuple[str, ...]) -> list[tuple[str, str]]:
+ """(English concept, label) pairs from a comma-separated description; segmentation models read English."""
+ parts = list(dict.fromkeys(item.strip() for item in re.split(r'[,,、;;\n]+', text) if item.strip()))
+ if not parts:
+ return [(CONCEPTS.get(item, item), item) for item in default]
+ pairs = []
+ for part in parts[:16]:
+ english = CONCEPTS.get(part) or (part if part.isascii() else None)
+ if english is None and self._chat is not None:
+ try:
+ english = (await self._chat(ChatRequest(messages=(
+ {'role': 'system', 'content': 'Name the visual object the user describes as a short English noun phrase, '
+ 'such as "red car" or "person". Output only the phrase.'},
+ {'role': 'user', 'content': part + ' /no_think'}), max_tokens=40))).strip().strip('."\'').lower()
+ except ProjectError:
+ english = None
+ if not english or not english.isascii():
+ raise ProjectError(f'无法识别「{part}」,请改用英文描述,或在“模型接入”中添加对话模型以自动翻译。', 422)
+ pairs.append((english, part))
+ return pairs
+
+ async def english(self, text: str) -> str:
+ """Video models render non-English prompt text as burnt-in subtitles; translate when a chat model is connected."""
+ if not text or text.isascii() or self._chat is None:
+ return text
+ try:
+ translated = await self._chat(ChatRequest(messages=(
+ {'role': 'system', 'content': 'Translate the user text into concise English for a video generation prompt. '
+ 'Output only the translation.'},
+ {'role': 'user', 'content': text + ' /no_think'}), max_tokens=400))
+ except ProjectError:
+ return text
+ return translated.strip() or text
+
+ async def video_prompt(self, user: str, instruction: str) -> str:
+ user = await self.english(user)
+ return f'{user}. {instruction}' if user else instruction
+
+ async def redraw(self, clip: bytes, seconds: float, width: int, height: int, prompt: str, picture=None, sound=None) -> bytes:
+ result = await self._edit(VideoEditRequest(prompt=f'{prompt} {CLEAN_PICTURE}', source=clip, seconds=seconds, width=width,
+ height=height, picture=picture, sound=sound, avoid=NO_TEXT), self._video_submitted)
+ return result.data
+
+ async def video_from_frame(self, frame: Image.Image, prompt: str, seconds: float) -> bytes:
+ ratio = frame.width / frame.height
+ aspect = min(('16:9', '9:16', '1:1', '4:3', '3:4'), key=lambda item: abs(eval_ratio(item) - ratio))
+ frame = media.scale_to_long_edge(frame, 1280) if max(frame.size) > 1280 else frame
+ result = await self._video(VideoRequest(prompt=f'{prompt} {CLEAN_PICTURE}', seconds=seconds, aspect_ratio=aspect,
+ first_frame=media.rgb_png(frame), avoid=NO_TEXT),
+ self._video_submitted)
+ return result.data
+
+# Common subjects map to SAM 3 concepts without a chat model; other words are translated.
+CONCEPTS = {
+ '人': 'person', '人物': 'person', '人像': 'person', '人群': 'person', '主体': 'person', '男人': 'man', '女人': 'woman',
+ '小孩': 'child', '孩子': 'child', '儿童': 'child', '脸': 'face', '手': 'hand', '头发': 'hair',
+ '动物': 'animal', '猫': 'cat', '狗': 'dog', '鸟': 'bird', '马': 'horse', '鱼': 'fish',
+ '车': 'car', '汽车': 'car', '车辆': 'vehicle', '交通工具': 'vehicle', '自行车': 'bicycle', '摩托车': 'motorcycle',
+ '船': 'boat', '飞机': 'airplane', '树': 'tree', '花': 'flower', '植物': 'plant', '建筑': 'building', '房子': 'house',
+ '天空': 'sky', '桌子': 'table', '椅子': 'chair', '沙发': 'sofa', '家具': 'furniture', '杯子': 'cup', '瓶子': 'bottle',
+ '包': 'bag', '鞋': 'shoe', '衣服': 'clothing', '帽子': 'hat', '手机': 'phone', '电脑': 'computer', '食物': 'food',
+ '商品': 'product', '产品': 'product', '文字': 'text', '标志': 'logo',
+}
+
+# Naming text in a positive prompt invites it; the negative prompt carries the exclusion.
+CLEAN_PICTURE = 'Clean picture.'
+
+NO_TEXT = 'subtitles, captions, on-screen text, letters, words, watermark, logo'
+
+def eval_ratio(text):
+ width, height = text.split(':')
+ return int(width) / int(height)
+
+def image_output(image: Image.Image, title: str) -> Output:
+ data = media.png(image)
+ if len(data) > 48 * 1024 * 1024:
+ # Very large renders are stored as high-quality JPEG to stay under the asset limit.
+ buffer = io.BytesIO()
+ image.convert('RGB').save(buffer, 'JPEG', quality=94)
+ return Output('image', buffer.getvalue(), 'jpg', title)
+ return Output('image', data, 'png', title)
+
+def _source_image(ctx: ToolContext, index=0) -> Image.Image:
+ if len(ctx.sources) <= index or ctx.sources[index].kind != 'image':
+ raise ProjectError('请提供图片素材。', 422)
+ return media.open_image(ctx.sources[index].data)
+
+def _with(prompt: str, instruction: str) -> str:
+ return f'{prompt}。{instruction}' if prompt else instruction
diff --git a/packages/core/src/opendirector/application/tool_image_edits.py b/packages/core/src/opendirector/application/tool_image_edits.py
new file mode 100644
index 000000000..75976817d
--- /dev/null
+++ b/packages/core/src/opendirector/application/tool_image_edits.py
@@ -0,0 +1,254 @@
+"""Image edit recipes: reframing, cleanup, presets, and poster motion."""
+import json
+from dataclasses import dataclass
+
+from PIL import Image
+
+from opendirector.application.tool_context import Output, ToolContext, _source_image, _with, image_output
+from opendirector.domain.projects import ProjectError
+from opendirector.media import processing as media
+
+
+def _placement(pads, width, height) -> str:
+ """Where the original sits in the extended frame, and which sides grow, in words."""
+ left, top, right, bottom = pads
+ total_width, total_height = width + left + right, height + top + bottom
+ horizontal = '左侧' if not left and right else '右侧' if left and not right else ''
+ vertical = '上方' if not top and bottom else '下方' if top and not bottom else ''
+ where = f'{vertical}{horizontal}'.replace('上方左侧', '左上角').replace('上方右侧', '右上角') \
+ .replace('下方左侧', '左下角').replace('下方右侧', '右下角') or '中央'
+ sides = '、'.join(name for name, pad in (('左侧', left), ('上方', top), ('右侧', right), ('下方', bottom)) if pad)
+ return (f'原画面约占新画面宽度的 {width / total_width:.0%}、高度的 {height / total_height:.0%},位于新画面的{where},'
+ f'在{sides}新增与原场景连续的内容')
+
+async def _extend(ctx: ToolContext, image: Image.Image, pads, prompt: str) -> Image.Image:
+ """Outpainting: soft border, image-to-image, original pixels kept inside a feathered seam.
+
+ Instruction editors ignore strength and recompose a padded canvas instead of
+ filling it, so they are asked to pull the camera back over the original.
+ """
+ if not ctx.edit_keeps_layout:
+ await ctx.progress('正在扩展画面')
+ width, height = image.width + pads[0] + pads[2], image.height + pads[1] + pads[3]
+ return await ctx.reframe(image, width, height, _with(prompt, (
+ f'镜头拉远,扩展画面:{_placement(pads, image.width, image.height)}。保持原图中的人物、物体、服饰、场景、色调与光线完全一致,'
+ '延续原有的透视与风格,画面完整自然,不要边框、白边或拼接痕迹')))
+ canvas, _ = media.extend_canvas(image, *pads)
+ await ctx.progress('正在扩展画面')
+ drawn = await ctx.edit(canvas, _with(prompt, '自然延展画面四周,与原图内容、风格、透视和光线保持一致,无边框无拼接痕迹'), 0.9)
+ # The redraw shifts tone slightly; a wide ramp inside the original hides the seam.
+ inset = max(8, min(image.size) // 8)
+ left, top, right, bottom = pads
+ keep = (left + (inset if left else 0), top + (inset if top else 0),
+ left + image.width - (inset if right else 0), top + image.height - (inset if bottom else 0))
+ seam = Image.new('L', canvas.size, 255)
+ seam.paste(0, keep)
+ return media.blend(canvas, drawn, media.feather(seam, inset / 2))
+
+async def smart_edit(ctx: ToolContext):
+ image = _source_image(ctx)
+ mode = ctx.choice('editMode', ('annotation', 'selection', 'combined'), 'combined')
+ if mode == 'selection' and not ctx.mask:
+ raise ProjectError('请先涂抹或识别需要修改的区域。', 422)
+ prompt = ctx.text('prompt')
+ notes = []
+ if mode != 'selection':
+ try:
+ document = json.loads(ctx.parameters.get('annotationDocument') or '{}')
+ notes = [stroke.get('text', '').strip() for stroke in document.get('strokes', []) if stroke.get('tool') == 'text']
+ except (ValueError, AttributeError):
+ pass
+ instruction = ';'.join(item for item in [prompt, *notes] if item)
+ if not instruction:
+ raise ProjectError('请描述要如何修改图片。', 422)
+ await ctx.progress('正在按描述改图')
+ input_image, references = image, ()
+ if mode != 'selection' and ctx.annotation:
+ marked = media.open_image(ctx.annotation)
+ if marked.size != image.size:
+ raise ProjectError('标注图片尺寸必须与原图一致。', 422)
+ if ctx.edit_max_images > 1:
+ references = (media.rgb_png(marked),)
+ instruction += '。第二张图是第一张图上的编辑标记,请根据标记理解位置与意图'
+ else:
+ input_image = marked
+ instruction += '。图上的笔画、箭头与文字是编辑指示'
+ instruction += ',完成修改后移除这些辅助标记'
+ edited = await ctx.edit(input_image, instruction + '。保持未提及的内容不变', 0.78, references=references)
+ if mode != 'annotation' and ctx.mask:
+ # A selection is an exact editing boundary: pixels outside it stay original.
+ edited = media.blend(image, edited, media.mask_from(ctx.mask, image.size))
+ return [image_output(edited, '智能改图')]
+
+async def outpaint(ctx: ToolContext):
+ image = _source_image(ctx)
+ sides = [ctx.number(key, 0, 0, 4) for key in ('left', 'top', 'right', 'bottom')]
+ if not any(sides):
+ raise ProjectError('请至少向一个方向扩展。', 422)
+ pads = [round(sides[0] * image.width), round(sides[1] * image.height), round(sides[2] * image.width), round(sides[3] * image.height)]
+ result = await _extend(ctx, image, pads, ctx.text('prompt'))
+ width, height = ctx.parameters.get('outputWidth'), ctx.parameters.get('outputHeight')
+ if isinstance(width, (int, float)) and isinstance(height, (int, float)) and width > 0 and height > 0:
+ result = media.resize(result, int(width), int(height))
+ return [image_output(result, '扩图')]
+
+HD_EDGES = {'2K': 2048, '4K': 4096, '8K': 8192}
+
+async def image_hd(ctx: ToolContext):
+ outputs = []
+ edge = HD_EDGES[ctx.choice('resolution', HD_EDGES, '4K')]
+ pro = ctx.choice('kind', ('normal', 'pro'), 'normal') == 'pro'
+ for index, source in enumerate(ctx.sources):
+ image = media.open_image(source.data)
+ if pro:
+ await ctx.progress(f'正在增强细节({index + 1}/{len(ctx.sources)})')
+ detail = ctx.number('detailStrength', 0.5, 0.01, 1)
+ base = media.scale_to_long_edge(image, 1536) if max(image.size) > 1536 else image
+ image = await ctx.edit(base, '高清摄影,细节丰富,纹理锐利清晰,保持构图、主体和颜色完全不变', 0.12 + 0.3 * detail)
+ await ctx.progress(f'正在放大到 {edge}px')
+ outputs.append(image_output(media.scale_to_long_edge(image, edge), f'超清 {ctx.parameters.get("resolution", "4K")}'))
+ return outputs
+
+async def inpainting_remove(ctx: ToolContext):
+ image = _source_image(ctx)
+ if not ctx.mask:
+ raise ProjectError('请先涂抹需要消除的区域。', 422)
+ mask = media.mask_from(ctx.mask, image.size)
+ await ctx.progress('正在消除并填补')
+ drawn = await ctx.edit(media.soften_region(image, mask), '移除涂抹区域中的物体与文字,用周围环境自然填补,画面干净完整', 0.8)
+ return [image_output(media.blend(image, drawn, media.feather(mask, max(3, min(image.size) / 120))), '消除')]
+
+def _yaw_text(yaw):
+ names = ['正面', '右前方', '右侧面', '右后方', '背面', '左后方', '左侧面', '左前方']
+ return names[round((yaw % 360) / 45) % 8]
+
+async def view_control(ctx: ToolContext):
+ image = _source_image(ctx)
+ yaw = ctx.number('yaw', 0, -360, 360)
+ pitch = ctx.number('pitch', 0, -90, 90)
+ distance = ctx.parameters.get('distancePreset') or ctx.parameters.get('distance') or 'standard'
+ shot = {'near': '近景特写', 'standard': '中景', 'far': '远景全身'}.get(distance, '中景')
+ angle = '俯视' if pitch > 20 else '仰视' if pitch < -10 else '平视'
+ await ctx.progress('正在生成新视角')
+ edited = await ctx.edit(image, _with(ctx.text('prompt'), f'同一主体从{_yaw_text(yaw)}{angle}角度拍摄的{shot},'
+ '保持主体外观、服装、颜色和场景风格完全一致'), 0.8)
+ return [image_output(edited, f'多角度 · {_yaw_text(yaw)}')]
+
+async def lighting(ctx: ToolContext):
+ image = _source_image(ctx)
+ yaw = ctx.number('yaw', 0, -360, 360)
+ pitch = ctx.number('pitch', 30, -90, 90)
+ # The lighting editor sends brightnessPercent; the catalog field is brightness.
+ brightness = ctx.number('brightnessPercent' if 'brightnessPercent' in ctx.parameters else 'brightness', 60, 0, 100)
+ texture = '柔和漫射' if ctx.parameters.get('texture', 'soft') == 'soft' else '硬朗强烈'
+ color = ctx.text('lightColor', '#ffffff') or '#ffffff'
+ height = '顶光' if pitch > 50 else '高位' if pitch > 15 else '底光' if pitch < -15 else '平射'
+ level = '明亮' if brightness > 66 else '中等亮度' if brightness > 33 else '昏暗低调'
+ await ctx.progress('正在重新布光')
+ edited = await ctx.edit(image, _with(ctx.text('prompt'), f'重新布光:主光来自{_yaw_text(yaw)}{height},{texture}的光质,'
+ f'光色 {color},整体{level},阴影和高光随光源变化,保持主体和构图不变'), 0.72)
+ return [image_output(edited, '智能打光')]
+
+async def panorama(ctx: ToolContext):
+ image = _source_image(ctx)
+ width = max(image.width, image.height * 2)
+ height = width // 2
+ pads = ((width - image.width) // 2, (height - image.height) // 2)
+ pads = (pads[0], pads[1], width - image.width - pads[0], height - image.height - pads[1])
+ result = await _extend(ctx, image, pads, _with(ctx.text('prompt'), '360度等距柱状投影全景图,左右边缘可无缝衔接'))
+ edge = {'4K': 4096, '2K': 2048}.get(ctx.parameters.get('resolution'), 2048)
+ return [image_output(media.resize(result, edge, edge // 2), '720 全景')]
+
+@dataclass(frozen=True)
+class ImagePreset:
+ title: str
+ prompts: tuple[str, ...]
+ size: tuple[int, int] = (2048, 1152)
+
+PRESETS = {
+ # Written as edit instructions: editing models follow imperatives, not captions.
+ 'three-view': ImagePreset('人物三视图', (
+ '以参考图中的人物为唯一身份依据,生成同一人物的全身三视图设定板。'
+ '横版画面分为三个等宽区域,从左至右严格排列:正面全身、右侧90度全身、背面全身。'
+ '三个视图保持同一身份、年龄、体型、头身比、发型、服装、配色、材质及配饰,衣服结构与细节相互对应。'
+ '全部自然站立、双臂放松,同一高度与地面基线,完整呈现头顶到鞋底,不裁头、不切脚、不遮挡、不重叠。'
+ '若原图仅有半身,依据可见服装合理补全下半身,补全部分在三个视角保持一致。'
+ '保持参考图画风,纯净浅灰背景、均匀柔光、弱透视,无剧情场景、文字、标签、水印、分割线或额外视图。',)),
+ 'face-three-view': ImagePreset('面部三视图', (
+ '以参考图人物的面部为唯一身份依据,生成同一人物的面部三视图参考板。'
+ '超宽横版画面分为三个等宽区域,从左至右严格排列:正面、左侧90度、右侧90度。'
+ '每个视图只呈现完整头部至肩颈,头顶、下巴、耳朵均完整,不出现背面或全身视图。'
+ '保持同一身份、年龄、脸型、骨相、五官比例、肤色、发际线、发型及识别性细节,左右侧面符合真实结构。'
+ '三个头部大小一致、眼睛基线对齐、中性表情、视线随朝向自然变化,面部不被头发遮挡。'
+ '保持参考图画风,纯净浅灰背景、均匀柔光,无美颜改脸、夸张透视、文字、标签、水印或额外人物。',), (2688, 1152)),
+ 'product-three-view': ImagePreset('产品三视图', (
+ '以参考图中的产品为唯一设计依据,生成同一产品的工业设计三视图参考板。'
+ '横版画面分为三个等宽区域,从左至右严格排列:正视图、右侧90度侧视图、后视图。'
+ '采用近正交投影、无广角畸变,同一比例尺、同一高度与底部基线,完整展示产品外轮廓,不裁切、不重叠。'
+ '三个视图保持结构、尺寸关系、材质、颜色、表面纹理、接口、按钮、接缝及标识一致,细节在视角之间符合物理对应关系。'
+ '不可见部位依据已知结构作合理且一致的补全,不增加功能件或改变产品设计。'
+ '产品独立展示,纯白背景、均匀棚拍光,无人物、手、包装道具、剧情场景、说明文字、尺寸标注、水印或额外视图;保留原有品牌标识。',)),
+ 'storyboard': ImagePreset('分镜', ('把镜头拉远成远景建立镜头,完整交代周围环境,主体在画面中较小',
+ '改为中景镜头,主体占画面一半高度,动作清晰',
+ '改为近景镜头,镜头推近到主体胸口以上,突出表情',
+ '改为特写镜头,只拍主体面部或关键细节,背景虚化')),
+ 'multi-camera': ImagePreset('多机位', ('把机位移到主体正前方,平视拍摄',
+ '把机位向左绕到主体左前方约45度,从左侧斜角拍摄,透视随之改变',
+ '把机位向右绕到主体右前方约45度,从右侧斜角拍摄,透视随之改变',
+ '把机位升高到主体上方,高角度俯拍')),
+}
+
+async def image_presets(ctx: ToolContext):
+ image = _source_image(ctx)
+ preset = PRESETS[ctx.choice('preset', PRESETS)]
+ title, prompts = preset.title, preset.prompts
+ outputs = []
+ for index, instruction in enumerate(prompts, 1):
+ await ctx.progress(f'正在生成{title}({index}/{len(prompts)})')
+ edited = await ctx.reframe(image, *preset.size, instruction + ',保持主体外观与风格一致')
+ outputs.append(image_output(edited, f'{title} {index}' if len(prompts) > 1 else title))
+ return outputs
+
+async def multi_size(ctx: ToolContext):
+ image = _source_image(ctx)
+ width = int(ctx.number('outputWidth', image.width, 64, 8192))
+ height = int(ctx.number('outputHeight', image.height, 64, 8192))
+ target, current = width / height, image.width / image.height
+ if abs(target - current) < 0.01:
+ return [image_output(media.resize(image, width, height), f'{width}×{height}')]
+ if target > current:
+ extra = round(image.height * target) - image.width
+ pads = (extra // 2, 0, extra - extra // 2, 0)
+ else:
+ extra = round(image.width / target) - image.height
+ pads = (0, extra // 2, 0, extra - extra // 2)
+ result = await _extend(ctx, image, pads, ctx.text('prompt'))
+ return [image_output(media.resize(result, width, height), f'{width}×{height}')]
+
+async def product_replacement(ctx: ToolContext):
+ scene, product = _source_image(ctx, 0), _source_image(ctx, 1)
+ if not ctx.boxes:
+ raise ProjectError('请先框选商品区域。', 422)
+ box = ctx.boxes[0]
+ x, y, width, height = (int(round(box[key])) for key in ('x', 'y', 'width', 'height'))
+ if width < 8 or height < 8 or x < 0 or y < 0 or x + width > scene.width or y + height > scene.height:
+ raise ProjectError('商品区域超出原图或尺寸不正确。', 422)
+ layer = media.cover_box(product, (x, y, width, height))
+ placed = scene.copy()
+ placed.paste(layer, (x, y), layer)
+ await ctx.progress('正在融合商品与场景')
+ drawn = await ctx.edit(placed, _with(ctx.text('prompt'), '商品自然融入场景,光影、透视和色调一致,保留商品外观和文字'), 0.42)
+ region = Image.new('L', scene.size, 0)
+ region.paste(255, (x, y, x + width, y + height))
+ result = media.blend(scene, drawn, media.feather(region, max(4, min(width, height) / 12)))
+ edge = {'4K': 4096, '2K': 2048}.get(ctx.parameters.get('resolution'))
+ if edge and max(result.size) < edge:
+ result = media.scale_to_long_edge(result, edge)
+ return [image_output(result, '商品替换')]
+
+async def dynamic_poster(ctx: ToolContext):
+ image = _source_image(ctx)
+ await ctx.progress('正在生成动态海报')
+ prompt = await ctx.video_prompt(ctx.text('prompt'), 'The poster comes gently alive with subtle natural motion; the subject and its text stay stable.')
+ data = await ctx.video_from_frame(image, prompt, 5)
+ return [Output('video', data, 'mp4', '动态海报')]
diff --git a/packages/core/src/opendirector/application/tool_image_segments.py b/packages/core/src/opendirector/application/tool_image_segments.py
new file mode 100644
index 000000000..c9384e43b
--- /dev/null
+++ b/packages/core/src/opendirector/application/tool_image_segments.py
@@ -0,0 +1,113 @@
+"""Image segmentation recipes for cutout, layer split, and editor previews."""
+from PIL import Image, ImageChops, ImageFilter
+
+from opendirector.application.tool_context import ToolContext, _source_image, image_output
+from opendirector.domain.projects import ProjectError
+from opendirector.media import processing as media
+
+
+async def cutout(ctx: ToolContext):
+ image = _source_image(ctx)
+ if ctx.mask:
+ await ctx.progress('正在应用选区')
+ alpha = media.mask_from(ctx.mask, image.size)
+ elif ctx.segment_available:
+ found = await select_image_objects(ctx, image, ctx.text('prompt'), ctx.boxes)
+ alpha = Image.new('L', image.size, 0)
+ for mask, _, _, _ in found:
+ alpha = ImageChops.lighter(alpha, mask)
+ else:
+ await ctx.progress('正在识别并抠出主体')
+ lifted = await ctx.cutout(image, ctx.text('prompt'))
+ alpha = lifted.getchannel('A')
+ if alpha.getextrema()[1] < 16:
+ raise ProjectError('没有识别到可抠出的主体,请换一张图或涂抹主体所在区域后重试。', 422)
+ # Keep the original pixels; the model contributes only the matte.
+ result = image.copy()
+ result.putalpha(ImageChops.multiply(alpha, image.getchannel('A')))
+ return [image_output(result, '抠图')]
+
+SMART_LAYERS = ('人物', '动物', '交通工具', '商品', '家具', '植物', '食物', '文字')
+
+def _overlap(box, target):
+ """Intersection over union of two (x0, y0, x1, y1) boxes."""
+ width = max(0.0, min(box[2], target[2]) - max(box[0], target[0]))
+ height = max(0.0, min(box[3], target[3]) - max(box[1], target[1]))
+ inner = width * height
+ union = (box[2] - box[0]) * (box[3] - box[1]) + (target[2] - target[0]) * (target[3] - target[1]) - inner
+ return inner / union if union > 0 else 0.0
+
+def _area(mask: Image.Image) -> int:
+ return mask.histogram()[255]
+
+def _distinct(found, size, limit=16, *, with_scores=False, preserve_order=False):
+ """Highest-scoring instances first; one that mostly repeats a kept layer or is a speck is dropped."""
+ kept = []
+ for mask, score, label in (found if preserve_order else sorted(found, key=lambda item: -item[1])):
+ mask = mask.point(lambda value: 255 if value >= 128 else 0)
+ area = _area(mask)
+ if area < size[0] * size[1] * 0.002:
+ continue
+ if any(_area(ImageChops.multiply(mask, other)) > 0.6 * min(area, other_area) for other, other_area, _, _ in kept):
+ continue
+ kept.append((mask, area, label, score))
+ if len(kept) == limit:
+ break
+ return [(mask, score, label) if with_scores else (mask, label) for mask, _, label, score in kept]
+
+async def select_image_objects(ctx: ToolContext, image: Image.Image, prompt='', boxes=()):
+ """Reusable SAM instances for editor previews and automatic cutout.
+
+ Exemplar boxes can match similar objects elsewhere, so only the best overlapping
+ instance is selected for each user box. No point-prompt semantics are invented.
+ """
+ found = []
+ if boxes:
+ for index, item in enumerate(boxes, 1):
+ target = (item['x'], item['y'], item['x'] + item['width'], item['y'] + item['height'])
+ if target[0] < 0 or target[1] < 0 or target[2] > image.width or target[3] > image.height:
+ raise ProjectError('选框必须位于原图内。', 422)
+ await ctx.progress(f'正在识别框选对象({index}/{len(boxes)})')
+ instances = await ctx.segment(image, boxes=(target,))
+ best = max(instances, key=lambda item: _overlap(item[2], target), default=None)
+ if best is not None and _overlap(best[2], target) >= 0.3:
+ found.append((best[0], best[1], f'对象 {index}'))
+ else:
+ for concept, label in await ctx.concepts(prompt, SMART_LAYERS):
+ await ctx.progress(f'正在识别「{label}」')
+ found += [(mask, score, label) for mask, score, _ in await ctx.segment(image, concept)]
+ return [(mask, score, label, mask.getbbox())
+ for mask, score, label in _distinct(found, image.size, with_scores=True, preserve_order=bool(boxes))]
+
+async def layer_decompose(ctx: ToolContext):
+ image = _source_image(ctx)
+ mode = ctx.choice('mode', ('smart', 'boxes', 'description'), 'smart')
+ if mode == 'boxes' and not ctx.boxes:
+ raise ProjectError('框选拆分需要提供原图中的矩形选区。', 422)
+ text = ctx.text('prompt') if mode == 'description' else ''
+ if mode == 'description' and not text:
+ raise ProjectError('按描述拆分需要填写拆分描述。', 422)
+ found = await select_image_objects(ctx, image, text, ctx.boxes if mode == 'boxes' else ())
+ layers = [(mask, label) for mask, _, label, _ in found]
+ if not layers:
+ raise ProjectError('没有识别到可分离的对象,请换一种描述或框选对象后重试。', 422)
+ holes = Image.new('L', image.size, 0)
+ for mask, _ in layers:
+ holes = ImageChops.lighter(holes, mask)
+ await ctx.progress('正在补全背景')
+ # Without an image editor the background keeps transparent holes where the layers were.
+ grown = holes.filter(ImageFilter.MaxFilter(max(3, (min(image.size) // 100) | 1)))
+ try:
+ drawn = await ctx.edit(media.soften_region(image, grown), '移除画面中被涂抹区域的主体,用周围背景自然补全,画面干净完整', 0.85)
+ background, title = media.blend(image, drawn, media.feather(grown, max(3, min(image.size) / 150))), '背景'
+ except ProjectError:
+ background, title = image.convert('RGBA'), '背景(未补全)'
+ background.putalpha(ImageChops.multiply(ImageChops.invert(holes), background.getchannel('A')))
+ outputs = [image_output(background, title)]
+ alpha = image.convert('RGBA').getchannel('A')
+ for index, (mask, label) in enumerate(layers, 1):
+ # Layers keep the source canvas so stacking them over the background rebuilds the image.
+ layer = image.convert('RGBA')
+ layer.putalpha(ImageChops.multiply(mask, alpha))
+ outputs.append(image_output(layer, f'图层 {index} · {label}'))
+ return outputs
diff --git a/packages/core/src/opendirector/application/tool_operations.py b/packages/core/src/opendirector/application/tool_operations.py
index 28b162b9d..755bc5ccf 100644
--- a/packages/core/src/opendirector/application/tool_operations.py
+++ b/packages/core/src/opendirector/application/tool_operations.py
@@ -4,807 +4,26 @@
them through whichever configured model offers them. Recipes never see a model
name, protocol or endpoint, so swapping or adding models does not touch them.
"""
-
-import io
-import json
-import math
-import re
from dataclasses import dataclass, field
from typing import Awaitable, Callable
-from PIL import Image, ImageChops, ImageFilter
-
-from opendirector.domain.capabilities import (ChatRequest, CutoutRequest, DepthRequest, EditMask, ImageRequest, SegmentRequest, TrackRequest,
- Tracks, VideoEditRequest, VideoRequest)
-from opendirector.domain.projects import ProjectError
-from opendirector.media import processing as media
-from opendirector.media.async_work import blocking
-
-
-@dataclass(frozen=True)
-class Source:
- kind: str
- data: bytes
- name: str
-
-
-@dataclass(frozen=True)
-class Output:
- kind: str
- data: bytes
- suffix: str
- title: str
-
-
-class ToolContext:
- """What a recipe may use: inputs, model capabilities and progress reporting."""
-
- def __init__(self, *, sources, mask, boxes, parameters, image_model, video_model, progress, video_submitted=None, cutout_model=None,
- edit_model=None, edit_seconds=(4.0, 15.0), chat_model=None, segment_model=None, track_model=None,
- edit_keeps_layout=True, annotation=None, edit_max_images=1, segment_available=False, depth_model=None):
- self.sources: list[Source] = sources
- self.mask: bytes | None = mask
- self.annotation: bytes | None = annotation
- self.edit_max_images = edit_max_images
- self.segment_available = segment_available
- self.boxes: list[dict] = boxes
- self.parameters: dict = parameters
- self._image, self._video, self._cutout, self._edit = image_model, video_model, cutout_model, edit_model
- self._segment, self._track, self._depth = segment_model, track_model, depth_model
- # img2img models redraw in place by strength; instruction editors recompose the picture.
- self.edit_keeps_layout = edit_keeps_layout
- # Shortest and longest clip one redraw accepts; longer sources are processed piecewise.
- self.edit_seconds = edit_seconds
- # Optional: a chat model only improves prompts; tools never require it.
- self._chat = chat_model
- self._progress, self._video_submitted = progress, video_submitted
-
- def text(self, key, default=''):
- value = self.parameters.get(key, default)
- return value.strip() if isinstance(value, str) else default
-
- def number(self, key, default, low=None, high=None):
- value = self.parameters.get(key, default)
- if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value):
- raise ProjectError(f'参数 {key} 无效。', 422)
- if (low is not None and value < low) or (high is not None and value > high):
- raise ProjectError(f'参数 {key} 超出范围。', 422)
- return value
-
- def choice(self, key, options, default=None):
- value = self.parameters.get(key, default)
- if value not in options:
- raise ProjectError(f'参数 {key} 不在可选范围内。', 422)
- return value
-
- async def progress(self, message):
- await self._progress(message)
-
- async def edit(self, image: Image.Image, prompt: str, strength: float, *, references=()) -> Image.Image:
- """Image-to-image at the source's aspect; the result is resampled back to the source size."""
- result = await self._image(ImageRequest(prompt=prompt, width=image.width, height=image.height,
- image=media.rgb_png(image), strength=strength, references=tuple(references)))
- return media.resize(media.open_image(result.data), image.width, image.height)
-
- async def reframe(self, image: Image.Image, width: int, height: int, prompt: str) -> Image.Image:
- """An instruction edit of image rendered on a width x height frame."""
- result = await self._image(ImageRequest(prompt=prompt, width=width, height=height, image=media.rgb_png(image)))
- return media.resize(media.open_image(result.data), width, height)
-
- async def cutout(self, image: Image.Image, subject: str = '') -> Image.Image:
- """The subject on transparency, at the source size."""
- result = await self._cutout(CutoutRequest(image=media.rgb_png(image), width=image.width, height=image.height, subject=subject))
- return media.resize(media.open_image(result.data), image.width, image.height)
-
- async def segment(self, image: Image.Image, concept: str = '', boxes=()) -> list[tuple[Image.Image, float, tuple]]:
- """Instances of an English concept or of exemplar boxes: (mask at the image size, score, box)."""
- segments = await self._segment(SegmentRequest(image=media.rgb_png(image), concept=concept, boxes=tuple(boxes)))
- return [(media.resize(media.open_image(item.mask).convert('L'), image.width, image.height), item.score, item.box)
- for item in segments]
-
- async def track(self, clip: bytes, concepts: tuple[str, ...]) -> Tracks:
- return await self._track(TrackRequest(video=clip, concepts=concepts))
-
- async def depth(self, clip: bytes) -> bytes:
- """A grayscale depth video of clip at its size and rate; near is bright."""
- return (await self._depth(DepthRequest(video=clip))).data
-
- async def concepts(self, text: str, default: tuple[str, ...]) -> list[tuple[str, str]]:
- """(English concept, label) pairs from a comma-separated description; segmentation models read English."""
- parts = list(dict.fromkeys(item.strip() for item in re.split(r'[,,、;;\n]+', text) if item.strip()))
- if not parts:
- return [(CONCEPTS.get(item, item), item) for item in default]
- pairs = []
- for part in parts[:16]:
- english = CONCEPTS.get(part) or (part if part.isascii() else None)
- if english is None and self._chat is not None:
- try:
- english = (await self._chat(ChatRequest(messages=(
- {'role': 'system', 'content': 'Name the visual object the user describes as a short English noun phrase, '
- 'such as "red car" or "person". Output only the phrase.'},
- {'role': 'user', 'content': part + ' /no_think'}), max_tokens=40))).strip().strip('."\'').lower()
- except ProjectError:
- english = None
- if not english or not english.isascii():
- raise ProjectError(f'无法识别「{part}」,请改用英文描述,或在“模型接入”中添加对话模型以自动翻译。', 422)
- pairs.append((english, part))
- return pairs
-
- async def english(self, text: str) -> str:
- """Video models render non-English prompt text as burnt-in subtitles; translate when a chat model is connected."""
- if not text or text.isascii() or self._chat is None:
- return text
- try:
- translated = await self._chat(ChatRequest(messages=(
- {'role': 'system', 'content': 'Translate the user text into concise English for a video generation prompt. '
- 'Output only the translation.'},
- {'role': 'user', 'content': text + ' /no_think'}), max_tokens=400))
- except ProjectError:
- return text
- return translated.strip() or text
-
- async def video_prompt(self, user: str, instruction: str) -> str:
- user = await self.english(user)
- return f'{user}. {instruction}' if user else instruction
-
- async def redraw(self, clip: bytes, seconds: float, width: int, height: int, prompt: str, picture=None, sound=None) -> bytes:
- result = await self._edit(VideoEditRequest(prompt=f'{prompt} {CLEAN_PICTURE}', source=clip, seconds=seconds, width=width,
- height=height, picture=picture, sound=sound, avoid=NO_TEXT), self._video_submitted)
- return result.data
-
- async def video_from_frame(self, frame: Image.Image, prompt: str, seconds: float) -> bytes:
- ratio = frame.width / frame.height
- aspect = min(('16:9', '9:16', '1:1', '4:3', '3:4'), key=lambda item: abs(eval_ratio(item) - ratio))
- frame = media.scale_to_long_edge(frame, 1280) if max(frame.size) > 1280 else frame
- result = await self._video(VideoRequest(prompt=f'{prompt} {CLEAN_PICTURE}', seconds=seconds, aspect_ratio=aspect,
- first_frame=media.rgb_png(frame), avoid=NO_TEXT),
- self._video_submitted)
- return result.data
-
-
-# Common subjects map to SAM 3 concepts without a chat model; other words are translated.
-CONCEPTS = {
- '人': 'person', '人物': 'person', '人像': 'person', '人群': 'person', '主体': 'person', '男人': 'man', '女人': 'woman',
- '小孩': 'child', '孩子': 'child', '儿童': 'child', '脸': 'face', '手': 'hand', '头发': 'hair',
- '动物': 'animal', '猫': 'cat', '狗': 'dog', '鸟': 'bird', '马': 'horse', '鱼': 'fish',
- '车': 'car', '汽车': 'car', '车辆': 'vehicle', '交通工具': 'vehicle', '自行车': 'bicycle', '摩托车': 'motorcycle',
- '船': 'boat', '飞机': 'airplane', '树': 'tree', '花': 'flower', '植物': 'plant', '建筑': 'building', '房子': 'house',
- '天空': 'sky', '桌子': 'table', '椅子': 'chair', '沙发': 'sofa', '家具': 'furniture', '杯子': 'cup', '瓶子': 'bottle',
- '包': 'bag', '鞋': 'shoe', '衣服': 'clothing', '帽子': 'hat', '手机': 'phone', '电脑': 'computer', '食物': 'food',
- '商品': 'product', '产品': 'product', '文字': 'text', '标志': 'logo',
-}
-
-
-# Naming text in a positive prompt invites it; the negative prompt carries the exclusion.
-CLEAN_PICTURE = 'Clean picture.'
-NO_TEXT = 'subtitles, captions, on-screen text, letters, words, watermark, logo'
-
-
-def eval_ratio(text):
- width, height = text.split(':')
- return int(width) / int(height)
-
-
-def image_output(image: Image.Image, title: str) -> Output:
- data = media.png(image)
- if len(data) > 48 * 1024 * 1024:
- # Very large renders are stored as high-quality JPEG to stay under the asset limit.
- buffer = io.BytesIO()
- image.convert('RGB').save(buffer, 'JPEG', quality=94)
- return Output('image', buffer.getvalue(), 'jpg', title)
- return Output('image', data, 'png', title)
-
-
-def _source_image(ctx: ToolContext, index=0) -> Image.Image:
- if len(ctx.sources) <= index or ctx.sources[index].kind != 'image':
- raise ProjectError('请提供图片素材。', 422)
- return media.open_image(ctx.sources[index].data)
-
-
-def _with(prompt: str, instruction: str) -> str:
- return f'{prompt}。{instruction}' if prompt else instruction
-
-
-def _placement(pads, width, height) -> str:
- """Where the original sits in the extended frame, and which sides grow, in words."""
- left, top, right, bottom = pads
- total_width, total_height = width + left + right, height + top + bottom
- horizontal = '左侧' if not left and right else '右侧' if left and not right else ''
- vertical = '上方' if not top and bottom else '下方' if top and not bottom else ''
- where = f'{vertical}{horizontal}'.replace('上方左侧', '左上角').replace('上方右侧', '右上角') \
- .replace('下方左侧', '左下角').replace('下方右侧', '右下角') or '中央'
- sides = '、'.join(name for name, pad in (('左侧', left), ('上方', top), ('右侧', right), ('下方', bottom)) if pad)
- return (f'原画面约占新画面宽度的 {width / total_width:.0%}、高度的 {height / total_height:.0%},位于新画面的{where},'
- f'在{sides}新增与原场景连续的内容')
-
-
-async def _extend(ctx: ToolContext, image: Image.Image, pads, prompt: str) -> Image.Image:
- """Outpainting: soft border, image-to-image, original pixels kept inside a feathered seam.
-
- Instruction editors ignore strength and recompose a padded canvas instead of
- filling it, so they are asked to pull the camera back over the original.
- """
- if not ctx.edit_keeps_layout:
- await ctx.progress('正在扩展画面')
- width, height = image.width + pads[0] + pads[2], image.height + pads[1] + pads[3]
- return await ctx.reframe(image, width, height, _with(prompt, (
- f'镜头拉远,扩展画面:{_placement(pads, image.width, image.height)}。保持原图中的人物、物体、服饰、场景、色调与光线完全一致,'
- '延续原有的透视与风格,画面完整自然,不要边框、白边或拼接痕迹')))
- canvas, _ = media.extend_canvas(image, *pads)
- await ctx.progress('正在扩展画面')
- drawn = await ctx.edit(canvas, _with(prompt, '自然延展画面四周,与原图内容、风格、透视和光线保持一致,无边框无拼接痕迹'), 0.9)
- # The redraw shifts tone slightly; a wide ramp inside the original hides the seam.
- inset = max(8, min(image.size) // 8)
- left, top, right, bottom = pads
- keep = (left + (inset if left else 0), top + (inset if top else 0),
- left + image.width - (inset if right else 0), top + image.height - (inset if bottom else 0))
- seam = Image.new('L', canvas.size, 255)
- seam.paste(0, keep)
- return media.blend(canvas, drawn, media.feather(seam, inset / 2))
-
-
-# Image recipes ---------------------------------------------------------------
-
-async def smart_edit(ctx: ToolContext):
- image = _source_image(ctx)
- mode = ctx.choice('editMode', ('annotation', 'selection', 'combined'), 'combined')
- if mode == 'selection' and not ctx.mask:
- raise ProjectError('请先涂抹或识别需要修改的区域。', 422)
- prompt = ctx.text('prompt')
- notes = []
- if mode != 'selection':
- try:
- document = json.loads(ctx.parameters.get('annotationDocument') or '{}')
- notes = [stroke.get('text', '').strip() for stroke in document.get('strokes', []) if stroke.get('tool') == 'text']
- except (ValueError, AttributeError):
- pass
- instruction = ';'.join(item for item in [prompt, *notes] if item)
- if not instruction:
- raise ProjectError('请描述要如何修改图片。', 422)
- await ctx.progress('正在按描述改图')
- input_image, references = image, ()
- if mode != 'selection' and ctx.annotation:
- marked = media.open_image(ctx.annotation)
- if marked.size != image.size:
- raise ProjectError('标注图片尺寸必须与原图一致。', 422)
- if ctx.edit_max_images > 1:
- references = (media.rgb_png(marked),)
- instruction += '。第二张图是第一张图上的编辑标记,请根据标记理解位置与意图'
- else:
- input_image = marked
- instruction += '。图上的笔画、箭头与文字是编辑指示'
- instruction += ',完成修改后移除这些辅助标记'
- edited = await ctx.edit(input_image, instruction + '。保持未提及的内容不变', 0.78, references=references)
- if mode != 'annotation' and ctx.mask:
- # A selection is an exact editing boundary: pixels outside it stay original.
- edited = media.blend(image, edited, media.mask_from(ctx.mask, image.size))
- return [image_output(edited, '智能改图')]
-
-
-async def outpaint(ctx: ToolContext):
- image = _source_image(ctx)
- sides = [ctx.number(key, 0, 0, 4) for key in ('left', 'top', 'right', 'bottom')]
- if not any(sides):
- raise ProjectError('请至少向一个方向扩展。', 422)
- pads = [round(sides[0] * image.width), round(sides[1] * image.height), round(sides[2] * image.width), round(sides[3] * image.height)]
- result = await _extend(ctx, image, pads, ctx.text('prompt'))
- width, height = ctx.parameters.get('outputWidth'), ctx.parameters.get('outputHeight')
- if isinstance(width, (int, float)) and isinstance(height, (int, float)) and width > 0 and height > 0:
- result = media.resize(result, int(width), int(height))
- return [image_output(result, '扩图')]
-
-
-HD_EDGES = {'2K': 2048, '4K': 4096, '8K': 8192}
-
-
-async def image_hd(ctx: ToolContext):
- outputs = []
- edge = HD_EDGES[ctx.choice('resolution', HD_EDGES, '4K')]
- pro = ctx.choice('kind', ('normal', 'pro'), 'normal') == 'pro'
- for index, source in enumerate(ctx.sources):
- image = media.open_image(source.data)
- if pro:
- await ctx.progress(f'正在增强细节({index + 1}/{len(ctx.sources)})')
- detail = ctx.number('detailStrength', 0.5, 0.01, 1)
- base = media.scale_to_long_edge(image, 1536) if max(image.size) > 1536 else image
- image = await ctx.edit(base, '高清摄影,细节丰富,纹理锐利清晰,保持构图、主体和颜色完全不变', 0.12 + 0.3 * detail)
- await ctx.progress(f'正在放大到 {edge}px')
- outputs.append(image_output(media.scale_to_long_edge(image, edge), f'超清 {ctx.parameters.get("resolution", "4K")}'))
- return outputs
-
-
-async def cutout(ctx: ToolContext):
- image = _source_image(ctx)
- if ctx.mask:
- await ctx.progress('正在应用选区')
- alpha = media.mask_from(ctx.mask, image.size)
- elif ctx.segment_available:
- found = await select_image_objects(ctx, image, ctx.text('prompt'), ctx.boxes)
- alpha = Image.new('L', image.size, 0)
- for mask, _, _, _ in found:
- alpha = ImageChops.lighter(alpha, mask)
- else:
- await ctx.progress('正在识别并抠出主体')
- lifted = await ctx.cutout(image, ctx.text('prompt'))
- alpha = lifted.getchannel('A')
- if alpha.getextrema()[1] < 16:
- raise ProjectError('没有识别到可抠出的主体,请换一张图或涂抹主体所在区域后重试。', 422)
- # Keep the original pixels; the model contributes only the matte.
- result = image.copy()
- result.putalpha(ImageChops.multiply(alpha, image.getchannel('A')))
- return [image_output(result, '抠图')]
-
-
-SMART_LAYERS = ('人物', '动物', '交通工具', '商品', '家具', '植物', '食物', '文字')
-
-
-def _overlap(box, target):
- """Intersection over union of two (x0, y0, x1, y1) boxes."""
- width = max(0.0, min(box[2], target[2]) - max(box[0], target[0]))
- height = max(0.0, min(box[3], target[3]) - max(box[1], target[1]))
- inner = width * height
- union = (box[2] - box[0]) * (box[3] - box[1]) + (target[2] - target[0]) * (target[3] - target[1]) - inner
- return inner / union if union > 0 else 0.0
-
-
-def _area(mask: Image.Image) -> int:
- return mask.histogram()[255]
-
-
-def _distinct(found, size, limit=16, *, with_scores=False, preserve_order=False):
- """Highest-scoring instances first; one that mostly repeats a kept layer or is a speck is dropped."""
- kept = []
- for mask, score, label in (found if preserve_order else sorted(found, key=lambda item: -item[1])):
- mask = mask.point(lambda value: 255 if value >= 128 else 0)
- area = _area(mask)
- if area < size[0] * size[1] * 0.002:
- continue
- if any(_area(ImageChops.multiply(mask, other)) > 0.6 * min(area, other_area) for other, other_area, _, _ in kept):
- continue
- kept.append((mask, area, label, score))
- if len(kept) == limit:
- break
- return [(mask, score, label) if with_scores else (mask, label) for mask, _, label, score in kept]
-
-
-async def select_image_objects(ctx: ToolContext, image: Image.Image, prompt='', boxes=()):
- """Reusable SAM instances for editor previews and automatic cutout.
-
- Exemplar boxes can match similar objects elsewhere, so only the best overlapping
- instance is selected for each user box. No point-prompt semantics are invented.
- """
- found = []
- if boxes:
- for index, item in enumerate(boxes, 1):
- target = (item['x'], item['y'], item['x'] + item['width'], item['y'] + item['height'])
- if target[0] < 0 or target[1] < 0 or target[2] > image.width or target[3] > image.height:
- raise ProjectError('选框必须位于原图内。', 422)
- await ctx.progress(f'正在识别框选对象({index}/{len(boxes)})')
- instances = await ctx.segment(image, boxes=(target,))
- best = max(instances, key=lambda item: _overlap(item[2], target), default=None)
- if best is not None and _overlap(best[2], target) >= 0.3:
- found.append((best[0], best[1], f'对象 {index}'))
- else:
- for concept, label in await ctx.concepts(prompt, SMART_LAYERS):
- await ctx.progress(f'正在识别「{label}」')
- found += [(mask, score, label) for mask, score, _ in await ctx.segment(image, concept)]
- return [(mask, score, label, mask.getbbox())
- for mask, score, label in _distinct(found, image.size, with_scores=True, preserve_order=bool(boxes))]
-
+from opendirector.application.tool_context import Output, Source, ToolContext
+from opendirector.application.tool_image_edits import (
+ PRESETS, dynamic_poster, image_hd, image_presets, inpainting_remove, lighting, multi_size,
+ outpaint, panorama, product_replacement, smart_edit, view_control,
+)
+from opendirector.application.tool_image_segments import cutout, layer_decompose, select_image_objects
+from opendirector.application.tool_video_recipes import (
+ AUDIO_MODES, audio_separation, depth_capture, frame_interpolation, partial_reshoot,
+ subtitle_erasure, video_edit, video_matting, video_upscale,
+)
-async def layer_decompose(ctx: ToolContext):
- image = _source_image(ctx)
- mode = ctx.choice('mode', ('smart', 'boxes', 'description'), 'smart')
- if mode == 'boxes' and not ctx.boxes:
- raise ProjectError('框选拆分需要提供原图中的矩形选区。', 422)
- text = ctx.text('prompt') if mode == 'description' else ''
- if mode == 'description' and not text:
- raise ProjectError('按描述拆分需要填写拆分描述。', 422)
- found = await select_image_objects(ctx, image, text, ctx.boxes if mode == 'boxes' else ())
- layers = [(mask, label) for mask, _, label, _ in found]
- if not layers:
- raise ProjectError('没有识别到可分离的对象,请换一种描述或框选对象后重试。', 422)
- holes = Image.new('L', image.size, 0)
- for mask, _ in layers:
- holes = ImageChops.lighter(holes, mask)
- await ctx.progress('正在补全背景')
- # Without an image editor the background keeps transparent holes where the layers were.
- grown = holes.filter(ImageFilter.MaxFilter(max(3, (min(image.size) // 100) | 1)))
- try:
- drawn = await ctx.edit(media.soften_region(image, grown), '移除画面中被涂抹区域的主体,用周围背景自然补全,画面干净完整', 0.85)
- background, title = media.blend(image, drawn, media.feather(grown, max(3, min(image.size) / 150))), '背景'
- except ProjectError:
- background, title = image.convert('RGBA'), '背景(未补全)'
- background.putalpha(ImageChops.multiply(ImageChops.invert(holes), background.getchannel('A')))
- outputs = [image_output(background, title)]
- alpha = image.convert('RGBA').getchannel('A')
- for index, (mask, label) in enumerate(layers, 1):
- # Layers keep the source canvas so stacking them over the background rebuilds the image.
- layer = image.convert('RGBA')
- layer.putalpha(ImageChops.multiply(mask, alpha))
- outputs.append(image_output(layer, f'图层 {index} · {label}'))
- return outputs
+# Editor previews and tool tasks import this helper from the catalog module.
+__all__ = ['Output', 'Source', 'TOOLS', 'ToolContext', 'select_image_objects']
-async def inpainting_remove(ctx: ToolContext):
- image = _source_image(ctx)
- if not ctx.mask:
- raise ProjectError('请先涂抹需要消除的区域。', 422)
- mask = media.mask_from(ctx.mask, image.size)
- await ctx.progress('正在消除并填补')
- drawn = await ctx.edit(media.soften_region(image, mask), '移除涂抹区域中的物体与文字,用周围环境自然填补,画面干净完整', 0.8)
- return [image_output(media.blend(image, drawn, media.feather(mask, max(3, min(image.size) / 120))), '消除')]
-
-
-def _yaw_text(yaw):
- names = ['正面', '右前方', '右侧面', '右后方', '背面', '左后方', '左侧面', '左前方']
- return names[round((yaw % 360) / 45) % 8]
-
-
-async def view_control(ctx: ToolContext):
- image = _source_image(ctx)
- yaw = ctx.number('yaw', 0, -360, 360)
- pitch = ctx.number('pitch', 0, -90, 90)
- distance = ctx.parameters.get('distancePreset') or ctx.parameters.get('distance') or 'standard'
- shot = {'near': '近景特写', 'standard': '中景', 'far': '远景全身'}.get(distance, '中景')
- angle = '俯视' if pitch > 20 else '仰视' if pitch < -10 else '平视'
- await ctx.progress('正在生成新视角')
- edited = await ctx.edit(image, _with(ctx.text('prompt'), f'同一主体从{_yaw_text(yaw)}{angle}角度拍摄的{shot},'
- '保持主体外观、服装、颜色和场景风格完全一致'), 0.8)
- return [image_output(edited, f'多角度 · {_yaw_text(yaw)}')]
-
-
-async def lighting(ctx: ToolContext):
- image = _source_image(ctx)
- yaw = ctx.number('yaw', 0, -360, 360)
- pitch = ctx.number('pitch', 30, -90, 90)
- # The lighting editor sends brightnessPercent; the catalog field is brightness.
- brightness = ctx.number('brightnessPercent' if 'brightnessPercent' in ctx.parameters else 'brightness', 60, 0, 100)
- texture = '柔和漫射' if ctx.parameters.get('texture', 'soft') == 'soft' else '硬朗强烈'
- color = ctx.text('lightColor', '#ffffff') or '#ffffff'
- height = '顶光' if pitch > 50 else '高位' if pitch > 15 else '底光' if pitch < -15 else '平射'
- level = '明亮' if brightness > 66 else '中等亮度' if brightness > 33 else '昏暗低调'
- await ctx.progress('正在重新布光')
- edited = await ctx.edit(image, _with(ctx.text('prompt'), f'重新布光:主光来自{_yaw_text(yaw)}{height},{texture}的光质,'
- f'光色 {color},整体{level},阴影和高光随光源变化,保持主体和构图不变'), 0.72)
- return [image_output(edited, '智能打光')]
-
-
-async def panorama(ctx: ToolContext):
- image = _source_image(ctx)
- width = max(image.width, image.height * 2)
- height = width // 2
- pads = ((width - image.width) // 2, (height - image.height) // 2)
- pads = (pads[0], pads[1], width - image.width - pads[0], height - image.height - pads[1])
- result = await _extend(ctx, image, pads, _with(ctx.text('prompt'), '360度等距柱状投影全景图,左右边缘可无缝衔接'))
- edge = {'4K': 4096, '2K': 2048}.get(ctx.parameters.get('resolution'), 2048)
- return [image_output(media.resize(result, edge, edge // 2), '720 全景')]
-
-
-@dataclass(frozen=True)
-class ImagePreset:
- title: str
- prompts: tuple[str, ...]
- size: tuple[int, int] = (2048, 1152)
-
-
-PRESETS = {
- # Written as edit instructions: editing models follow imperatives, not captions.
- 'three-view': ImagePreset('人物三视图', (
- '以参考图中的人物为唯一身份依据,生成同一人物的全身三视图设定板。'
- '横版画面分为三个等宽区域,从左至右严格排列:正面全身、右侧90度全身、背面全身。'
- '三个视图保持同一身份、年龄、体型、头身比、发型、服装、配色、材质及配饰,衣服结构与细节相互对应。'
- '全部自然站立、双臂放松,同一高度与地面基线,完整呈现头顶到鞋底,不裁头、不切脚、不遮挡、不重叠。'
- '若原图仅有半身,依据可见服装合理补全下半身,补全部分在三个视角保持一致。'
- '保持参考图画风,纯净浅灰背景、均匀柔光、弱透视,无剧情场景、文字、标签、水印、分割线或额外视图。',)),
- 'face-three-view': ImagePreset('面部三视图', (
- '以参考图人物的面部为唯一身份依据,生成同一人物的面部三视图参考板。'
- '超宽横版画面分为三个等宽区域,从左至右严格排列:正面、左侧90度、右侧90度。'
- '每个视图只呈现完整头部至肩颈,头顶、下巴、耳朵均完整,不出现背面或全身视图。'
- '保持同一身份、年龄、脸型、骨相、五官比例、肤色、发际线、发型及识别性细节,左右侧面符合真实结构。'
- '三个头部大小一致、眼睛基线对齐、中性表情、视线随朝向自然变化,面部不被头发遮挡。'
- '保持参考图画风,纯净浅灰背景、均匀柔光,无美颜改脸、夸张透视、文字、标签、水印或额外人物。',), (2688, 1152)),
- 'product-three-view': ImagePreset('产品三视图', (
- '以参考图中的产品为唯一设计依据,生成同一产品的工业设计三视图参考板。'
- '横版画面分为三个等宽区域,从左至右严格排列:正视图、右侧90度侧视图、后视图。'
- '采用近正交投影、无广角畸变,同一比例尺、同一高度与底部基线,完整展示产品外轮廓,不裁切、不重叠。'
- '三个视图保持结构、尺寸关系、材质、颜色、表面纹理、接口、按钮、接缝及标识一致,细节在视角之间符合物理对应关系。'
- '不可见部位依据已知结构作合理且一致的补全,不增加功能件或改变产品设计。'
- '产品独立展示,纯白背景、均匀棚拍光,无人物、手、包装道具、剧情场景、说明文字、尺寸标注、水印或额外视图;保留原有品牌标识。',)),
- 'storyboard': ImagePreset('分镜', ('把镜头拉远成远景建立镜头,完整交代周围环境,主体在画面中较小',
- '改为中景镜头,主体占画面一半高度,动作清晰',
- '改为近景镜头,镜头推近到主体胸口以上,突出表情',
- '改为特写镜头,只拍主体面部或关键细节,背景虚化')),
- 'multi-camera': ImagePreset('多机位', ('把机位移到主体正前方,平视拍摄',
- '把机位向左绕到主体左前方约45度,从左侧斜角拍摄,透视随之改变',
- '把机位向右绕到主体右前方约45度,从右侧斜角拍摄,透视随之改变',
- '把机位升高到主体上方,高角度俯拍')),
-}
-
-
-async def image_presets(ctx: ToolContext):
- image = _source_image(ctx)
- preset = PRESETS[ctx.choice('preset', PRESETS)]
- title, prompts = preset.title, preset.prompts
- outputs = []
- for index, instruction in enumerate(prompts, 1):
- await ctx.progress(f'正在生成{title}({index}/{len(prompts)})')
- edited = await ctx.reframe(image, *preset.size, instruction + ',保持主体外观与风格一致')
- outputs.append(image_output(edited, f'{title} {index}' if len(prompts) > 1 else title))
- return outputs
-
-
-async def multi_size(ctx: ToolContext):
- image = _source_image(ctx)
- width = int(ctx.number('outputWidth', image.width, 64, 8192))
- height = int(ctx.number('outputHeight', image.height, 64, 8192))
- target, current = width / height, image.width / image.height
- if abs(target - current) < 0.01:
- return [image_output(media.resize(image, width, height), f'{width}×{height}')]
- if target > current:
- extra = round(image.height * target) - image.width
- pads = (extra // 2, 0, extra - extra // 2, 0)
- else:
- extra = round(image.width / target) - image.height
- pads = (0, extra // 2, 0, extra - extra // 2)
- result = await _extend(ctx, image, pads, ctx.text('prompt'))
- return [image_output(media.resize(result, width, height), f'{width}×{height}')]
-
-
-async def product_replacement(ctx: ToolContext):
- scene, product = _source_image(ctx, 0), _source_image(ctx, 1)
- if not ctx.boxes:
- raise ProjectError('请先框选商品区域。', 422)
- box = ctx.boxes[0]
- x, y, width, height = (int(round(box[key])) for key in ('x', 'y', 'width', 'height'))
- if width < 8 or height < 8 or x < 0 or y < 0 or x + width > scene.width or y + height > scene.height:
- raise ProjectError('商品区域超出原图或尺寸不正确。', 422)
- layer = media.cover_box(product, (x, y, width, height))
- placed = scene.copy()
- placed.paste(layer, (x, y), layer)
- await ctx.progress('正在融合商品与场景')
- drawn = await ctx.edit(placed, _with(ctx.text('prompt'), '商品自然融入场景,光影、透视和色调一致,保留商品外观和文字'), 0.42)
- region = Image.new('L', scene.size, 0)
- region.paste(255, (x, y, x + width, y + height))
- result = media.blend(scene, drawn, media.feather(region, max(4, min(width, height) / 12)))
- edge = {'4K': 4096, '2K': 2048}.get(ctx.parameters.get('resolution'))
- if edge and max(result.size) < edge:
- result = media.scale_to_long_edge(result, edge)
- return [image_output(result, '商品替换')]
-
-
-async def dynamic_poster(ctx: ToolContext):
- image = _source_image(ctx)
- await ctx.progress('正在生成动态海报')
- prompt = await ctx.video_prompt(ctx.text('prompt'), 'The poster comes gently alive with subtle natural motion; the subject and its text stay stable.')
- data = await ctx.video_from_frame(image, prompt, 5)
- return [Output('video', data, 'mp4', '动态海报')]
-
-
-# Video recipes ---------------------------------------------------------------
-
-def _source_video(ctx: ToolContext) -> Source:
- if not ctx.sources or ctx.sources[0].kind != 'video':
- raise ProjectError('请提供视频素材。', 422)
- return ctx.sources[0]
-
-
-async def _redraw_pieces(ctx: ToolContext, source: Source, prompt: str, picture, sound, *, window=None):
- """Redraw a clip within the model's per-request length: the whole clip in even pieces, or only
- the stretch around `window` (seconds), spliced back. Output keeps the source size and rate."""
- low, high = ctx.edit_seconds
- with media.Workspace() as work:
- path = work.write('source.mp4', source.data)
- info = await blocking(media.video_info, path)
- duration = info['duration']
- if duration < low:
- raise ProjectError(f'视频至少需要 {low:g} 秒。', 422)
- if window:
- start, end = window
- if end - start > high:
- raise ProjectError(f'一次最多重绘 {high:g} 秒,请缩短区间。', 422)
- length = min(duration, max(low, min(high, end - start + 2)))
- first = min(max(0.0, (start + end - length) / 2), duration - length)
- pieces = [(first, first + length)]
- else:
- count = math.ceil(duration / high)
- pieces = [(duration * index / count, duration * (index + 1) / count) for index in range(count)]
- done = []
- for index, (first, last) in enumerate(pieces):
- await ctx.progress(f'正在重绘({index + 1}/{len(pieces)})' if len(pieces) > 1 else '正在重绘')
- clip = await blocking(media.conform, path, work.path / f'in-{index}.mp4', width=info['width'], height=info['height'],
- fps=info['fps'], start=first, end=last)
- local = (lambda mask: mask and EditMask(mask.level, mask.region, None if mask.start is None else mask.start - first,
- None if mask.end is None else mask.end - first))
- drawn = await ctx.redraw(clip.read_bytes(), last - first, info['width'], info['height'], prompt, local(picture), local(sound))
- done.append(await blocking(media.conform, work.write(f'drawn-{index}.mp4', drawn), work.path / f'out-{index}.mp4',
- width=info['width'], height=info['height'], fps=info['fps'], end=last - first))
- await ctx.progress('正在合成结果')
- if window:
- return await blocking(media.splice, work, path, pieces[0][0], pieces[0][1], done[0])
- return await blocking(media.concat, work, done)
-
-
-def _box_region(ctx: ToolContext, width, height, rows=36, columns=64):
- """Selection boxes (source pixels) as a 0/1 grid over the frame, or None without boxes."""
- if not ctx.boxes:
- return None
- grid = [[0.0] * columns for _ in range(rows)]
- for box in ctx.boxes:
- x0, y0 = box['x'] / width, box['y'] / height
- x1, y1 = (box['x'] + box['width']) / width, (box['y'] + box['height']) / height
- for row in range(rows):
- for column in range(columns):
- if x0 <= (column + 0.5) / columns <= x1 and y0 <= (row + 0.5) / rows <= y1:
- grid[row][column] = 1.0
- return tuple(tuple(row) for row in grid)
-
-
-async def _video_size(source: Source):
- with media.Workspace() as work:
- info = await blocking(media.video_info, work.write('probe.mp4', source.data))
- return info['width'], info['height']
-
-
-async def partial_reshoot(ctx: ToolContext):
- source = _source_video(ctx)
- prompt = ctx.text('prompt')
- if not prompt:
- raise ProjectError('请描述重拍片段的内容。', 422)
- start = ctx.number('startMs', 0, 0) / 1000
- end = ctx.number('endMs', 0, 0) / 1000
- if end - start < 0.5:
- raise ProjectError('重拍区间至少 0.5 秒。', 422)
- # Only the chosen stretch is redrawn, picture and sound; the rest of the clip stays the source.
- window = EditMask(1.0, None, start, end)
- prompt = await ctx.video_prompt(prompt, 'Keep the people, setting, lighting and camera continuous with the surrounding footage.')
- data = await _redraw_pieces(ctx, source, prompt, window, window, window=(start, end))
- return [Output('video', data, 'mp4', '局部重拍')]
-
-
-MATTE_MAX_FRAMES = 2048
-
-
-def _write_mattes(tracks: Tracks, folder):
- folder.mkdir()
- for index, frame in enumerate(tracks.frames):
- matte = Image.new('L', (tracks.width, tracks.height), 0)
- for counts in frame:
- matte = ImageChops.lighter(matte, media.rle_mask(counts, tracks.width, tracks.height))
- # A one-pixel blur anti-aliases the hard mask edge.
- matte.filter(ImageFilter.GaussianBlur(0.8)).save(folder / f'{index:05d}.png', compress_level=1)
-
-
-async def video_matting(ctx: ToolContext):
- source = _source_video(ctx)
- background = ctx.choice('background', ('black', 'green', 'transparent'), 'green')
- pairs = await ctx.concepts(ctx.text('prompt'), ('人物',))
- with media.Workspace() as work:
- raw = work.write('source', source.data)
- info = await blocking(media.video_info, raw)
- if info['duration'] * info['fps'] > MATTE_MAX_FRAMES:
- raise ProjectError(f'视频抠像单次最多处理 {MATTE_MAX_FRAMES} 帧(约 {MATTE_MAX_FRAMES / info["fps"]:.0f} 秒),请先裁剪视频。', 422)
- await ctx.progress('正在整理视频')
- # A constant-rate, even-sized clip decodes to the same frames for the tracker and ffmpeg.
- clip = await blocking(media.conform, raw, work.path / 'clip.mp4', width=info['width'] - info['width'] % 2,
- height=info['height'] - info['height'] % 2, fps=info['fps'])
- await ctx.progress(f"正在识别并跟踪「{'、'.join(label for _, label in pairs)}」")
- tracks = await ctx.track(clip.read_bytes(), tuple(concept for concept, _ in pairs))
- if not any(tracks.frames):
- raise ProjectError(f"视频中没有识别到「{'、'.join(label for _, label in pairs)}」,请换一种描述后重试。", 422)
- await ctx.progress('正在合成抠像视频')
- await blocking(_write_mattes, tracks, work.path / 'mattes')
- data, suffix = await blocking(media.matte, clip, str(work.path / 'mattes' / '%05d.png'), info['fps'],
- work.path / 'matted', background=background)
- return [Output('video', data, suffix, '视频抠像')]
-
-
-DEPTH_MAX_SECONDS = 30
-DEPTH_MAX_FRAMES = 2048
-DEPTH_SHORT_EDGES = {'480P': 480, '720P': 720}
-
-
-def _depth_size(width, height, short_edge):
- """The source size scaled down so its short side is at most short_edge, on even pixels."""
- scale = min(1.0, short_edge / min(width, height))
- return max(2, round(width * scale / 2) * 2), max(2, round(height * scale / 2) * 2)
-
-
-async def depth_capture(ctx: ToolContext):
- source = _source_video(ctx)
- resolution = ctx.choice('resolution', tuple(DEPTH_SHORT_EDGES), '480P')
- with media.Workspace() as work:
- raw = work.write('source', source.data)
- info = await blocking(media.video_info, raw)
- if not 0 < info['duration'] <= DEPTH_MAX_SECONDS + 0.05:
- raise ProjectError(f'深度动作捕捉需要不超过 {DEPTH_MAX_SECONDS} 秒的素材,请先裁剪视频。', 422)
- if info['duration'] * info['fps'] > DEPTH_MAX_FRAMES:
- raise ProjectError(f'深度动作捕捉单次最多处理 {DEPTH_MAX_FRAMES} 帧,请先裁剪视频或降低帧率。', 422)
- await ctx.progress('正在整理视频')
- # The depth service returns the size it receives, so the clip is sized here; every
- # source frame is kept so depth frame i lines up with source frame i.
- width, height = _depth_size(info['width'], info['height'], DEPTH_SHORT_EDGES[resolution])
- clip = await blocking(media.picture, raw, work.path / 'clip.mp4', width=width, height=height)
- await ctx.progress('正在估计每一帧的深度')
- data = await ctx.depth(clip.read_bytes())
- return [Output('video', data, 'mp4', f'深度动作捕捉 {resolution}')]
-
-
-async def video_edit(ctx: ToolContext):
- source = _source_video(ctx)
- prompt = ctx.text('prompt')
- if not prompt:
- raise ProjectError('请描述要如何修改视频。', 422)
- width, height = await _video_size(source)
- region = _box_region(ctx, width, height)
- # Masked redraw regenerates a region; a whole-frame restyle would discard the source entirely.
- if region is None:
- raise ProjectError('请先框选要重绘的区域。', 422)
- prompt = await ctx.video_prompt(prompt, 'The rest of the picture, its light and motion stay as they are.')
- data = await _redraw_pieces(ctx, source, prompt, EditMask(1.0, region), None)
- return [Output('video', data, 'mp4', '视频编辑')]
-
-
-SUBTITLE_BAND = tuple((1.0,) if row >= 39 else (0.0,) for row in range(50)) # Bottom 22% of the frame.
-
-
-async def subtitle_erasure(ctx: ToolContext):
- source = _source_video(ctx)
- width, height = await _video_size(source)
- picture = EditMask(1.0, _box_region(ctx, width, height) or SUBTITLE_BAND)
- prompt = await ctx.video_prompt(ctx.text('prompt'), 'This part of the frame continues the surrounding scene naturally, '
- 'matching its texture, light and motion.')
- data = await _redraw_pieces(ctx, source, prompt, picture, None)
- return [Output('video', data, 'mp4', '字幕擦除')]
-
-
-AUDIO_MODES = {'all': '完整音轨', 'voice': '人声(近似)', 'backgroundSound': '背景声(近似)'}
-
-
-async def audio_separation(ctx: ToolContext):
- if not ctx.sources or ctx.sources[0].kind not in {'video', 'audio'}:
- raise ProjectError('请提供视频或音频素材。', 422)
- source = ctx.sources[0]
- mode = ctx.choice('mode', AUDIO_MODES, 'all')
- outputs = []
- with media.Workspace() as work:
- suffix = source.name.rsplit('.', 1)[-1].lower() if '.' in source.name else ('mp4' if source.kind == 'video' else 'mp3')
- path = work.write(f'source.{suffix}', source.data)
- if mode == 'backgroundSound' and not await blocking(media.is_stereo_with_side, path):
- raise ProjectError('单声道音频无法在本地估计背景声,需要接入具备音轨分离能力的模型。', 422)
- await ctx.progress('正在分离音轨')
- audio = await blocking(media.audio_track, path, work.path / 'track.mp3',
- mode={'all': 'all', 'voice': 'voice', 'backgroundSound': 'background'}[mode])
- outputs.append(Output('audio', audio, 'mp3', AUDIO_MODES[mode]))
- if mode == 'all' and source.kind == 'video':
- # Splitting a clip yields both halves: its soundtrack and the silent picture.
- outputs.append(Output('video', await blocking(media.without_audio, path, work.path / 'silent.mp4'), 'mp4', '无声视频'))
- return outputs
-
-
-async def video_upscale(ctx: ToolContext):
- source = _source_video(ctx)
- edge = {'2K': 2560, '4K': 3840}[ctx.choice('resolution', ('2K', '4K'), '4K')]
- await ctx.progress('正在放大视频')
- with media.Workspace() as work:
- data = await blocking(media.upscale, work.write('source.mp4', source.data), edge, work.path / 'out.mp4')
- return [Output('video', data, 'mp4', f'超清 {ctx.parameters.get("resolution", "4K")}')]
-
-
-async def frame_interpolation(ctx: ToolContext):
- source = _source_video(ctx)
- fps = int(ctx.choice('fps', (30, 60, '30', '60'), 60))
- await ctx.progress(f'正在补帧到 {fps} fps')
- with media.Workspace() as work:
- data = await blocking(media.interpolate, work.write('source.mp4', source.data), fps, work.path / 'out.mp4')
- return [Output('video', data, 'mp4', f'补帧 {fps}fps')]
-
-
-# Catalog ---------------------------------------------------------------------
-
Recipe = Callable[[ToolContext], Awaitable[list[Output]]]
-
@dataclass(frozen=True)
class ToolSpec:
id: str
@@ -815,11 +34,9 @@ class ToolSpec:
fields: tuple[dict, ...] = field(default_factory=tuple)
note: str = ''
-
def _needs(*capabilities):
return lambda parameters: capabilities
-
def _select(key, label, options, default=None, required=True):
value = {'key': key, 'label': label, 'type': 'select', 'required': required,
'options': [{'value': option, 'label': text} for option, text in options]}
@@ -827,7 +44,6 @@ def _select(key, label, options, default=None, required=True):
value['default'] = default
return value
-
TOOLS: dict[str, ToolSpec] = {item.id: item for item in [
ToolSpec('smart-edit', ('image',), _needs('image.edit'), smart_edit),
ToolSpec('outpaint', ('image',), _needs('image.edit'), outpaint),
diff --git a/packages/core/src/opendirector/application/tool_video_recipes.py b/packages/core/src/opendirector/application/tool_video_recipes.py
new file mode 100644
index 000000000..81bc21eba
--- /dev/null
+++ b/packages/core/src/opendirector/application/tool_video_recipes.py
@@ -0,0 +1,212 @@
+"""Video recipes over local media steps and video-model capabilities."""
+import math
+
+from PIL import Image, ImageChops, ImageFilter
+
+from opendirector.application.tool_context import Output, Source, ToolContext
+from opendirector.domain.capabilities import EditMask, Tracks
+from opendirector.domain.projects import ProjectError
+from opendirector.media import processing as media
+from opendirector.media.async_work import blocking
+
+
+def _source_video(ctx: ToolContext) -> Source:
+ if not ctx.sources or ctx.sources[0].kind != 'video':
+ raise ProjectError('请提供视频素材。', 422)
+ return ctx.sources[0]
+
+async def _redraw_pieces(ctx: ToolContext, source: Source, prompt: str, picture, sound, *, window=None):
+ """Redraw a clip within the model's per-request length: the whole clip in even pieces, or only
+ the stretch around `window` (seconds), spliced back. Output keeps the source size and rate."""
+ low, high = ctx.edit_seconds
+ with media.Workspace() as work:
+ path = work.write('source.mp4', source.data)
+ info = await blocking(media.video_info, path)
+ duration = info['duration']
+ if duration < low:
+ raise ProjectError(f'视频至少需要 {low:g} 秒。', 422)
+ if window:
+ start, end = window
+ if end - start > high:
+ raise ProjectError(f'一次最多重绘 {high:g} 秒,请缩短区间。', 422)
+ length = min(duration, max(low, min(high, end - start + 2)))
+ first = min(max(0.0, (start + end - length) / 2), duration - length)
+ pieces = [(first, first + length)]
+ else:
+ count = math.ceil(duration / high)
+ pieces = [(duration * index / count, duration * (index + 1) / count) for index in range(count)]
+ done = []
+ for index, (first, last) in enumerate(pieces):
+ await ctx.progress(f'正在重绘({index + 1}/{len(pieces)})' if len(pieces) > 1 else '正在重绘')
+ clip = await blocking(media.conform, path, work.path / f'in-{index}.mp4', width=info['width'], height=info['height'],
+ fps=info['fps'], start=first, end=last)
+ local = (lambda mask: mask and EditMask(mask.level, mask.region, None if mask.start is None else mask.start - first,
+ None if mask.end is None else mask.end - first))
+ drawn = await ctx.redraw(clip.read_bytes(), last - first, info['width'], info['height'], prompt, local(picture), local(sound))
+ done.append(await blocking(media.conform, work.write(f'drawn-{index}.mp4', drawn), work.path / f'out-{index}.mp4',
+ width=info['width'], height=info['height'], fps=info['fps'], end=last - first))
+ await ctx.progress('正在合成结果')
+ if window:
+ return await blocking(media.splice, work, path, pieces[0][0], pieces[0][1], done[0])
+ return await blocking(media.concat, work, done)
+
+def _box_region(ctx: ToolContext, width, height, rows=36, columns=64):
+ """Selection boxes (source pixels) as a 0/1 grid over the frame, or None without boxes."""
+ if not ctx.boxes:
+ return None
+ grid = [[0.0] * columns for _ in range(rows)]
+ for box in ctx.boxes:
+ x0, y0 = box['x'] / width, box['y'] / height
+ x1, y1 = (box['x'] + box['width']) / width, (box['y'] + box['height']) / height
+ for row in range(rows):
+ for column in range(columns):
+ if x0 <= (column + 0.5) / columns <= x1 and y0 <= (row + 0.5) / rows <= y1:
+ grid[row][column] = 1.0
+ return tuple(tuple(row) for row in grid)
+
+async def _video_size(source: Source):
+ with media.Workspace() as work:
+ info = await blocking(media.video_info, work.write('probe.mp4', source.data))
+ return info['width'], info['height']
+
+async def partial_reshoot(ctx: ToolContext):
+ source = _source_video(ctx)
+ prompt = ctx.text('prompt')
+ if not prompt:
+ raise ProjectError('请描述重拍片段的内容。', 422)
+ start = ctx.number('startMs', 0, 0) / 1000
+ end = ctx.number('endMs', 0, 0) / 1000
+ if end - start < 0.5:
+ raise ProjectError('重拍区间至少 0.5 秒。', 422)
+ # Only the chosen stretch is redrawn, picture and sound; the rest of the clip stays the source.
+ window = EditMask(1.0, None, start, end)
+ prompt = await ctx.video_prompt(prompt, 'Keep the people, setting, lighting and camera continuous with the surrounding footage.')
+ data = await _redraw_pieces(ctx, source, prompt, window, window, window=(start, end))
+ return [Output('video', data, 'mp4', '局部重拍')]
+
+MATTE_MAX_FRAMES = 2048
+
+def _write_mattes(tracks: Tracks, folder):
+ folder.mkdir()
+ for index, frame in enumerate(tracks.frames):
+ matte = Image.new('L', (tracks.width, tracks.height), 0)
+ for counts in frame:
+ matte = ImageChops.lighter(matte, media.rle_mask(counts, tracks.width, tracks.height))
+ # A one-pixel blur anti-aliases the hard mask edge.
+ matte.filter(ImageFilter.GaussianBlur(0.8)).save(folder / f'{index:05d}.png', compress_level=1)
+
+async def video_matting(ctx: ToolContext):
+ source = _source_video(ctx)
+ background = ctx.choice('background', ('black', 'green', 'transparent'), 'green')
+ pairs = await ctx.concepts(ctx.text('prompt'), ('人物',))
+ with media.Workspace() as work:
+ raw = work.write('source', source.data)
+ info = await blocking(media.video_info, raw)
+ if info['duration'] * info['fps'] > MATTE_MAX_FRAMES:
+ raise ProjectError(f'视频抠像单次最多处理 {MATTE_MAX_FRAMES} 帧(约 {MATTE_MAX_FRAMES / info["fps"]:.0f} 秒),请先裁剪视频。', 422)
+ await ctx.progress('正在整理视频')
+ # A constant-rate, even-sized clip decodes to the same frames for the tracker and ffmpeg.
+ clip = await blocking(media.conform, raw, work.path / 'clip.mp4', width=info['width'] - info['width'] % 2,
+ height=info['height'] - info['height'] % 2, fps=info['fps'])
+ await ctx.progress(f"正在识别并跟踪「{'、'.join(label for _, label in pairs)}」")
+ tracks = await ctx.track(clip.read_bytes(), tuple(concept for concept, _ in pairs))
+ if not any(tracks.frames):
+ raise ProjectError(f"视频中没有识别到「{'、'.join(label for _, label in pairs)}」,请换一种描述后重试。", 422)
+ await ctx.progress('正在合成抠像视频')
+ await blocking(_write_mattes, tracks, work.path / 'mattes')
+ data, suffix = await blocking(media.matte, clip, str(work.path / 'mattes' / '%05d.png'), info['fps'],
+ work.path / 'matted', background=background)
+ return [Output('video', data, suffix, '视频抠像')]
+
+DEPTH_MAX_SECONDS = 30
+
+DEPTH_MAX_FRAMES = 2048
+
+DEPTH_SHORT_EDGES = {'480P': 480, '720P': 720}
+
+def _depth_size(width, height, short_edge):
+ """The source size scaled down so its short side is at most short_edge, on even pixels."""
+ scale = min(1.0, short_edge / min(width, height))
+ return max(2, round(width * scale / 2) * 2), max(2, round(height * scale / 2) * 2)
+
+async def depth_capture(ctx: ToolContext):
+ source = _source_video(ctx)
+ resolution = ctx.choice('resolution', tuple(DEPTH_SHORT_EDGES), '480P')
+ with media.Workspace() as work:
+ raw = work.write('source', source.data)
+ info = await blocking(media.video_info, raw)
+ if not 0 < info['duration'] <= DEPTH_MAX_SECONDS + 0.05:
+ raise ProjectError(f'深度动作捕捉需要不超过 {DEPTH_MAX_SECONDS} 秒的素材,请先裁剪视频。', 422)
+ if info['duration'] * info['fps'] > DEPTH_MAX_FRAMES:
+ raise ProjectError(f'深度动作捕捉单次最多处理 {DEPTH_MAX_FRAMES} 帧,请先裁剪视频或降低帧率。', 422)
+ await ctx.progress('正在整理视频')
+ # The depth service returns the size it receives, so the clip is sized here; every
+ # source frame is kept so depth frame i lines up with source frame i.
+ width, height = _depth_size(info['width'], info['height'], DEPTH_SHORT_EDGES[resolution])
+ clip = await blocking(media.picture, raw, work.path / 'clip.mp4', width=width, height=height)
+ await ctx.progress('正在估计每一帧的深度')
+ data = await ctx.depth(clip.read_bytes())
+ return [Output('video', data, 'mp4', f'深度动作捕捉 {resolution}')]
+
+async def video_edit(ctx: ToolContext):
+ source = _source_video(ctx)
+ prompt = ctx.text('prompt')
+ if not prompt:
+ raise ProjectError('请描述要如何修改视频。', 422)
+ width, height = await _video_size(source)
+ region = _box_region(ctx, width, height)
+ # Masked redraw regenerates a region; a whole-frame restyle would discard the source entirely.
+ if region is None:
+ raise ProjectError('请先框选要重绘的区域。', 422)
+ prompt = await ctx.video_prompt(prompt, 'The rest of the picture, its light and motion stay as they are.')
+ data = await _redraw_pieces(ctx, source, prompt, EditMask(1.0, region), None)
+ return [Output('video', data, 'mp4', '视频编辑')]
+
+SUBTITLE_BAND = tuple((1.0,) if row >= 39 else (0.0,) for row in range(50)) # Bottom 22% of the frame.
+
+async def subtitle_erasure(ctx: ToolContext):
+ source = _source_video(ctx)
+ width, height = await _video_size(source)
+ picture = EditMask(1.0, _box_region(ctx, width, height) or SUBTITLE_BAND)
+ prompt = await ctx.video_prompt(ctx.text('prompt'), 'This part of the frame continues the surrounding scene naturally, '
+ 'matching its texture, light and motion.')
+ data = await _redraw_pieces(ctx, source, prompt, picture, None)
+ return [Output('video', data, 'mp4', '字幕擦除')]
+
+AUDIO_MODES = {'all': '完整音轨', 'voice': '人声(近似)', 'backgroundSound': '背景声(近似)'}
+
+async def audio_separation(ctx: ToolContext):
+ if not ctx.sources or ctx.sources[0].kind not in {'video', 'audio'}:
+ raise ProjectError('请提供视频或音频素材。', 422)
+ source = ctx.sources[0]
+ mode = ctx.choice('mode', AUDIO_MODES, 'all')
+ outputs = []
+ with media.Workspace() as work:
+ suffix = source.name.rsplit('.', 1)[-1].lower() if '.' in source.name else ('mp4' if source.kind == 'video' else 'mp3')
+ path = work.write(f'source.{suffix}', source.data)
+ if mode == 'backgroundSound' and not await blocking(media.is_stereo_with_side, path):
+ raise ProjectError('单声道音频无法在本地估计背景声,需要接入具备音轨分离能力的模型。', 422)
+ await ctx.progress('正在分离音轨')
+ audio = await blocking(media.audio_track, path, work.path / 'track.mp3',
+ mode={'all': 'all', 'voice': 'voice', 'backgroundSound': 'background'}[mode])
+ outputs.append(Output('audio', audio, 'mp3', AUDIO_MODES[mode]))
+ if mode == 'all' and source.kind == 'video':
+ # Splitting a clip yields both halves: its soundtrack and the silent picture.
+ outputs.append(Output('video', await blocking(media.without_audio, path, work.path / 'silent.mp4'), 'mp4', '无声视频'))
+ return outputs
+
+async def video_upscale(ctx: ToolContext):
+ source = _source_video(ctx)
+ edge = {'2K': 2560, '4K': 3840}[ctx.choice('resolution', ('2K', '4K'), '4K')]
+ await ctx.progress('正在放大视频')
+ with media.Workspace() as work:
+ data = await blocking(media.upscale, work.write('source.mp4', source.data), edge, work.path / 'out.mp4')
+ return [Output('video', data, 'mp4', f'超清 {ctx.parameters.get("resolution", "4K")}')]
+
+async def frame_interpolation(ctx: ToolContext):
+ source = _source_video(ctx)
+ fps = int(ctx.choice('fps', (30, 60, '30', '60'), 60))
+ await ctx.progress(f'正在补帧到 {fps} fps')
+ with media.Workspace() as work:
+ data = await blocking(media.interpolate, work.write('source.mp4', source.data), fps, work.path / 'out.mp4')
+ return [Output('video', data, 'mp4', f'补帧 {fps}fps')]
diff --git a/packages/core/src/opendirector/infrastructure/creation_catalog.py b/packages/core/src/opendirector/infrastructure/creation_catalog.py
new file mode 100644
index 000000000..fc2c64c33
--- /dev/null
+++ b/packages/core/src/opendirector/infrastructure/creation_catalog.py
@@ -0,0 +1,187 @@
+"""Project directory scan, catalog listing, and unreadable-folder cleanup."""
+import time
+from pathlib import Path
+
+from opendirector.domain.projects import ProjectError, identifier, project_name
+from opendirector.infrastructure import recycle
+from opendirector.infrastructure.creation_records import Manifest
+from opendirector.infrastructure.directories import directory, sync_directory
+from opendirector.infrastructure.local_projects import child, read_json
+
+
+class ProjectCatalog:
+ """Find project directories and list the ones a catalog read can open."""
+
+ @staticmethod
+ def _parse_manifest(raw):
+ if not isinstance(raw, dict) or raw.get('format') != 'opendirector-project' or raw.get('formatVersion') != 2:
+ raise ProjectError('不支持该工程格式;请创建新工程,旧文件不会自动转换。', 409, code='unsupported_format')
+ try:
+ value = Manifest.model_validate(raw)
+ project_name(value.name)
+ return value
+ except (ValueError, TypeError):
+ raise ProjectError('工程清单无效,原文件已保留。', 409, code='storage_unavailable') from None
+
+ @classmethod
+ def _manifest(cls, path):
+ directory(path)
+ return cls._parse_manifest(read_json(child(path, 'project.json')))
+
+ def _scan(self):
+ self.local._check_root()
+ grouped, manifests, unsupported, warnings = {}, {}, set(), list(self._warnings)
+ self._invalid = []
+ if self.root.is_dir():
+ for path in sorted(self.root.iterdir()):
+ if path.is_symlink() or not path.is_dir() or path.name.startswith('.opendirector-'):
+ continue
+ manifest_path = path / 'project.json'
+ if not manifest_path.exists() and not manifest_path.is_symlink():
+ continue
+ try:
+ project_name(path.name)
+ raw = read_json(child(path, 'project.json'))
+ project_id = identifier(raw['id'])
+ grouped.setdefault(project_id, []).append(path)
+ if raw.get('format') != 'opendirector-project' or raw.get('formatVersion') != 2:
+ unsupported.add(project_id)
+ else:
+ # Parsed once per scan; callers never reread project.json.
+ manifests[project_id] = raw
+ except (OSError, ValueError, TypeError, KeyError, ProjectError):
+ warning = f'工程“{path.name}”的清单无法读取,原文件已保留。'
+ warnings.append(warning)
+ self._invalid.append((path, warning))
+ conflicts = {key for key, paths in grouped.items() if len(paths) > 1}
+ for key in sorted(conflicts):
+ warnings.append(f'工程标识重复:{key};请移走重复目录后重试。')
+ return grouped, manifests, unsupported, conflicts, warnings
+
+ def _find(self, db, project_id):
+ project_id = identifier(str(project_id))
+ if project_id in self._blocked:
+ raise ProjectError('工程提交需要恢复;请检查磁盘及工程文件后重试。', 409, code='storage_unavailable')
+ grouped, manifests, unsupported, conflicts, _ = self._scan()
+ if project_id in conflicts:
+ raise ProjectError('projects 中存在同标识工程,请移走重复目录后重试。', 409)
+ if project_id in unsupported:
+ raise ProjectError('不支持该工程格式;请创建新工程,旧文件不会自动转换。', 409, code='unsupported_format')
+ if project_id not in grouped:
+ raise ProjectError('工程不在 projects 中或清单无法读取,请刷新工程列表。', 404)
+ path = grouped[project_id][0]
+ raw = manifests.get(project_id)
+ if raw is None:
+ # The manifest is present but invalid; report the precise reason.
+ return path, self._manifest(path)
+ return path, self._parse_manifest(raw)
+
+ @staticmethod
+ def _unreadable_item(path, reason, project_id=None):
+ return dict(id=project_id, name=path.name, path=str(path), reason=reason)
+
+ def _catalog(self, db):
+ # One directory scan for the whole listing: resolving each project with
+ # _find() reread every project.json once per project (O(N^2)).
+ grouped, manifests, unsupported, conflicts, warnings = self._scan()
+ invalid = list(self._invalid)
+ projects = []
+ unreadable = [self._unreadable_item(path, reason) for path, reason in invalid]
+ for project_id in sorted(grouped):
+ paths = grouped[project_id]
+ if project_id in unsupported:
+ reason = f'工程 {project_id} 使用旧格式,统一工程接口不支持读取或转换。'
+ warnings.append(reason)
+ unreadable.extend(self._unreadable_item(path, reason, project_id) for path in paths)
+ continue
+ if project_id in conflicts:
+ reason = f'工程标识重复:{project_id};请移走重复目录后重试。'
+ unreadable.extend(self._unreadable_item(path, reason, project_id) for path in paths)
+ continue
+ try:
+ if project_id in self._blocked:
+ raise ProjectError('工程提交需要恢复;请检查磁盘及工程文件后重试。',
+ 409, code='storage_unavailable')
+ path = paths[0]
+ raw = manifests.get(project_id)
+ manifest = self._manifest(path) if raw is None else self._parse_manifest(raw)
+ # Parsing the head alone proves the project still opens, and the
+ # manifest already carries the name it must agree with; a full
+ # chain replay just to list a name cost about a second.
+ record = self._record(path, manifest.head)
+ if record.snapshot.project.name != manifest.name:
+ raise ProjectError('工程提交历史与清单不一致,原文件已保留。', 409, code='storage_unavailable')
+ projects.append(dict(id=project_id, name=manifest.name, path=str(path)))
+ except (ProjectError, OSError):
+ reason = f'工程 {project_id} 需要恢复,原文件已保留。'
+ warnings.append(reason)
+ unreadable.append(self._unreadable_item(paths[0], reason, project_id))
+ projects.sort(key=lambda item: (item['name'].casefold(), item['name']))
+ unreadable.sort(key=lambda item: (item['name'].casefold(), item['name']))
+ return dict(projects=projects, unreadable=unreadable, warnings=warnings)
+
+ def list_projects(self):
+ with self.local.transaction() as db:
+ self._recover()
+ return self._catalog(db)
+
+ @staticmethod
+ def _cleanup_blocker(db, project_id, path):
+ active = db.execute('SELECT 1 FROM sessions WHERE expires>? AND (path=? OR project_id=?)',
+ (time.time(), str(path), project_id or '')).fetchone()
+ if active:
+ return '工程仍在其他窗口中打开,请关闭后再清理。'
+ tools = path / 'tool-tasks'
+ if tools.exists() or tools.is_symlink():
+ try:
+ directory(tools)
+ tasks = [read_json(child(tools, item.name)) for item in tools.glob('*.json')]
+ if any(not isinstance(task, dict) for task in tasks):
+ raise ValueError('Invalid tool task')
+ except (OSError, ValueError, TypeError, KeyError, ProjectError):
+ return '无法确认工具任务状态,请检查工程文件后再清理。'
+ if any(task.get('status') in {'queued', 'running'} for task in tasks):
+ return '工程仍有工具任务,请等待或取消任务后再清理。'
+ return None
+
+ def cleanup_unreadable(self):
+ """Remove only directories that a fresh catalog read still cannot open."""
+ with self.local.transaction() as db:
+ self._recover()
+ candidates = self._catalog(db)['unreadable']
+ removed, failed = [], []
+ for candidate in candidates:
+ with self.local.transaction() as db:
+ self._recover()
+ current = next((item for item in self._catalog(db)['unreadable']
+ if item['path'] == candidate['path']), None)
+ if current is None:
+ continue
+ path = Path(current['path'])
+ blocker = self._cleanup_blocker(db, current['id'], path)
+ if blocker:
+ failed.append(dict(name=current['name'], message=blocker))
+ continue
+ if not path.exists() and not path.is_symlink():
+ continue
+ try:
+ directory(path)
+ recycle.remove(path, recoverable=self.delete_mode == 'recycle_bin')
+ except (OSError, ProjectError) as error:
+ failed.append(dict(name=current['name'], message=str(error)))
+ continue
+ removed.append(current['name'])
+ if current['id']:
+ journal = self._journal(current['id'])
+ if journal.exists():
+ # The project is gone; its pending recovery must not recreate
+ # a permanent catalog warning on the next read.
+ journal.unlink()
+ sync_directory(self.intents)
+ with self.local.transaction() as db:
+ db.execute('DELETE FROM sessions WHERE path=?', (str(path),))
+ if current['id']:
+ db.execute('DELETE FROM sessions WHERE project_id=?', (current['id'],))
+ if removed:
+ sync_directory(self.root)
+ return dict(removed=removed, failed=failed)
diff --git a/packages/core/src/opendirector/infrastructure/creation_commit_log.py b/packages/core/src/opendirector/infrastructure/creation_commit_log.py
new file mode 100644
index 000000000..dff7c067f
--- /dev/null
+++ b/packages/core/src/opendirector/infrastructure/creation_commit_log.py
@@ -0,0 +1,376 @@
+"""Read and cache the immutable commit chain.
+
+Opening a project serves the head commit. Ancestry is proved by history reads
+and by a bounded background warm, never by trusting a bare timestamp.
+"""
+import threading
+from hashlib import sha256
+
+from opendirector.domain.projects import ProjectError
+from opendirector.infrastructure.creation_records import CommitRecord
+from opendirector.infrastructure.directories import directory
+from opendirector.infrastructure.local_projects import child, read_json
+
+
+# Every history read validates the whole commit chain, and each record holds a
+# full project snapshot. The cache must fit a long project's history: below
+# that, each read reparses every record from disk and holds the catalog lock
+# long enough to expire sessions and interrupt running jobs.
+RECORD_CACHE_ENTRIES = 4096
+RECORD_CACHE_BYTES = 512 * 1024 * 1024
+# Only the validated head of each open project is kept, so this stays small.
+CURRENT_CACHE_ENTRIES = 16
+# A head served without replaying its ancestry is validated in the background
+# so the first autosave after a cold open reuses the parsed chain. At most a
+# couple of warms run at once; more projects simply keep the lazy path.
+WARM_CONCURRENCY = 2
+WARM_ATTEMPTS = 64
+
+
+def _file_signature(file):
+ stat = file.stat(follow_symlinks=False)
+ return stat.st_dev, stat.st_ino, stat.st_size, stat.st_mtime_ns, stat.st_ctime_ns
+
+
+def _head_signature(path, head, verify_bytes=False):
+ """Cheap identity of a commit file, or None when it cannot be read."""
+ file = child(directory(child(path, 'commits')), f'{head}.json')
+ try:
+ signature = _file_signature(file)
+ if verify_bytes:
+ content = sha256(file.read_bytes()).digest()
+ if _file_signature(file) != signature:
+ return None
+ return (*signature, content)
+ return signature
+ except OSError:
+ return None
+
+
+class CommitLog:
+ """Validated commit records, the head cache, and history queries."""
+
+ def _record(self, path, head):
+ file = child(directory(child(path, 'commits')), f'{head}.json')
+ try:
+ before = _file_signature(file)
+ with self._cache_lock:
+ cached = self._records_cache.get(file)
+ if cached is not None:
+ self._records_cache.move_to_end(file)
+ # On platforms with reliable change times, a rewrite changes the
+ # signature (ctime/mtime/size/inode). Re-reading and re-hashing every
+ # historical commit on each read cost ~13 s per history query for a
+ # project with hundreds of commits, holding the catalog lock past the
+ # 15 s contention budget of unrelated saves. On Windows, verify bytes
+ # because the file signature can remain unchanged after a rewrite.
+ if cached and cached[0] == before and not self._verify_record_bytes:
+ # Private repository records are read-only. Public query
+ # boundaries copy returned values, not every historical snapshot.
+ return cached[1]
+ if cached and cached[0] == before and cached[2] is not None:
+ # Windows: ctime is creation time and mtime can be restored by
+ # an outside writer, so the recorded bytes are verified too.
+ content = sha256(file.read_bytes()).digest()
+ if _file_signature(file) != before:
+ raise ValueError('Commit changed during read')
+ if content != cached[2]:
+ raise ValueError('Commit content changed')
+ return cached[1]
+ raw = file.read_bytes() if self._verify_record_bytes else None
+ content = sha256(raw).digest() if raw is not None else None
+ if raw is not None and _file_signature(file) != before:
+ raise ValueError('Commit changed during read')
+ if cached and cached[0] == before and cached[2] == content:
+ self._records_cache.move_to_end(file)
+ return cached[1]
+ if cached:
+ with self._cache_lock:
+ removed = self._records_cache.pop(file, None)
+ if removed is not None:
+ self._records_cache_bytes -= removed[0][2]
+ record = CommitRecord.model_validate_json(raw) if raw is not None else CommitRecord.model_validate(read_json(file))
+ if _file_signature(file) != before:
+ raise ValueError('Commit changed during read')
+ if before[2] <= 8 * 1024 * 1024:
+ with self._cache_lock:
+ # Another reader (a warm or a caught-up changes() poll) may
+ # have installed this record while we parsed it; replacing
+ # it must subtract the replaced size or the budget drifts.
+ replaced = self._records_cache.pop(file, None)
+ if replaced is not None:
+ self._records_cache_bytes -= replaced[0][2]
+ self._records_cache[file] = (before, record, content)
+ self._records_cache_bytes += before[2]
+ while len(self._records_cache) > RECORD_CACHE_ENTRIES or self._records_cache_bytes > RECORD_CACHE_BYTES:
+ _, removed = self._records_cache.popitem(last=False)
+ self._records_cache_bytes -= removed[0][2]
+ return record
+ except (ValueError, TypeError, KeyError, FileNotFoundError):
+ raise ProjectError('工程提交记录缺失或损坏,已阻止自动覆盖。', 409, code='storage_unavailable') from None
+
+ def _history(self, path, manifest):
+ records, seen, head = [], set(), manifest.head
+ while head is not None:
+ if head in seen:
+ raise ProjectError('工程提交历史存在循环,原文件已保留。', 409, code='storage_unavailable')
+ seen.add(head)
+ record = self._record(path, head)
+ if record.command.commandId != head or record.snapshot.project.id != manifest.id:
+ raise ProjectError('工程提交身份不一致,原文件已保留。', 409, code='storage_unavailable')
+ if records:
+ newer = records[-1]
+ if newer.snapshot.eventCursor != record.snapshot.eventCursor + (1 if newer.event else 0):
+ raise ProjectError('工程变更游标不连续,原文件已保留。', 409, code='storage_unavailable')
+ records.append(record)
+ head = record.previousHead
+ if (not records or records[-1].command.type != 'project.create' or records[-1].snapshot.eventCursor != 1
+ or records[0].snapshot.project.name != manifest.name):
+ raise ProjectError('工程提交历史与清单不一致,原文件已保留。', 409, code='storage_unavailable')
+ # The chain behind this head is now proven; a head served earlier by
+ # the head-only fast path may be reused by caught-up change polling.
+ self._mark_validated(path, records[0].command.commandId)
+ return records
+
+ def _load(self, db, project_id):
+ path, manifest = self._find(db, project_id)
+ records = self._history(path, manifest)
+ return path, manifest, records
+
+ def _remember_current(self, path, record):
+ signature = _head_signature(path, record.command.commandId, self._verify_record_bytes)
+ if signature is None:
+ return
+ key = (str(path), str(record.command.commandId), signature)
+ with self._cache_lock:
+ self._current_cache[key] = (record, True)
+ self._current_cache.move_to_end(key)
+ while len(self._current_cache) > CURRENT_CACHE_ENTRIES:
+ self._current_cache.popitem(last=False)
+
+ def _mark_validated(self, path, head):
+ """A full replay proved this head; caught-up polling may now trust it."""
+ prefix = (str(path), str(head))
+ with self._cache_lock:
+ for key, value in list(self._current_cache.items()):
+ if key[0] == prefix[0] and key[1] == prefix[1] and not value[1]:
+ self._current_cache[key] = (value[0], True)
+
+ def _schedule_warm(self, path, manifest):
+ """Validate the ancestry behind a head that was served without replay.
+
+ The first autosave after a cold open replays the chain; warming it in
+ the background right after the open read keeps that save cheap. The
+ work is coalesced per (project, head) and bounded, never holds the
+ catalog lock and never changes a read result: a failed warm just
+ leaves the lazy path, and is not remembered as a successful proof.
+ """
+ key = (str(manifest.id), str(manifest.head))
+ with self._warm_lock:
+ if key in self._warming or key in self._warmed or len(self._warming) >= WARM_CONCURRENCY:
+ return
+ event = threading.Event()
+ self._warming[key] = event
+ thread = threading.Thread(target=self._warm, args=(path, manifest, key, event),
+ name='creation-history-warm', daemon=True)
+ try:
+ thread.start()
+ except BaseException:
+ # A start failure must not leave a key that every later await waits
+ # out. Anyone who already observed this event is released too.
+ with self._warm_lock:
+ if self._warming.get(key) is event:
+ self._warming.pop(key, None)
+ event.set()
+ raise
+
+ def _await_warm(self, project_id, head, timeout=30):
+ """Join validation of this head instead of replaying its chain twice.
+
+ A warm of a different head is ignored. The wait stays outside the
+ catalog lock, so a first autosave races one validation rather than
+ parsing every snapshot twice at once.
+ """
+ if head is None:
+ return
+ with self._warm_lock:
+ event = self._warming.get((str(project_id), str(head)))
+ if event is not None:
+ event.wait(timeout)
+
+ def _await_current_warm(self, project_id, timeout=30):
+ """Wait for a warm of the head this caller is about to read.
+
+ When nothing is in flight this returns without taking the catalog
+ lock. A missing project is left for the caller's own transaction.
+ """
+ project = str(project_id)
+ with self._warm_lock:
+ inflight = any(key[0] == project for key in self._warming)
+ if not inflight:
+ return
+ try:
+ head = self.head(project_id)
+ except ProjectError:
+ return
+ self._await_warm(project_id, head, timeout)
+
+ def _warm(self, path, manifest, key, event):
+ validated = False
+ try:
+ self._history(path, manifest)
+ validated = True
+ except BaseException:
+ # Reads stay correct: every path that needs the chain replays it
+ # itself and reports the integrity failure there. Leaving the key
+ # out of _warmed lets the next open retry a transient failure.
+ pass
+ finally:
+ with self._warm_lock:
+ if self._warming.get(key) is event:
+ self._warming.pop(key, None)
+ if validated:
+ self._warmed[key] = True
+ self._warmed.move_to_end(key)
+ while len(self._warmed) > WARM_ATTEMPTS:
+ self._warmed.popitem(last=False)
+ event.set()
+
+ def _current_record(self, db, project_id, path, manifest):
+ """The head commit and whether its ancestry has been replayed.
+
+ Opening a canvas must not parse every historical snapshot: a commit
+ leaves the old files alone (a commit file is immutable) and rewrites the
+ manifest, so the head file signature plus the manifest decides whether
+ the cached head is still current. Missing, corrupt or rewritten heads
+ still fail here; ancestors are proven by commit/history/receipt/changes
+ reads and by the background warm an open read schedules.
+ """
+ signature = _head_signature(path, manifest.head, self._verify_record_bytes)
+ key = (str(path), str(manifest.head), signature)
+ if signature is not None:
+ with self._cache_lock:
+ cached = self._current_cache.get(key)
+ if cached is not None:
+ self._current_cache.move_to_end(key)
+ return cached
+ record = self._record(path, manifest.head)
+ if (record.command.commandId != manifest.head or record.snapshot.project.id != manifest.id
+ or record.snapshot.project.name != manifest.name):
+ raise ProjectError('工程提交身份不一致,原文件已保留。', 409, code='storage_unavailable')
+ if record.previousHead is None:
+ # A single-commit project's whole history is this record; validate
+ # the creation invariants that a full replay would check.
+ if record.command.type != 'project.create' or record.snapshot.eventCursor != 1:
+ raise ProjectError('工程提交历史与清单不一致,原文件已保留。', 409, code='storage_unavailable')
+ validated = True
+ else:
+ validated = False
+ if signature is not None:
+ with self._cache_lock:
+ self._current_cache[key] = (record, validated)
+ self._current_cache.move_to_end(key)
+ while len(self._current_cache) > CURRENT_CACHE_ENTRIES:
+ self._current_cache.popitem(last=False)
+ return record, validated
+
+ def _current(self, db, project_id, path, manifest):
+ """The head commit, reused while its file is untouched.
+
+ Replaying and re-validating the whole chain for every read made opening
+ a canvas take about a second. A commit leaves the old files alone and
+ moves the head, and an outside rewrite changes the head file's
+ signature, so both are noticed without trusting a bare timestamp.
+ """
+ return self._current_record(db, project_id, path, manifest)[0]
+
+ def snapshot(self, project_id):
+ with self.local.transaction() as db:
+ self._recover()
+ path, manifest = self._find(db, project_id)
+ return self._current(db, project_id, path, manifest).snapshot.model_copy(deep=True)
+
+ def head(self, project_id):
+ """The current head commit, cheap enough to gate content-addressed caches.
+
+ It skips the journal recovery that snapshot() runs: a caller only uses
+ this to notice that a cached read is stale.
+ """
+ with self.local.transaction() as db:
+ return self._find(db, project_id)[1].head
+
+ def _read_manifest(self, project_id):
+ """Resolve the current head under the catalog lock.
+
+ Commit files are immutable once published, so the chain behind this head
+ can be walked without holding the lock: a slow read only delays itself,
+ not the saves and status polls that share the catalog.
+ """
+ with self.local.transaction() as db:
+ self._recover()
+ return self._find(db, project_id)
+
+ def records(self, project_id):
+ """Private commit records for read-only scans; callers must not mutate them.
+
+ history() deep-copies every snapshot for callers that keep the records
+ around. Scans that only count versions or owners would copy hundreds of
+ megabytes for long histories, so they read the shared records directly.
+ """
+ path, manifest = self._read_manifest(project_id)
+ return tuple(self._history(path, manifest))
+
+ def history(self, project_id):
+ records = self.records(project_id)
+ # Private records are never mutated. Copy for the public caller after
+ # releasing the global lock so large history reads do not block saves.
+ return tuple(record.model_copy(deep=True) for record in records)
+
+ def history_index(self, project_id):
+ """Small detached event metadata; toolbar queries need no snapshots."""
+ path, manifest = self._read_manifest(project_id)
+ records = self._history(path, manifest)
+ return records[0].snapshot.undoClearedThrough, tuple(dict(
+ commandId=r.command.commandId, type=r.command.type,
+ cursor=r.event.cursor, source=r.event.source,
+ targetCommandId=getattr(r.command.payload, 'targetCommandId', None),
+ ) for r in records if r.event is not None)
+
+ def receipt(self, project_id, command_id):
+ with self.local.transaction() as db:
+ self._recover()
+ records = self._load(db, project_id)[2]
+ found = next((record.receipt for record in records if str(record.command.commandId) == str(command_id)), None)
+ if found is None:
+ raise ProjectError('没有该命令的已提交回执。', 404)
+ return found.model_copy(deep=True)
+
+ def changes(self, project_id, *, after=0, limit=100):
+ if type(after) is not int or after < 0 or type(limit) is not int or not 1 <= limit <= 200:
+ raise ProjectError('变更游标或分页大小无效。')
+ # open() may already be proving this head. Joining that warm before the
+ # catalog lock keeps a caught-up subscriber from replaying the same
+ # chain while the lock is held.
+ self._await_current_warm(project_id)
+ with self.local.transaction() as db:
+ self._recover()
+ path, manifest = self._find(db, project_id)
+ # A subscriber that is already caught up is the common polling
+ # path. Replaying the commit chain here held the catalog lock for
+ # about a second per poll on Windows and starved saves/heartbeats.
+ head, validated = self._current_record(db, project_id, path, manifest)
+ cursor = head.snapshot.eventCursor
+ if after > cursor:
+ raise ProjectError('变更游标超出当前工程,请重新读取快照。', 409)
+ if after == cursor:
+ if not validated:
+ # A head served by the fast path has not proven its ancestry
+ # yet; the outbox is derived from the chain, so validate it
+ # before claiming there are no events.
+ self._history(path, manifest)
+ return dict(events=[], nextCursor=after, currentCursor=cursor, hasMore=False)
+ records = self._history(path, manifest)
+ events = [record.event for record in reversed(records) if record.event and record.event.cursor > after][:limit]
+ events = [event.model_copy(deep=True) for event in events]
+ return dict(events=events, nextCursor=events[-1].cursor if events else after,
+ currentCursor=cursor, hasMore=bool(events and events[-1].cursor < cursor))
diff --git a/packages/core/src/opendirector/infrastructure/creation_projects.py b/packages/core/src/opendirector/infrastructure/creation_projects.py
index 48fd50fe2..b02a3e8ba 100644
--- a/packages/core/src/opendirector/infrastructure/creation_projects.py
+++ b/packages/core/src/opendirector/infrastructure/creation_projects.py
@@ -4,168 +4,44 @@
A durable intent precedes every filesystem mutation. Publishing project.json
is the commit point; reads first finish pending intents under the catalog lock.
SQLite coordinates leases only and is never used to roll back file writes.
+
+Catalog scans, commit history, and publication live in sibling modules.
+Command dispatch lives in ``application.creation_commands``. ``execute`` delegates
+there so this module does not import application services.
"""
-from collections.abc import Callable
-from collections import OrderedDict
-from pathlib import Path
-from typing import Literal
-from uuid import UUID
-from hashlib import sha256
import os
import threading
import time
+from collections import OrderedDict
+from uuid import UUID
-from pydantic import Field, ValidationError, model_validator
-
-from opendirector.domain.creation.base import Contract, Digest, ObjectVersion, digest
-from opendirector.domain.creation.commands import Command, CommandReceipt, ProjectEvent, command_fingerprint
+from opendirector.domain.creation.base import digest
+from opendirector.domain.creation.commands import Command
from opendirector.domain.creation.index import object_index
from opendirector.domain.creation.project import Project, ProjectSnapshot, ViewState
from opendirector.domain.creation.validation import ContractError, validate_command
from opendirector.domain.projects import ProjectError, identifier, project_name
-from opendirector.ports.dispatch import command_dispatcher
-from opendirector.infrastructure.local_projects import LocalProjects, child, read_json, write_json
from opendirector.infrastructure import recycle
+from opendirector.infrastructure.creation_catalog import ProjectCatalog
+from opendirector.infrastructure.creation_commit_log import CommitLog
+from opendirector.infrastructure.creation_publication import CommitPublication
+from opendirector.infrastructure.creation_records import CommitIntent, CommitRecord, durable_json, object_changes
from opendirector.infrastructure.directories import directory, sync_directory
-from opendirector.infrastructure.rename import rename_path
-from opendirector.infrastructure.creation_files import cleanup_staging, delete_files, install_files
-from opendirector.ports.files import AssetFileDelete, AssetFileWrite
-
-
-class Manifest(Contract):
- format: Literal['opendirector-project'] = Field(default='opendirector-project', description='Serialized format identifier.')
- formatVersion: Literal[2] = Field(default=2, description='Project format version.')
- id: UUID = Field(description='Stable object ID.')
- name: str = Field(description='User-visible name.')
- head: UUID = Field(description='Current committed command ID.')
-
-
-class CommitRecord(Contract):
- schemaVersion: Literal[1] = Field(default=1, description='Record schema version.')
- command: Command = Field(description='Immutable command recorded in this commit.')
- previousHead: UUID | None = Field(description='Previous commit ID, or null for project creation.')
- snapshot: ProjectSnapshot = Field(description='Authoritative project snapshot.')
- receipt: CommandReceipt = Field(description='Immutable command execution receipt.')
- event: ProjectEvent | None = Field(description='Project change event, if emitted.')
-
- @model_validator(mode='after')
- def consistent(self):
- if (self.command.projectId != self.snapshot.project.id
- or self.receipt.projectId != self.command.projectId
- or self.receipt.commandId != self.command.commandId
- or self.receipt.inputFingerprint != command_fingerprint(self.command)
- or self.receipt.eventCursor != self.snapshot.eventCursor):
- raise ValueError('Commit identity is inconsistent')
- applied = self.receipt.status in {'applied', 'accepted'}
- if applied != (self.event is not None):
- raise ValueError('Only applied commits have outbox events')
- if self.event is not None:
- if (self.event.projectId != self.command.projectId or self.event.commandId != self.command.commandId
- or self.event.cursor != self.snapshot.eventCursor or self.event.jobIds != self.receipt.jobIds
- or tuple(change.version for change in self.event.changed) != self.receipt.changed):
- raise ValueError('Outbox event differs from the committed receipt')
- return self
-
-
-class CommitIntent(Contract):
- schemaVersion: Literal[1] = Field(default=1, description='Record schema version.')
- fromName: str | None = Field(description='Original project directory name.')
- toName: str = Field(description='Destination project directory name.')
- beforeFingerprint: Digest | None = Field(description='Fingerprint of the project before this commit.')
- record: CommitRecord = Field(description='Immutable commit awaiting publication.')
- files: tuple[AssetFileWrite, ...] = Field(default=(), description='Staged asset files installed before commit publication.')
- deletes: tuple[AssetFileDelete, ...] = Field(default=(), description='Asset file removals performed after publication.')
-
- @model_validator(mode='after')
- def consistent(self):
- project_name(self.toName)
- if self.fromName is not None:
- project_name(self.fromName)
- creating = self.fromName is None
- if creating != (self.record.previousHead is None) or creating != (self.beforeFingerprint is None):
- raise ValueError('Creation intent has no prior project')
- if creating and self.record.command.type != 'project.create':
- raise ValueError('First commit must create a project')
- ids = [write.assetId for write in self.files]
- if len(ids) != len(set(ids)):
- raise ValueError('File destinations must be unique')
- assets = {asset.id: asset for asset in self.record.snapshot.assets}
- created = {version.id for version in self.record.receipt.changed if version.objectType == 'asset'}
- for write in self.files:
- asset = assets.get(write.assetId)
- if (asset is None or asset.id not in created or asset.fingerprint != write.fingerprint
- or asset.metadata.size != write.size):
- raise ValueError('File write must match its committed asset')
- deleted = {change.version.id for change in self.record.event.changed if change.change == 'deleted' and change.version.objectType == 'asset'} if self.record.event else set()
- if any(value.assetId not in deleted or value.assetId in assets for value in self.deletes):
- raise ValueError('Deleted files must have committed asset deletions')
- return self
-
-
-def durable_json(path: Path, value):
- write_json(path, value)
- sync_directory(path.parent)
-
-
-def object_changes(before, after, command):
- """The storage boundary also checks revisions on trusted service writes."""
- old = object_index(before) if before else {}
- new = object_index(after)
- expected = {(item.objectType, item.id): item.revision for item in command.expectedVersions}
- changed = []
- for key in sorted(old.keys() | new.keys(), key=lambda item: (item[0], str(item[1]))):
- previous, current = old.get(key), new.get(key)
- if previous == current:
- continue
- kind, object_id = key
- if previous is not None and expected.get(key) != previous.revision:
- raise ContractError('revision_conflict', 'Every changed object requires its current version', object_id)
- if current is not None and current.revision != (previous.revision + 1 if previous else 1):
- raise ContractError('revision_conflict', 'Object revisions must advance exactly once', object_id)
- change = 'created' if previous is None else 'deleted' if current is None else 'updated'
- if kind == 'canvas_item' and previous and current and previous.visible and not current.visible:
- change = 'hidden'
- changed.append(dict(version=ObjectVersion(objectType=kind, id=object_id,
- revision=current.revision if current else previous.revision), change=change))
- return changed
-
-
-# Every history read validates the whole commit chain, and each record holds a
-# full project snapshot. The cache must fit a long project's history: below
-# that, each read reparses every record from disk and holds the catalog lock
-# long enough to expire sessions and interrupt running jobs.
-RECORD_CACHE_ENTRIES = 4096
-RECORD_CACHE_BYTES = 512 * 1024 * 1024
-# Only the validated head of each open project is kept, so this stays small.
-CURRENT_CACHE_ENTRIES = 16
-# A head served without replaying its ancestry is validated in the background
-# so the first autosave after a cold open reuses the parsed chain. At most a
-# couple of warms run at once; more projects simply keep the lazy path.
-WARM_CONCURRENCY = 2
-WARM_ATTEMPTS = 64
-
-
-def _file_signature(file):
- stat = file.stat(follow_symlinks=False)
- return stat.st_dev, stat.st_ino, stat.st_size, stat.st_mtime_ns, stat.st_ctime_ns
+from opendirector.infrastructure.local_projects import LocalProjects, child, read_json
+from opendirector.ports.dispatch import command_dispatcher
-def _head_signature(path, head, verify_bytes=False):
- """Cheap identity of a commit file, or None when it cannot be read."""
- file = child(directory(child(path, 'commits')), f'{head}.json')
- try:
- signature = _file_signature(file)
- if verify_bytes:
- content = sha256(file.read_bytes()).digest()
- if _file_signature(file) != signature:
- return None
- return (*signature, content)
- return signature
- except OSError:
- return None
+__all__ = [
+ 'CommitRecord',
+ 'CreationProjects',
+ 'directory',
+ 'durable_json',
+ 'object_index',
+ 'sync_directory',
+]
-class CreationProjects:
+class CreationProjects(ProjectCatalog, CommitLog, CommitPublication):
"""Authoritative repository for project commits and lifecycle storage.
commit() is an internal application-service boundary;
@@ -173,6 +49,7 @@ class CreationProjects:
Command routing lives in application.creation_commands. execute() delegates
there so this module does not import application services.
"""
+
def __init__(self, local: LocalProjects):
self.local = local
self.root = local.root
@@ -203,304 +80,6 @@ def __init__(self, local: LocalProjects):
def _checkpoint(self, stage):
"""Fault-injection boundary. Never participates in production decisions."""
- @staticmethod
- def _parse_manifest(raw):
- if not isinstance(raw, dict) or raw.get('format') != 'opendirector-project' or raw.get('formatVersion') != 2:
- raise ProjectError('不支持该工程格式;请创建新工程,旧文件不会自动转换。', 409, code='unsupported_format')
- try:
- value = Manifest.model_validate(raw)
- project_name(value.name)
- return value
- except (ValueError, TypeError):
- raise ProjectError('工程清单无效,原文件已保留。', 409, code='storage_unavailable') from None
-
- @classmethod
- def _manifest(cls, path):
- directory(path)
- return cls._parse_manifest(read_json(child(path, 'project.json')))
-
- def _scan(self):
- self.local._check_root()
- grouped, manifests, unsupported, warnings = {}, {}, set(), list(self._warnings)
- self._invalid = []
- if self.root.is_dir():
- for path in sorted(self.root.iterdir()):
- if path.is_symlink() or not path.is_dir() or path.name.startswith('.opendirector-'):
- continue
- manifest_path = path / 'project.json'
- if not manifest_path.exists() and not manifest_path.is_symlink():
- continue
- try:
- project_name(path.name)
- raw = read_json(child(path, 'project.json'))
- project_id = identifier(raw['id'])
- grouped.setdefault(project_id, []).append(path)
- if raw.get('format') != 'opendirector-project' or raw.get('formatVersion') != 2:
- unsupported.add(project_id)
- else:
- # Parsed once per scan; callers never reread project.json.
- manifests[project_id] = raw
- except (OSError, ValueError, TypeError, KeyError, ProjectError):
- warning = f'工程“{path.name}”的清单无法读取,原文件已保留。'
- warnings.append(warning)
- self._invalid.append((path, warning))
- conflicts = {key for key, paths in grouped.items() if len(paths) > 1}
- for key in sorted(conflicts):
- warnings.append(f'工程标识重复:{key};请移走重复目录后重试。')
- return grouped, manifests, unsupported, conflicts, warnings
-
- def _find(self, db, project_id):
- project_id = identifier(str(project_id))
- if project_id in self._blocked:
- raise ProjectError('工程提交需要恢复;请检查磁盘及工程文件后重试。', 409, code='storage_unavailable')
- grouped, manifests, unsupported, conflicts, _ = self._scan()
- if project_id in conflicts:
- raise ProjectError('projects 中存在同标识工程,请移走重复目录后重试。', 409)
- if project_id in unsupported:
- raise ProjectError('不支持该工程格式;请创建新工程,旧文件不会自动转换。', 409, code='unsupported_format')
- if project_id not in grouped:
- raise ProjectError('工程不在 projects 中或清单无法读取,请刷新工程列表。', 404)
- path = grouped[project_id][0]
- raw = manifests.get(project_id)
- if raw is None:
- # The manifest is present but invalid; report the precise reason.
- return path, self._manifest(path)
- return path, self._parse_manifest(raw)
-
- def _record(self, path, head):
- file = child(directory(child(path, 'commits')), f'{head}.json')
- try:
- before = _file_signature(file)
- with self._cache_lock:
- cached = self._records_cache.get(file)
- if cached is not None:
- self._records_cache.move_to_end(file)
- # On platforms with reliable change times, a rewrite changes the
- # signature (ctime/mtime/size/inode). Re-reading and re-hashing every
- # historical commit on each read cost ~13 s per history query for a
- # project with hundreds of commits, holding the catalog lock past the
- # 15 s contention budget of unrelated saves. On Windows, verify bytes
- # because the file signature can remain unchanged after a rewrite.
- if cached and cached[0] == before and not self._verify_record_bytes:
- # Private repository records are read-only. Public query
- # boundaries copy returned values, not every historical snapshot.
- return cached[1]
- if cached and cached[0] == before and cached[2] is not None:
- # Windows: ctime is creation time and mtime can be restored by
- # an outside writer, so the recorded bytes are verified too.
- content = sha256(file.read_bytes()).digest()
- if _file_signature(file) != before:
- raise ValueError('Commit changed during read')
- if content != cached[2]:
- raise ValueError('Commit content changed')
- return cached[1]
- raw = file.read_bytes() if self._verify_record_bytes else None
- content = sha256(raw).digest() if raw is not None else None
- if raw is not None and _file_signature(file) != before:
- raise ValueError('Commit changed during read')
- if cached and cached[0] == before and cached[2] == content:
- self._records_cache.move_to_end(file)
- return cached[1]
- if cached:
- with self._cache_lock:
- removed = self._records_cache.pop(file, None)
- if removed is not None:
- self._records_cache_bytes -= removed[0][2]
- record = CommitRecord.model_validate_json(raw) if raw is not None else CommitRecord.model_validate(read_json(file))
- if _file_signature(file) != before:
- raise ValueError('Commit changed during read')
- if before[2] <= 8 * 1024 * 1024:
- with self._cache_lock:
- # Another reader (a warm or a caught-up changes() poll) may
- # have installed this record while we parsed it; replacing
- # it must subtract the replaced size or the budget drifts.
- replaced = self._records_cache.pop(file, None)
- if replaced is not None:
- self._records_cache_bytes -= replaced[0][2]
- self._records_cache[file] = (before, record, content)
- self._records_cache_bytes += before[2]
- while len(self._records_cache) > RECORD_CACHE_ENTRIES or self._records_cache_bytes > RECORD_CACHE_BYTES:
- _, removed = self._records_cache.popitem(last=False)
- self._records_cache_bytes -= removed[0][2]
- return record
- except (ValueError, TypeError, KeyError, FileNotFoundError):
- raise ProjectError('工程提交记录缺失或损坏,已阻止自动覆盖。', 409, code='storage_unavailable') from None
-
- def _history(self, path, manifest):
- records, seen, head = [], set(), manifest.head
- while head is not None:
- if head in seen:
- raise ProjectError('工程提交历史存在循环,原文件已保留。', 409, code='storage_unavailable')
- seen.add(head)
- record = self._record(path, head)
- if record.command.commandId != head or record.snapshot.project.id != manifest.id:
- raise ProjectError('工程提交身份不一致,原文件已保留。', 409, code='storage_unavailable')
- if records:
- newer = records[-1]
- if newer.snapshot.eventCursor != record.snapshot.eventCursor + (1 if newer.event else 0):
- raise ProjectError('工程变更游标不连续,原文件已保留。', 409, code='storage_unavailable')
- records.append(record)
- head = record.previousHead
- if (not records or records[-1].command.type != 'project.create' or records[-1].snapshot.eventCursor != 1
- or records[0].snapshot.project.name != manifest.name):
- raise ProjectError('工程提交历史与清单不一致,原文件已保留。', 409, code='storage_unavailable')
- # The chain behind this head is now proven; a head served earlier by
- # the head-only fast path may be reused by caught-up change polling.
- self._mark_validated(path, records[0].command.commandId)
- return records
-
- def _load(self, db, project_id):
- path, manifest = self._find(db, project_id)
- records = self._history(path, manifest)
- return path, manifest, records
-
- def _remember_current(self, path, record):
- signature = _head_signature(path, record.command.commandId, self._verify_record_bytes)
- if signature is None:
- return
- key = (str(path), str(record.command.commandId), signature)
- with self._cache_lock:
- self._current_cache[key] = (record, True)
- self._current_cache.move_to_end(key)
- while len(self._current_cache) > CURRENT_CACHE_ENTRIES:
- self._current_cache.popitem(last=False)
-
- def _mark_validated(self, path, head):
- """A full replay proved this head; caught-up polling may now trust it."""
- prefix = (str(path), str(head))
- with self._cache_lock:
- for key, value in list(self._current_cache.items()):
- if key[0] == prefix[0] and key[1] == prefix[1] and not value[1]:
- self._current_cache[key] = (value[0], True)
-
- def _schedule_warm(self, path, manifest):
- """Validate the ancestry behind a head that was served without replay.
-
- The first autosave after a cold open replays the chain; warming it in
- the background right after the open read keeps that save cheap. The
- work is coalesced per (project, head) and bounded, never holds the
- catalog lock and never changes a read result: a failed warm just
- leaves the lazy path, and is not remembered as a successful proof.
- """
- key = (str(manifest.id), str(manifest.head))
- with self._warm_lock:
- if key in self._warming or key in self._warmed or len(self._warming) >= WARM_CONCURRENCY:
- return
- event = threading.Event()
- self._warming[key] = event
- thread = threading.Thread(target=self._warm, args=(path, manifest, key, event),
- name='creation-history-warm', daemon=True)
- try:
- thread.start()
- except BaseException:
- # A start failure must not leave a key that every later await waits
- # out. Anyone who already observed this event is released too.
- with self._warm_lock:
- if self._warming.get(key) is event:
- self._warming.pop(key, None)
- event.set()
- raise
-
- def _await_warm(self, project_id, head, timeout=30):
- """Join validation of this head instead of replaying its chain twice.
-
- A warm of a different head is ignored. The wait stays outside the
- catalog lock, so a first autosave races one validation rather than
- parsing every snapshot twice at once.
- """
- if head is None:
- return
- with self._warm_lock:
- event = self._warming.get((str(project_id), str(head)))
- if event is not None:
- event.wait(timeout)
-
- def _await_current_warm(self, project_id, timeout=30):
- """Wait for a warm of the head this caller is about to read.
-
- When nothing is in flight this returns without taking the catalog
- lock. A missing project is left for the caller's own transaction.
- """
- project = str(project_id)
- with self._warm_lock:
- inflight = any(key[0] == project for key in self._warming)
- if not inflight:
- return
- try:
- head = self.head(project_id)
- except ProjectError:
- return
- self._await_warm(project_id, head, timeout)
-
- def _warm(self, path, manifest, key, event):
- validated = False
- try:
- self._history(path, manifest)
- validated = True
- except BaseException:
- # Reads stay correct: every path that needs the chain replays it
- # itself and reports the integrity failure there. Leaving the key
- # out of _warmed lets the next open retry a transient failure.
- pass
- finally:
- with self._warm_lock:
- if self._warming.get(key) is event:
- self._warming.pop(key, None)
- if validated:
- self._warmed[key] = True
- self._warmed.move_to_end(key)
- while len(self._warmed) > WARM_ATTEMPTS:
- self._warmed.popitem(last=False)
- event.set()
-
- def _current_record(self, db, project_id, path, manifest):
- """The head commit and whether its ancestry has been replayed.
-
- Opening a canvas must not parse every historical snapshot: a commit
- leaves the old files alone (a commit file is immutable) and rewrites the
- manifest, so the head file signature plus the manifest decides whether
- the cached head is still current. Missing, corrupt or rewritten heads
- still fail here; ancestors are proven by commit/history/receipt/changes
- reads and by the background warm an open read schedules.
- """
- signature = _head_signature(path, manifest.head, self._verify_record_bytes)
- key = (str(path), str(manifest.head), signature)
- if signature is not None:
- with self._cache_lock:
- cached = self._current_cache.get(key)
- if cached is not None:
- self._current_cache.move_to_end(key)
- return cached
- record = self._record(path, manifest.head)
- if (record.command.commandId != manifest.head or record.snapshot.project.id != manifest.id
- or record.snapshot.project.name != manifest.name):
- raise ProjectError('工程提交身份不一致,原文件已保留。', 409, code='storage_unavailable')
- if record.previousHead is None:
- # A single-commit project's whole history is this record; validate
- # the creation invariants that a full replay would check.
- if record.command.type != 'project.create' or record.snapshot.eventCursor != 1:
- raise ProjectError('工程提交历史与清单不一致,原文件已保留。', 409, code='storage_unavailable')
- validated = True
- else:
- validated = False
- if signature is not None:
- with self._cache_lock:
- self._current_cache[key] = (record, validated)
- self._current_cache.move_to_end(key)
- while len(self._current_cache) > CURRENT_CACHE_ENTRIES:
- self._current_cache.popitem(last=False)
- return record, validated
-
- def _current(self, db, project_id, path, manifest):
- """The head commit, reused while its file is untouched.
-
- Replaying and re-validating the whole chain for every read made opening
- a canvas take about a second. A commit leaves the old files alone and
- moves the head, and an outside rewrite changes the head file's
- signature, so both are noticed without trusting a bare timestamp.
- """
- return self._current_record(db, project_id, path, manifest)[0]
-
def _lease(self, db, project_id, path, session):
if session is None:
raise ProjectError('修改工程需要已打开的会话。', 409)
@@ -522,168 +101,6 @@ def _closed(self, db, project_id, snapshot, verb='重命名'):
if tools.exists() and any(read_json(child(tools, item.name)).get('status') in {'queued', 'running'} for item in tools.glob('*.json')):
raise ProjectError(f'工程仍有工具任务,请等待或取消任务后再{verb}。', 409)
- @staticmethod
- def _unreadable_item(path, reason, project_id=None):
- return dict(id=project_id, name=path.name, path=str(path), reason=reason)
-
- def _catalog(self, db):
- # One directory scan for the whole listing: resolving each project with
- # _find() reread every project.json once per project (O(N^2)).
- grouped, manifests, unsupported, conflicts, warnings = self._scan()
- invalid = list(self._invalid)
- projects = []
- unreadable = [self._unreadable_item(path, reason) for path, reason in invalid]
- for project_id in sorted(grouped):
- paths = grouped[project_id]
- if project_id in unsupported:
- reason = f'工程 {project_id} 使用旧格式,统一工程接口不支持读取或转换。'
- warnings.append(reason)
- unreadable.extend(self._unreadable_item(path, reason, project_id) for path in paths)
- continue
- if project_id in conflicts:
- reason = f'工程标识重复:{project_id};请移走重复目录后重试。'
- unreadable.extend(self._unreadable_item(path, reason, project_id) for path in paths)
- continue
- try:
- if project_id in self._blocked:
- raise ProjectError('工程提交需要恢复;请检查磁盘及工程文件后重试。',
- 409, code='storage_unavailable')
- path = paths[0]
- raw = manifests.get(project_id)
- manifest = self._manifest(path) if raw is None else self._parse_manifest(raw)
- # Parsing the head alone proves the project still opens, and the
- # manifest already carries the name it must agree with; a full
- # chain replay just to list a name cost about a second.
- record = self._record(path, manifest.head)
- if record.snapshot.project.name != manifest.name:
- raise ProjectError('工程提交历史与清单不一致,原文件已保留。', 409, code='storage_unavailable')
- projects.append(dict(id=project_id, name=manifest.name, path=str(path)))
- except (ProjectError, OSError):
- reason = f'工程 {project_id} 需要恢复,原文件已保留。'
- warnings.append(reason)
- unreadable.append(self._unreadable_item(paths[0], reason, project_id))
- projects.sort(key=lambda item: (item['name'].casefold(), item['name']))
- unreadable.sort(key=lambda item: (item['name'].casefold(), item['name']))
- return dict(projects=projects, unreadable=unreadable, warnings=warnings)
-
- def list_projects(self):
- with self.local.transaction() as db:
- self._recover()
- return self._catalog(db)
-
- @staticmethod
- def _cleanup_blocker(db, project_id, path):
- active = db.execute('SELECT 1 FROM sessions WHERE expires>? AND (path=? OR project_id=?)',
- (time.time(), str(path), project_id or '')).fetchone()
- if active:
- return '工程仍在其他窗口中打开,请关闭后再清理。'
- tools = path / 'tool-tasks'
- if tools.exists() or tools.is_symlink():
- try:
- directory(tools)
- tasks = [read_json(child(tools, item.name)) for item in tools.glob('*.json')]
- if any(not isinstance(task, dict) for task in tasks):
- raise ValueError('Invalid tool task')
- except (OSError, ValueError, TypeError, KeyError, ProjectError):
- return '无法确认工具任务状态,请检查工程文件后再清理。'
- if any(task.get('status') in {'queued', 'running'} for task in tasks):
- return '工程仍有工具任务,请等待或取消任务后再清理。'
- return None
-
- def cleanup_unreadable(self):
- """Remove only directories that a fresh catalog read still cannot open."""
- with self.local.transaction() as db:
- self._recover()
- candidates = self._catalog(db)['unreadable']
- removed, failed = [], []
- for candidate in candidates:
- with self.local.transaction() as db:
- self._recover()
- current = next((item for item in self._catalog(db)['unreadable']
- if item['path'] == candidate['path']), None)
- if current is None:
- continue
- path = Path(current['path'])
- blocker = self._cleanup_blocker(db, current['id'], path)
- if blocker:
- failed.append(dict(name=current['name'], message=blocker))
- continue
- if not path.exists() and not path.is_symlink():
- continue
- try:
- directory(path)
- recycle.remove(path, recoverable=self.delete_mode == 'recycle_bin')
- except (OSError, ProjectError) as error:
- failed.append(dict(name=current['name'], message=str(error)))
- continue
- removed.append(current['name'])
- if current['id']:
- journal = self._journal(current['id'])
- if journal.exists():
- # The project is gone; its pending recovery must not recreate
- # a permanent catalog warning on the next read.
- journal.unlink()
- sync_directory(self.intents)
- with self.local.transaction() as db:
- db.execute('DELETE FROM sessions WHERE path=?', (str(path),))
- if current['id']:
- db.execute('DELETE FROM sessions WHERE project_id=?', (current['id'],))
- if removed:
- sync_directory(self.root)
- return dict(removed=removed, failed=failed)
-
- def snapshot(self, project_id):
- with self.local.transaction() as db:
- self._recover()
- path, manifest = self._find(db, project_id)
- return self._current(db, project_id, path, manifest).snapshot.model_copy(deep=True)
-
- def head(self, project_id):
- """The current head commit, cheap enough to gate content-addressed caches.
-
- It skips the journal recovery that snapshot() runs: a caller only uses
- this to notice that a cached read is stale.
- """
- with self.local.transaction() as db:
- return self._find(db, project_id)[1].head
-
- def _read_manifest(self, project_id):
- """Resolve the current head under the catalog lock.
-
- Commit files are immutable once published, so the chain behind this head
- can be walked without holding the lock: a slow read only delays itself,
- not the saves and status polls that share the catalog.
- """
- with self.local.transaction() as db:
- self._recover()
- return self._find(db, project_id)
-
- def records(self, project_id):
- """Private commit records for read-only scans; callers must not mutate them.
-
- history() deep-copies every snapshot for callers that keep the records
- around. Scans that only count versions or owners would copy hundreds of
- megabytes for long histories, so they read the shared records directly.
- """
- path, manifest = self._read_manifest(project_id)
- return tuple(self._history(path, manifest))
-
- def history(self, project_id):
- records = self.records(project_id)
- # Private records are never mutated. Copy for the public caller after
- # releasing the global lock so large history reads do not block saves.
- return tuple(record.model_copy(deep=True) for record in records)
-
- def history_index(self, project_id):
- """Small detached event metadata; toolbar queries need no snapshots."""
- path, manifest = self._read_manifest(project_id)
- records = self._history(path, manifest)
- return records[0].snapshot.undoClearedThrough, tuple(dict(
- commandId=r.command.commandId, type=r.command.type,
- cursor=r.event.cursor, source=r.event.source,
- targetCommandId=getattr(r.command.payload, 'targetCommandId', None),
- ) for r in records if r.event is not None)
-
def view(self, project_id, client_id, value=None, *, session=None, missing_ok=False):
with self.local.transaction() as db:
self._recover()
@@ -717,65 +134,10 @@ def open(self, project_id, session):
def heartbeat(self, session, project_id):
self.open(project_id, session)
- def receipt(self, project_id, command_id):
- with self.local.transaction() as db:
- self._recover()
- records = self._load(db, project_id)[2]
- found = next((record.receipt for record in records if str(record.command.commandId) == str(command_id)), None)
- if found is None:
- raise ProjectError('没有该命令的已提交回执。', 404)
- return found.model_copy(deep=True)
-
- def changes(self, project_id, *, after=0, limit=100):
- if type(after) is not int or after < 0 or type(limit) is not int or not 1 <= limit <= 200:
- raise ProjectError('变更游标或分页大小无效。')
- # open() may already be proving this head. Joining that warm before the
- # catalog lock keeps a caught-up subscriber from replaying the same
- # chain while the lock is held.
- self._await_current_warm(project_id)
- with self.local.transaction() as db:
- self._recover()
- path, manifest = self._find(db, project_id)
- # A subscriber that is already caught up is the common polling
- # path. Replaying the commit chain here held the catalog lock for
- # about a second per poll on Windows and starved saves/heartbeats.
- head, validated = self._current_record(db, project_id, path, manifest)
- cursor = head.snapshot.eventCursor
- if after > cursor:
- raise ProjectError('变更游标超出当前工程,请重新读取快照。', 409)
- if after == cursor:
- if not validated:
- # A head served by the fast path has not proven its ancestry
- # yet; the outbox is derived from the chain, so validate it
- # before claiming there are no events.
- self._history(path, manifest)
- return dict(events=[], nextCursor=after, currentCursor=cursor, hasMore=False)
- records = self._history(path, manifest)
- events = [record.event for record in reversed(records) if record.event and record.event.cursor > after][:limit]
- events = [event.model_copy(deep=True) for event in events]
- return dict(events=events, nextCursor=events[-1].cursor if events else after,
- currentCursor=cursor, hasMore=bool(events and events[-1].cursor < cursor))
-
def execute(self, command: Command, *, session=None, source='ui', imported_from=None):
return command_dispatcher().execute(
self, command, session=session, source=source, imported_from=imported_from)
- @staticmethod
- def _replay(records, command):
- record = next((item for item in records if item.command.commandId == command.commandId), None)
- if record is None:
- return None
- if record.receipt.inputFingerprint != command_fingerprint(command):
- raise ProjectError('该 commandId 已用于不同输入,请使用新的命令标识。', 409, code='command_conflict')
- return record.receipt.model_copy(deep=True)
-
- def replay(self, command):
- """Resolve an already committed command before reading upload handles."""
- self._await_current_warm(command.projectId)
- with self.local.transaction() as db:
- self._recover()
- return self._replay(self._load(db, command.projectId)[2], command)
-
def _create(self, command, source):
name = project_name(command.payload.name)
with self.local.transaction() as db:
@@ -870,214 +232,3 @@ def _trash(self, command, source):
raise ProjectError(str(error), 409, code='storage_unavailable') from error
sync_directory(self.root)
return receipt
-
- def commit(self, command: Command,
- apply: Callable[[ProjectSnapshot], ProjectSnapshot] | Callable[[ProjectSnapshot, tuple[CommitRecord, ...]], ProjectSnapshot], *,
- session=None, source='ui', files=(), deletes=(), with_history=False):
- if source not in {'ui', 'agent', 'background', 'external'}:
- raise ProjectError('无效的命令来源。')
- self._await_current_warm(command.projectId)
- with self.local.transaction() as db:
- self._recover()
- path, manifest, records = self._load(db, command.projectId)
- replay = self._replay(records, command)
- if replay:
- return replay
- before = records[0].snapshot
- if command.type == 'project.rename':
- self._closed(db, command.projectId, before)
- elif command.type == 'project.trash':
- self._closed(db, command.projectId, before, '删除')
- elif source not in {'background', 'external'}:
- # Only trusted server entrypoints select these sources. A
- # completed job must be able to save after its window closes.
- self._lease(db, command.projectId, path, session)
- issue, changed, snapshot = None, [], before
- try:
- validate_command(command, before)
- # Revalidate the whole graph, even if an internal caller used model_copy.
- draft = ProjectSnapshot.model_validate(before.model_dump(mode='json'))
- edited = apply(draft, tuple(records)) if with_history else apply(draft)
- snapshot = ProjectSnapshot.model_validate(edited.model_dump(mode='json'))
- if snapshot.project.id != before.project.id or snapshot.eventCursor != before.eventCursor:
- raise ContractError('invalid_input', 'Services cannot replace project identity or event cursors')
- if snapshot.project.name != before.project.name and command.type != 'project.rename':
- raise ContractError('invalid_input', 'Only the rename command can rename a project')
- changed = object_changes(before, snapshot, command)
- if command.type == 'project.rename':
- self.local._conflict(self.root, snapshot.project.name, path)
- except ContractError as error:
- issue = error.issue
- except ValidationError as error:
- failures = error.errors(include_input=False, include_url=False, include_context=False)
- paths = ['.'.join(str(part) for part in failure['loc']) for failure in failures]
- issue = dict(code='invalid_input', field=paths[0][:200] or None,
- message='; '.join(f"{path}: {failure['msg']}" if path else failure['msg']
- for path, failure in zip(paths, failures))[:500])
- except (ValueError, ProjectError) as error:
- issue = dict(code='invalid_input', message=str(error)[:500])
- if issue is not None:
- snapshot, changed = before, []
- elif changed:
- snapshot = ProjectSnapshot.model_validate({**snapshot.model_dump(), 'eventCursor': before.eventCursor + 1})
- record = self._make_record(command, manifest.head, snapshot, changed, source, issue)
- to_name = snapshot.project.name if command.type == 'project.rename' and changed else path.name
- return self._publish(CommitIntent(fromName=path.name, toName=to_name,
- beforeFingerprint=digest(before), record=record, files=files if changed and issue is None else (),
- deletes=deletes if changed and issue is None else ()), validated_history=True)
-
- @staticmethod
- def _make_record(command, head, snapshot, changed, source, issue=None):
- job_ids = tuple(item['version'].id for item in changed if item['version'].objectType == 'job' and item['change'] == 'created'
- and next(job for job in snapshot.jobs if job.id == item['version'].id).status == 'queued')
- event = ProjectEvent(projectId=command.projectId, cursor=snapshot.eventCursor, commandId=command.commandId,
- source=source, changed=changed, jobIds=job_ids) if changed else None
- receipt = CommandReceipt(commandId=command.commandId, projectId=command.projectId,
- inputFingerprint=command_fingerprint(command), status='rejected' if issue else 'accepted' if job_ids else 'applied' if changed else 'noop',
- changed=[item['version'] for item in changed], jobIds=job_ids, issues=[issue] if issue else [], eventCursor=snapshot.eventCursor)
- return CommitRecord(command=command, previousHead=head, snapshot=snapshot, receipt=receipt, event=event)
-
- def _journal(self, project_id):
- return child(directory(self.intents), f'{project_id}.json')
-
- def _temporary(self, intent):
- # Compact UUIDs retain both identities while keeping Windows staging
- # paths short enough for the longer application name.
- return child(self.root, f'.opendirector-creation-{intent.record.command.projectId.hex}-{intent.record.command.commandId.hex}')
-
- def _publish(self, intent, *, validated_history=False):
- self.intents.mkdir(exist_ok=True)
- sync_directory(self.state_dir)
- temporary = self._temporary(intent)
- if temporary.exists():
- raise ProjectError('提交临时目录已被占用,原目录未修改。', 409, code='storage_unavailable')
- journal = self._journal(intent.record.command.projectId)
- if journal.exists():
- raise ProjectError('工程已有待恢复的提交。', 409, code='storage_unavailable')
- durable_json(journal, intent.model_dump(mode='json'))
- self._checkpoint('journaled')
- self._finish(intent, validated_history=validated_history)
- return intent.record.receipt
-
- def _location(self, intent):
- target = child(self.root, intent.toName)
- temporary = self._temporary(intent)
- candidates = [temporary, target]
- if intent.fromName:
- candidates.append(child(self.root, intent.fromName))
- # Path.exists also accepts aliases on case-insensitive filesystems.
- existing_names = {entry.name for entry in self.root.iterdir()}
- locations = []
- for path in candidates:
- if path.name not in existing_names or not path.exists():
- continue
- directory(path)
- if any(path.samefile(other) for other in locations):
- continue
- manifest_path = child(path, 'project.json')
- if manifest_path.exists():
- manifest = self._manifest(path)
- if manifest.id == intent.record.command.projectId and manifest.head in {intent.record.previousHead, intent.record.command.commandId}:
- locations.append(path)
- elif path == temporary and intent.fromName is None:
- # A new directory can be interrupted before its first file is
- # installed. The durable intent owns only this reserved name.
- if any(item.name not in {'commits'} and not item.name.startswith('.opendirector-') for item in path.iterdir()):
- raise ProjectError('工程临时目录包含未知文件,已保留待检查。', 409)
- locations.append(path)
- if not locations and intent.fromName is None and not target.exists():
- temporary.mkdir()
- sync_directory(self.root)
- return temporary
- if len(locations) != 1:
- raise ProjectError('无法唯一定位待提交工程,原文件已保留。', 409, code='storage_unavailable')
- return locations[0]
-
- def _finish(self, intent, *, validated_history=False):
- self.local._check_root()
- path = self._location(intent)
- record = intent.record
- manifest_path = child(path, 'project.json')
- if manifest_path.exists():
- manifest = self._manifest(path)
- if manifest.head == record.previousHead:
- # Normal commits already verified ancestry under this lock.
- # Recovery still checks the full chain before publishing.
- previous = (self._record(path, manifest.head) if validated_history
- else self._history(path, manifest)[0])
- current = previous.snapshot
- if (previous.command.commandId != manifest.head or current.project.id != manifest.id
- or current.project.name != manifest.name or digest(current) != intent.beforeFingerprint):
- raise ProjectError('工程在提交期间被外部修改,已阻止覆盖。', 409, code='storage_unavailable')
- elif manifest.name != record.snapshot.project.name:
- raise ProjectError('已发布清单被外部修改,已阻止覆盖。', 409, code='storage_unavailable')
- self._checkpoint('directory_ready')
- install_files(path, record.command.projectId, intent.files, self.state_dir, self._checkpoint)
- if intent.files:
- self._checkpoint('files_installed')
- commits = directory(child(path, 'commits'))
- commits.mkdir(exist_ok=True)
- sync_directory(path)
- file = child(commits, f'{record.command.commandId}.json')
- if file.exists():
- if self._record(path, record.command.commandId) != record:
- raise ProjectError('已存在不同内容的提交记录,未覆盖。', 409, code='storage_unavailable')
- else:
- durable_json(file, record.model_dump(mode='json'))
- self._checkpoint('bundle_written')
- if intent.fromName is None:
- # Install identity before exposing a newly built directory. A crash
- # immediately after the move can then locate it unambiguously.
- manifest = Manifest(id=record.command.projectId, name=record.snapshot.project.name, head=record.command.commandId)
- durable_json(child(path, 'project.json'), manifest.model_dump(mode='json'))
- target, temporary = child(self.root, intent.toName), self._temporary(intent)
- if path.name != target.name:
- self.local._conflict(self.root, target.name, path)
- if path != temporary:
- rename_path(path, temporary)
- sync_directory(self.root)
- self._checkpoint('directory_staged')
- path = temporary
- self.local._conflict(self.root, target.name, path)
- rename_path(path, target)
- sync_directory(self.root)
- path = target
- self._checkpoint('directory_moved')
- manifest = Manifest(id=record.command.projectId, name=record.snapshot.project.name, head=record.command.commandId)
- durable_json(child(path, 'project.json'), manifest.model_dump(mode='json'))
- self._checkpoint('published')
- delete_files(path, intent.deletes)
- if intent.deletes:
- self._checkpoint('files_deleted')
- self._journal(record.command.projectId).unlink()
- sync_directory(self.intents)
- self._checkpoint('finished')
- # The record just published is the new head, so the read that follows a
- # save does not need to replay and re-parse the whole chain.
- self._remember_current(path, record)
- try:
- cleanup_staging(record.command.projectId, intent.files, self.state_dir)
- except (OSError, ProjectError):
- # Publication is already durable. Retained staging can be cleaned
- # by explicit upload cancellation without resubmitting the command.
- pass
-
- def _recover(self):
- self._blocked, self._warnings = {}, []
- directory(self.intents)
- if not self.intents.exists():
- return
- for file in sorted(self.intents.glob('*.json')):
- try:
- project_id = identifier(file.stem)
- except ProjectError:
- self._warnings.append('发现无法识别的提交日志,文件已保留。')
- continue
- try:
- intent = CommitIntent.model_validate(read_json(child(self.intents, file.name)))
- if str(intent.record.command.projectId) != project_id:
- raise ValueError('Journal filename differs from its project')
- self._finish(intent)
- except (OSError, ValueError, TypeError, KeyError, ProjectError):
- self._blocked[project_id] = True
- self._warnings.append(f'工程 {project_id} 的提交需要恢复,相关文件已保留。')
diff --git a/packages/core/src/opendirector/infrastructure/creation_publication.py b/packages/core/src/opendirector/infrastructure/creation_publication.py
new file mode 100644
index 000000000..da71c78aa
--- /dev/null
+++ b/packages/core/src/opendirector/infrastructure/creation_publication.py
@@ -0,0 +1,252 @@
+"""Publish one already-decided commit and finish a pending journal on read.
+
+The journal is written before any project file changes. ``project.json`` is the
+commit point. Recovery finishes that intent; it does not choose a new command.
+"""
+from collections.abc import Callable
+
+from pydantic import ValidationError
+
+from opendirector.domain.creation.base import digest
+from opendirector.domain.creation.commands import Command, CommandReceipt, ProjectEvent, command_fingerprint
+from opendirector.domain.creation.project import ProjectSnapshot
+from opendirector.domain.creation.validation import ContractError, validate_command
+from opendirector.domain.projects import ProjectError, identifier
+from opendirector.infrastructure.creation_files import cleanup_staging, delete_files, install_files
+from opendirector.infrastructure.creation_records import (
+ CommitIntent, CommitRecord, Manifest, durable_json, object_changes,
+)
+from opendirector.infrastructure.directories import directory, sync_directory
+from opendirector.infrastructure.local_projects import child, read_json
+from opendirector.infrastructure.rename import rename_path
+
+
+class CommitPublication:
+ """Idempotent commit publication and journal recovery."""
+
+ @staticmethod
+ def _replay(records, command):
+ record = next((item for item in records if item.command.commandId == command.commandId), None)
+ if record is None:
+ return None
+ if record.receipt.inputFingerprint != command_fingerprint(command):
+ raise ProjectError('该 commandId 已用于不同输入,请使用新的命令标识。', 409, code='command_conflict')
+ return record.receipt.model_copy(deep=True)
+
+ def replay(self, command):
+ """Resolve an already committed command before reading upload handles."""
+ self._await_current_warm(command.projectId)
+ with self.local.transaction() as db:
+ self._recover()
+ return self._replay(self._load(db, command.projectId)[2], command)
+
+ def commit(self, command: Command,
+ apply: Callable[[ProjectSnapshot], ProjectSnapshot] | Callable[[ProjectSnapshot, tuple[CommitRecord, ...]], ProjectSnapshot], *,
+ session=None, source='ui', files=(), deletes=(), with_history=False):
+ if source not in {'ui', 'agent', 'background', 'external'}:
+ raise ProjectError('无效的命令来源。')
+ self._await_current_warm(command.projectId)
+ with self.local.transaction() as db:
+ self._recover()
+ path, manifest, records = self._load(db, command.projectId)
+ replay = self._replay(records, command)
+ if replay:
+ return replay
+ before = records[0].snapshot
+ if command.type == 'project.rename':
+ self._closed(db, command.projectId, before)
+ elif command.type == 'project.trash':
+ self._closed(db, command.projectId, before, '删除')
+ elif source not in {'background', 'external'}:
+ # Only trusted server entrypoints select these sources. A
+ # completed job must be able to save after its window closes.
+ self._lease(db, command.projectId, path, session)
+ issue, changed, snapshot = None, [], before
+ try:
+ validate_command(command, before)
+ # Revalidate the whole graph, even if an internal caller used model_copy.
+ draft = ProjectSnapshot.model_validate(before.model_dump(mode='json'))
+ edited = apply(draft, tuple(records)) if with_history else apply(draft)
+ snapshot = ProjectSnapshot.model_validate(edited.model_dump(mode='json'))
+ if snapshot.project.id != before.project.id or snapshot.eventCursor != before.eventCursor:
+ raise ContractError('invalid_input', 'Services cannot replace project identity or event cursors')
+ if snapshot.project.name != before.project.name and command.type != 'project.rename':
+ raise ContractError('invalid_input', 'Only the rename command can rename a project')
+ changed = object_changes(before, snapshot, command)
+ if command.type == 'project.rename':
+ self.local._conflict(self.root, snapshot.project.name, path)
+ except ContractError as error:
+ issue = error.issue
+ except ValidationError as error:
+ failures = error.errors(include_input=False, include_url=False, include_context=False)
+ paths = ['.'.join(str(part) for part in failure['loc']) for failure in failures]
+ issue = dict(code='invalid_input', field=paths[0][:200] or None,
+ message='; '.join(f"{path}: {failure['msg']}" if path else failure['msg']
+ for path, failure in zip(paths, failures))[:500])
+ except (ValueError, ProjectError) as error:
+ issue = dict(code='invalid_input', message=str(error)[:500])
+ if issue is not None:
+ snapshot, changed = before, []
+ elif changed:
+ snapshot = ProjectSnapshot.model_validate({**snapshot.model_dump(), 'eventCursor': before.eventCursor + 1})
+ record = self._make_record(command, manifest.head, snapshot, changed, source, issue)
+ to_name = snapshot.project.name if command.type == 'project.rename' and changed else path.name
+ return self._publish(CommitIntent(fromName=path.name, toName=to_name,
+ beforeFingerprint=digest(before), record=record, files=files if changed and issue is None else (),
+ deletes=deletes if changed and issue is None else ()), validated_history=True)
+
+ @staticmethod
+ def _make_record(command, head, snapshot, changed, source, issue=None):
+ job_ids = tuple(item['version'].id for item in changed if item['version'].objectType == 'job' and item['change'] == 'created'
+ and next(job for job in snapshot.jobs if job.id == item['version'].id).status == 'queued')
+ event = ProjectEvent(projectId=command.projectId, cursor=snapshot.eventCursor, commandId=command.commandId,
+ source=source, changed=changed, jobIds=job_ids) if changed else None
+ receipt = CommandReceipt(commandId=command.commandId, projectId=command.projectId,
+ inputFingerprint=command_fingerprint(command), status='rejected' if issue else 'accepted' if job_ids else 'applied' if changed else 'noop',
+ changed=[item['version'] for item in changed], jobIds=job_ids, issues=[issue] if issue else [], eventCursor=snapshot.eventCursor)
+ return CommitRecord(command=command, previousHead=head, snapshot=snapshot, receipt=receipt, event=event)
+
+ def _journal(self, project_id):
+ return child(directory(self.intents), f'{project_id}.json')
+
+ def _temporary(self, intent):
+ # Compact UUIDs retain both identities while keeping Windows staging
+ # paths short enough for the longer application name.
+ return child(self.root, f'.opendirector-creation-{intent.record.command.projectId.hex}-{intent.record.command.commandId.hex}')
+
+ def _publish(self, intent, *, validated_history=False):
+ self.intents.mkdir(exist_ok=True)
+ sync_directory(self.state_dir)
+ temporary = self._temporary(intent)
+ if temporary.exists():
+ raise ProjectError('提交临时目录已被占用,原目录未修改。', 409, code='storage_unavailable')
+ journal = self._journal(intent.record.command.projectId)
+ if journal.exists():
+ raise ProjectError('工程已有待恢复的提交。', 409, code='storage_unavailable')
+ durable_json(journal, intent.model_dump(mode='json'))
+ self._checkpoint('journaled')
+ self._finish(intent, validated_history=validated_history)
+ return intent.record.receipt
+
+ def _location(self, intent):
+ target = child(self.root, intent.toName)
+ temporary = self._temporary(intent)
+ candidates = [temporary, target]
+ if intent.fromName:
+ candidates.append(child(self.root, intent.fromName))
+ # Path.exists also accepts aliases on case-insensitive filesystems.
+ existing_names = {entry.name for entry in self.root.iterdir()}
+ locations = []
+ for path in candidates:
+ if path.name not in existing_names or not path.exists():
+ continue
+ directory(path)
+ if any(path.samefile(other) for other in locations):
+ continue
+ manifest_path = child(path, 'project.json')
+ if manifest_path.exists():
+ manifest = self._manifest(path)
+ if manifest.id == intent.record.command.projectId and manifest.head in {intent.record.previousHead, intent.record.command.commandId}:
+ locations.append(path)
+ elif path == temporary and intent.fromName is None:
+ # A new directory can be interrupted before its first file is
+ # installed. The durable intent owns only this reserved name.
+ if any(item.name not in {'commits'} and not item.name.startswith('.opendirector-') for item in path.iterdir()):
+ raise ProjectError('工程临时目录包含未知文件,已保留待检查。', 409)
+ locations.append(path)
+ if not locations and intent.fromName is None and not target.exists():
+ temporary.mkdir()
+ sync_directory(self.root)
+ return temporary
+ if len(locations) != 1:
+ raise ProjectError('无法唯一定位待提交工程,原文件已保留。', 409, code='storage_unavailable')
+ return locations[0]
+
+ def _finish(self, intent, *, validated_history=False):
+ self.local._check_root()
+ path = self._location(intent)
+ record = intent.record
+ manifest_path = child(path, 'project.json')
+ if manifest_path.exists():
+ manifest = self._manifest(path)
+ if manifest.head == record.previousHead:
+ # Normal commits already verified ancestry under this lock.
+ # Recovery still checks the full chain before publishing.
+ previous = (self._record(path, manifest.head) if validated_history
+ else self._history(path, manifest)[0])
+ current = previous.snapshot
+ if (previous.command.commandId != manifest.head or current.project.id != manifest.id
+ or current.project.name != manifest.name or digest(current) != intent.beforeFingerprint):
+ raise ProjectError('工程在提交期间被外部修改,已阻止覆盖。', 409, code='storage_unavailable')
+ elif manifest.name != record.snapshot.project.name:
+ raise ProjectError('已发布清单被外部修改,已阻止覆盖。', 409, code='storage_unavailable')
+ self._checkpoint('directory_ready')
+ install_files(path, record.command.projectId, intent.files, self.state_dir, self._checkpoint)
+ if intent.files:
+ self._checkpoint('files_installed')
+ commits = directory(child(path, 'commits'))
+ commits.mkdir(exist_ok=True)
+ sync_directory(path)
+ file = child(commits, f'{record.command.commandId}.json')
+ if file.exists():
+ if self._record(path, record.command.commandId) != record:
+ raise ProjectError('已存在不同内容的提交记录,未覆盖。', 409, code='storage_unavailable')
+ else:
+ durable_json(file, record.model_dump(mode='json'))
+ self._checkpoint('bundle_written')
+ if intent.fromName is None:
+ # Install identity before exposing a newly built directory. A crash
+ # immediately after the move can then locate it unambiguously.
+ manifest = Manifest(id=record.command.projectId, name=record.snapshot.project.name, head=record.command.commandId)
+ durable_json(child(path, 'project.json'), manifest.model_dump(mode='json'))
+ target, temporary = child(self.root, intent.toName), self._temporary(intent)
+ if path.name != target.name:
+ self.local._conflict(self.root, target.name, path)
+ if path != temporary:
+ rename_path(path, temporary)
+ sync_directory(self.root)
+ self._checkpoint('directory_staged')
+ path = temporary
+ self.local._conflict(self.root, target.name, path)
+ rename_path(path, target)
+ sync_directory(self.root)
+ path = target
+ self._checkpoint('directory_moved')
+ manifest = Manifest(id=record.command.projectId, name=record.snapshot.project.name, head=record.command.commandId)
+ durable_json(child(path, 'project.json'), manifest.model_dump(mode='json'))
+ self._checkpoint('published')
+ delete_files(path, intent.deletes)
+ if intent.deletes:
+ self._checkpoint('files_deleted')
+ self._journal(record.command.projectId).unlink()
+ sync_directory(self.intents)
+ self._checkpoint('finished')
+ # The record just published is the new head, so the read that follows a
+ # save does not need to replay and re-parse the whole chain.
+ self._remember_current(path, record)
+ try:
+ cleanup_staging(record.command.projectId, intent.files, self.state_dir)
+ except (OSError, ProjectError):
+ # Publication is already durable. Retained staging can be cleaned
+ # by explicit upload cancellation without resubmitting the command.
+ pass
+
+ def _recover(self):
+ self._blocked, self._warnings = {}, []
+ directory(self.intents)
+ if not self.intents.exists():
+ return
+ for file in sorted(self.intents.glob('*.json')):
+ try:
+ project_id = identifier(file.stem)
+ except ProjectError:
+ self._warnings.append('发现无法识别的提交日志,文件已保留。')
+ continue
+ try:
+ intent = CommitIntent.model_validate(read_json(child(self.intents, file.name)))
+ if str(intent.record.command.projectId) != project_id:
+ raise ValueError('Journal filename differs from its project')
+ self._finish(intent)
+ except (OSError, ValueError, TypeError, KeyError, ProjectError):
+ self._blocked[project_id] = True
+ self._warnings.append(f'工程 {project_id} 的提交需要恢复,相关文件已保留。')
diff --git a/packages/core/src/opendirector/infrastructure/creation_records.py b/packages/core/src/opendirector/infrastructure/creation_records.py
new file mode 100644
index 000000000..c759fbd8b
--- /dev/null
+++ b/packages/core/src/opendirector/infrastructure/creation_records.py
@@ -0,0 +1,119 @@
+"""Commit documents published by project storage.
+
+A commit record fixes the command, snapshot, receipt, and optional outbox
+event. ``object_changes`` checks revisions when a service hands storage a new
+snapshot. Choosing which service runs a command stays in the application layer.
+"""
+from pathlib import Path
+from typing import Literal
+from uuid import UUID
+
+from pydantic import Field, model_validator
+
+from opendirector.domain.creation.base import Contract, Digest, ObjectVersion
+from opendirector.domain.creation.commands import Command, CommandReceipt, ProjectEvent, command_fingerprint
+from opendirector.domain.creation.index import object_index
+from opendirector.domain.creation.project import ProjectSnapshot
+from opendirector.domain.creation.validation import ContractError
+from opendirector.domain.projects import project_name
+from opendirector.infrastructure.directories import sync_directory
+from opendirector.infrastructure.local_projects import write_json
+from opendirector.ports.files import AssetFileDelete, AssetFileWrite
+
+
+class Manifest(Contract):
+ format: Literal['opendirector-project'] = Field(default='opendirector-project', description='Serialized format identifier.')
+ formatVersion: Literal[2] = Field(default=2, description='Project format version.')
+ id: UUID = Field(description='Stable object ID.')
+ name: str = Field(description='User-visible name.')
+ head: UUID = Field(description='Current committed command ID.')
+
+
+class CommitRecord(Contract):
+ schemaVersion: Literal[1] = Field(default=1, description='Record schema version.')
+ command: Command = Field(description='Immutable command recorded in this commit.')
+ previousHead: UUID | None = Field(description='Previous commit ID, or null for project creation.')
+ snapshot: ProjectSnapshot = Field(description='Authoritative project snapshot.')
+ receipt: CommandReceipt = Field(description='Immutable command execution receipt.')
+ event: ProjectEvent | None = Field(description='Project change event, if emitted.')
+
+ @model_validator(mode='after')
+ def consistent(self):
+ if (self.command.projectId != self.snapshot.project.id
+ or self.receipt.projectId != self.command.projectId
+ or self.receipt.commandId != self.command.commandId
+ or self.receipt.inputFingerprint != command_fingerprint(self.command)
+ or self.receipt.eventCursor != self.snapshot.eventCursor):
+ raise ValueError('Commit identity is inconsistent')
+ applied = self.receipt.status in {'applied', 'accepted'}
+ if applied != (self.event is not None):
+ raise ValueError('Only applied commits have outbox events')
+ if self.event is not None:
+ if (self.event.projectId != self.command.projectId or self.event.commandId != self.command.commandId
+ or self.event.cursor != self.snapshot.eventCursor or self.event.jobIds != self.receipt.jobIds
+ or tuple(change.version for change in self.event.changed) != self.receipt.changed):
+ raise ValueError('Outbox event differs from the committed receipt')
+ return self
+
+
+class CommitIntent(Contract):
+ schemaVersion: Literal[1] = Field(default=1, description='Record schema version.')
+ fromName: str | None = Field(description='Original project directory name.')
+ toName: str = Field(description='Destination project directory name.')
+ beforeFingerprint: Digest | None = Field(description='Fingerprint of the project before this commit.')
+ record: CommitRecord = Field(description='Immutable commit awaiting publication.')
+ files: tuple[AssetFileWrite, ...] = Field(default=(), description='Staged asset files installed before commit publication.')
+ deletes: tuple[AssetFileDelete, ...] = Field(default=(), description='Asset file removals performed after publication.')
+
+ @model_validator(mode='after')
+ def consistent(self):
+ project_name(self.toName)
+ if self.fromName is not None:
+ project_name(self.fromName)
+ creating = self.fromName is None
+ if creating != (self.record.previousHead is None) or creating != (self.beforeFingerprint is None):
+ raise ValueError('Creation intent has no prior project')
+ if creating and self.record.command.type != 'project.create':
+ raise ValueError('First commit must create a project')
+ ids = [write.assetId for write in self.files]
+ if len(ids) != len(set(ids)):
+ raise ValueError('File destinations must be unique')
+ assets = {asset.id: asset for asset in self.record.snapshot.assets}
+ created = {version.id for version in self.record.receipt.changed if version.objectType == 'asset'}
+ for write in self.files:
+ asset = assets.get(write.assetId)
+ if (asset is None or asset.id not in created or asset.fingerprint != write.fingerprint
+ or asset.metadata.size != write.size):
+ raise ValueError('File write must match its committed asset')
+ deleted = {change.version.id for change in self.record.event.changed if change.change == 'deleted' and change.version.objectType == 'asset'} if self.record.event else set()
+ if any(value.assetId not in deleted or value.assetId in assets for value in self.deletes):
+ raise ValueError('Deleted files must have committed asset deletions')
+ return self
+
+
+def durable_json(path: Path, value):
+ write_json(path, value)
+ sync_directory(path.parent)
+
+
+def object_changes(before, after, command):
+ """The storage boundary also checks revisions on trusted service writes."""
+ old = object_index(before) if before else {}
+ new = object_index(after)
+ expected = {(item.objectType, item.id): item.revision for item in command.expectedVersions}
+ changed = []
+ for key in sorted(old.keys() | new.keys(), key=lambda item: (item[0], str(item[1]))):
+ previous, current = old.get(key), new.get(key)
+ if previous == current:
+ continue
+ kind, object_id = key
+ if previous is not None and expected.get(key) != previous.revision:
+ raise ContractError('revision_conflict', 'Every changed object requires its current version', object_id)
+ if current is not None and current.revision != (previous.revision + 1 if previous else 1):
+ raise ContractError('revision_conflict', 'Object revisions must advance exactly once', object_id)
+ change = 'created' if previous is None else 'deleted' if current is None else 'updated'
+ if kind == 'canvas_item' and previous and current and previous.visible and not current.visible:
+ change = 'hidden'
+ changed.append(dict(version=ObjectVersion(objectType=kind, id=object_id,
+ revision=current.revision if current else previous.revision), change=change))
+ return changed
diff --git a/tests/test_creation_storage.py b/tests/test_creation_storage.py
index 28471f09b..03d556bcb 100644
--- a/tests/test_creation_storage.py
+++ b/tests/test_creation_storage.py
@@ -399,7 +399,7 @@ def test_symlinks_and_missing_commit_records_are_not_followed_or_replaced(projec
@pytest.mark.parametrize('change', ['in_place', 'replacement', 'missing'])
@pytest.mark.skipif(os.name == 'nt', reason='Commit signature caching requires POSIX change time')
def test_cached_history_still_detects_changed_ancestor_with_same_size_and_mtime(projects, monkeypatch, change):
- from opendirector.infrastructure import creation_projects as module
+ from opendirector.infrastructure import creation_commit_log as module
created = create(projects)
projects.execute(rename(created))
projects.changes(created.projectId)
@@ -434,7 +434,7 @@ def reading(path):
def test_long_history_is_validated_from_disk_only_once(projects, monkeypatch):
# Each read validates the whole chain; a cache smaller than the history
# would reparse every record on every read of a long project.
- from opendirector.infrastructure import creation_projects as module
+ from opendirector.infrastructure import creation_commit_log as module
created = create(projects)
for revision in range(1, 200):
assert projects.execute(rename(created, f'Renamed {revision}', revision)).status == 'applied'
@@ -472,9 +472,10 @@ def test_byte_verified_cache_detects_rewrites_with_unchanged_file_signature(proj
projects.execute(renamed)
key = renamed.commandId if victim == 'head' else created.commandId
file = projects.root / 'Renamed' / 'commits' / f'{key}.json'
- signature = creation_projects._file_signature(file)
- original_signature = creation_projects._file_signature
- monkeypatch.setattr(creation_projects, '_file_signature',
+ from opendirector.infrastructure import creation_commit_log
+ signature = creation_commit_log._file_signature(file)
+ original_signature = creation_commit_log._file_signature
+ monkeypatch.setattr(creation_commit_log, '_file_signature',
lambda path: signature if path == file else original_signature(path))
projects.history_index(created.projectId)
original = creation_projects.CommitRecord.model_validate_json
@@ -584,20 +585,20 @@ def test_paginated_outbox_has_no_duplicate_or_skipped_events(projects):
@pytest.mark.parametrize('file_kind', ['journal', 'bundle', 'manifest'])
def test_real_file_write_failure_preserves_recoverable_intent(projects, monkeypatch, file_kind):
- from opendirector.infrastructure import creation_projects
+ from opendirector.infrastructure import creation_records
created = create(projects)
command = rename(created)
- original = creation_projects.write_json
+ original = creation_records.write_json
def fail_write(path, value):
matches = (path.parent == projects.intents if file_kind == 'journal' else
path.name == f'{command.commandId}.json' if file_kind == 'bundle' else path.name == 'project.json')
if matches:
raise OSError('simulated disk full')
original(path, value)
- monkeypatch.setattr(creation_projects, 'write_json', fail_write)
+ monkeypatch.setattr(creation_records, 'write_json', fail_write)
with pytest.raises(OSError):
projects.execute(command)
- monkeypatch.setattr(creation_projects, 'write_json', original)
+ monkeypatch.setattr(creation_records, 'write_json', original)
restored = restarted(projects)
if file_kind == 'journal':
assert restored.snapshot(created.projectId).project.name == 'Example'
@@ -754,8 +755,9 @@ def test_list_projects_scans_directories_and_manifests_once(projects, monkeypatc
for index in range(8):
create(projects, f'Project {index}')
scans, manifests = [], []
+ from opendirector.infrastructure import creation_catalog
original_scan = creation_projects.CreationProjects._scan
- original_read = creation_projects.read_json
+ original_read = creation_catalog.read_json
def scanning(self):
scans.append(1)
@@ -767,7 +769,7 @@ def reading(path):
return original_read(path)
monkeypatch.setattr(creation_projects.CreationProjects, '_scan', scanning)
- monkeypatch.setattr(creation_projects, 'read_json', reading)
+ monkeypatch.setattr(creation_catalog, 'read_json', reading)
first = projects.list_projects()
assert len(first['projects']) == 8
# One directory scan and one manifest read per project, never per project pair.
From d0d60255f8f5ec982e93a871330c836d5f949bbb Mon Sep 17 00:00:00 2001
From: wuli666 <421774554@qq.com>
Date: Sun, 8 Nov 2026 14:55:57 +0800
Subject: [PATCH 03/61] [bugfix] providers: stop offering gpt-image as a cutout
matte (#223)
## summary
- gpt-image models no longer declare image.cutout. Their edits redraw
and move the subject, so the returned alpha does not line up with
the source pixels, and gpt-image-2 rejects transparent backgrounds.
Cutout without a selection or segmentation model now reports the
missing model instead of calling OpenAI.
- Add a regression test and update the gpt-image capability assertion.
## validation
- New test_gpt_image_is_never_used_as_a_cutout_matte fails without the
fix and passes with it; tests/test_openai_images.py passes.
- pytest tests: 1097 passed, 6 skipped.
- lint-imports: 4 kept; generate_contracts.py --check: verified.
- npm test: 675 passed.
Fixes: #222
---
.../opendirector/integrations/model_adapters.py | 5 ++++-
tests/test_openai_images.py | 2 +-
tests/test_tool_tasks.py | 17 +++++++++++++++++
3 files changed, 22 insertions(+), 2 deletions(-)
diff --git a/packages/core/src/opendirector/integrations/model_adapters.py b/packages/core/src/opendirector/integrations/model_adapters.py
index ce2338272..669571e11 100644
--- a/packages/core/src/opendirector/integrations/model_adapters.py
+++ b/packages/core/src/opendirector/integrations/model_adapters.py
@@ -676,7 +676,10 @@ def adapter_for(config, transport=None, poll_interval=3) -> ModelAdapter | None:
return ArkImageEdits(transport, poll_interval)
if kind == 'image' and profile == 'openai-gpt-image':
# gpt-image: base64 answers only, 16 reference images, documented sizes.
- return OpenAIImages(transport, poll_interval, max_images=16, transparent=True,
+ # No subject cutout: its edits redraw and move the subject, so a returned
+ # alpha does not line up with the source pixels, and gpt-image-2 rejects
+ # transparent backgrounds outright.
+ return OpenAIImages(transport, poll_interval, max_images=16,
response_format=False, reference_field='image[]')
if kind == 'image' and protocol == 'openai':
return OpenAIImages(transport, poll_interval)
diff --git a/tests/test_openai_images.py b/tests/test_openai_images.py
index 3d9e1be67..d91c42bf9 100644
--- a/tests/test_openai_images.py
+++ b/tests/test_openai_images.py
@@ -51,7 +51,7 @@ def test_adapter_drops_response_format_only_for_gpt_image(model):
adapter = adapter_for({**GPT_IMAGE, 'modelId': model})
assert isinstance(adapter, OpenAIImages) and adapter.response_format is False
assert adapter.reference_field == 'image[]' and adapter.max_images == 16
- assert adapter.capabilities == {'image.generate', 'image.edit', 'image.cutout'}
+ assert adapter.capabilities == {'image.generate', 'image.edit'}
assert adapter.size(1600, 900) == (1536, 1024)
# OpenAI-compatible services keep the vLLM-Omni request shape.
compatible = adapter_for({**GPT_IMAGE, 'modelId': 'Tongyi-MAI/Z-Image-Turbo', 'url': 'http://gpu-box:8200/v1'})
diff --git a/tests/test_tool_tasks.py b/tests/test_tool_tasks.py
index 94ab9d62d..0f066ab29 100644
--- a/tests/test_tool_tasks.py
+++ b/tests/test_tool_tasks.py
@@ -624,6 +624,23 @@ def test_cutout_applies_exact_user_mask_without_any_model(project):
assert result.getpixel((9, 8))[3] == 0 and result.getpixel((30, 20))[3] == 0
+def test_gpt_image_is_never_used_as_a_cutout_matte(project):
+ # gpt-image edits redraw and move the subject, so its alpha would not match the source pixels.
+ store, project_id, session = project
+ configs = ModelConfigs(store.local.repository)
+ configs.save('image', 'https://api.openai.com/v1', 'gpt-image-2', 'sk-test', protocol='openai')
+ source = upload(store, project_id, session, 'blue.png', png())
+ calls = []
+ transport = httpx.MockTransport(lambda request: calls.append(request) or httpx.Response(500))
+ with pytest.raises(ProjectError, match='主体抠图'):
+ run(store, configs, transport, project_id, session, {'tool': 'cutout', 'sourceAssetIds': [source]})
+ # A painted selection still cuts out locally, without calling the image service.
+ mask = upload(store, project_id, session, 'mask.png', base64.b64decode(box_mask((64, 48), (10, 8, 30, 32))))
+ task = run(store, configs, transport, project_id, session,
+ {'tool': 'cutout', 'sourceAssetIds': [source], 'maskAssetId': mask})
+ assert task['status'] == 'succeeded' and task['requires'] == [] and not calls
+
+
def test_cutout_uses_sam_when_no_rgba_editor_is_configured(project):
store, project_id, session = project
source = upload(store, project_id, session, 'blue.png', png())
From d96324dbec4b990888f9a26d6283b68aedc25a6e Mon Sep 17 00:00:00 2001
From: Hongsheng Liu
Date: Sun, 8 Nov 2026 18:07:31 +0800
Subject: [PATCH 04/61] [docs] add an animated GitHub star call-to-action
(#227)
## summary
Add a linked star demonstration to both READMEs with a reduced-motion
still image and a reproducible Pillow generator. The original repository
illustration contains no adoption counters or actual GitHub actions.
## validation
- Decode the GIF: 960x560, 5.6 seconds, infinite loop, matching seam.
- Inspect rendered still, pointer, click, and hold frames.
- Regenerate both assets and compare bytes; verify README asset links.
- npm run check:i18n and git diff --staged --check pass.
---
README.md | 11 ++
README.zh-CN.md | 11 ++
docs/guides/assets/star-opendirector.gif | Bin 0 -> 76655 bytes
docs/guides/assets/star-opendirector.png | Bin 0 -> 117199 bytes
scripts/generate_star_cta.py | 148 +++++++++++++++++++++++
5 files changed, 170 insertions(+)
create mode 100644 docs/guides/assets/star-opendirector.gif
create mode 100644 docs/guides/assets/star-opendirector.png
create mode 100644 scripts/generate_star_cta.py
diff --git a/README.md b/README.md
index fd4234be5..a6f6560fe 100644
--- a/README.md
+++ b/README.md
@@ -101,6 +101,17 @@ Join the **OpenDirector with vLLM-Omni (2)** WeChat group to discuss OpenDirecto
+If OpenDirector is useful to you, [give it a star on GitHub](https://github.com/ThinkFlowLab/OpenDirector) to support the project and help others discover it.
+
+
+
## Contributing
We welcome bug reports and suggestions through [Issues](https://github.com/ThinkFlowLab/OpenDirector/issues), and code and documentation contributions through pull requests. See the [validation guide (Chinese)](docs/development/validation.md) for development checks.
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 667ae880b..0240e7ca5 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -101,6 +101,17 @@ opendirector serve
+如果 OpenDirector 对你有帮助,欢迎[在 GitHub 上点亮 Star](https://github.com/ThinkFlowLab/OpenDirector),支持项目,也让更多人发现它。
+
+