@my-life-buddies/cli 0.2.0 → 0.4.0

package/resources/buddy-creator/scripts/buddy_core.py

@@ -311,6 +311,7 @@ def resolve_transition_refs(state, artifact):
 
 
 def put_artifacts(state, proposals, by, draft=False):
+    import widgets
     require(isinstance(proposals, list), 'PATCH_SCHEMA', 'artifacts 必须为数组。')
     ids = [a.get('id') for a in proposals if isinstance(a, dict)]
     require(len(ids) == len(proposals) and len(set(ids)) == len(ids), 'PATCH_SCHEMA', '每个产物必须是对象，且一次只能修改同一 ID 一次。')
@@ -319,6 +320,21 @@ def put_artifacts(state, proposals, by, draft=False):
     for item in proposals:
         required = {'id', 'stage', 'kind', 'title', 'markdown', 'evidence', 'dependencies', 'unresolved'}
         require(required <= set(item) and not set(item) - (required | {'data'}), 'ARTIFACT_SCHEMA', '产物字段必须包含 id、stage、kind、title、markdown、evidence、dependencies、unresolved，可选 data；不要提交 hash/revision。')
+        if item['kind'] in widgets.KINDS:
+            require(text(item['title']) and text(item['markdown']) and text_list(item['unresolved'], True), 'ARTIFACT_SCHEMA', '小挂件产物需要标题、说明及待补项。')
+            a = copy.deepcopy(item)
+            require(isinstance(a.get('data'), dict), 'ARTIFACT_DATA', '小挂件需要结构化 data。')
+            evidence(state, a['evidence'])
+            evidence(state, a['dependencies'])
+            for ref in a['dependencies']:
+                if ref['type'] == 'artifact':
+                    require(confirmed(state, ref['id']), 'UNCONFIRMED_DEPENDENCY', '依赖内容必须已确认。')
+            widgets.validate(state, a)
+            a['hash'] = digest(a)
+            if state['artifacts'].get(a['id'], {}).get('hash') != a['hash']:
+                changed.add(a['id'])
+            state['artifacts'][a['id']] = a
+            continue
         require(item['stage'] in stages and item['kind'] in KINDS and text(item['title']) and text(item['markdown']) and text_list(item['unresolved'], True), 'ARTIFACT_SCHEMA', '产物结构不完整。')
         require(stages.index(item['stage']) <= stages.index(state['stage']), 'STAGE_SCOPE', '上游手册尚未确认，不能生成后续阶段产物。')
         a = copy.deepcopy(item)
@@ -418,6 +434,9 @@ def transition_differences(state):
 
 
 def confirmation_blockers(state, artifact):
+    import widgets
+    if artifact['kind'] in widgets.KINDS:
+        return widgets.blockers(state, artifact)
     import interview
     result = {}
     if artifact['unresolved']:
@@ -465,16 +484,21 @@ def require_confirmation_ready(state, artifacts):
 
 def delivery_record(state, proposal, delivery_id, input_id=None, opening=False, explanation=False):
     import interview
+    import widgets
     require(isinstance(proposal, dict) and text(proposal.get('text')), 'DELIVERY_REQUIRED', '需要给用户的公开回复 text。')
-    require(not set(proposal) - {'text', 'question', 'confirmationObjectIds', 'confirmationScope', 'mode', 'blocked'}, 'DELIVERY_SCHEMA', 'delivery 包含未支持字段；请按协议提交。')
+    require(not set(proposal) - {'text', 'question', 'designQuestion', 'confirmationObjectIds', 'confirmationScope', 'mode', 'blocked'}, 'DELIVERY_SCHEMA', 'delivery 包含未支持字段；请按协议提交。')
     question, ids = proposal.get('question'), proposal.get('confirmationObjectIds')
+    design_question = proposal.get('designQuestion')
     if explanation:
-        require(not question and not ids and not proposal.get('blocked'), 'EXPLANATION_ONLY', '纯答疑保留原待答内容，不附加采访问题或确认。')
-    require(not (question and ids), 'ONE_REPLY_TARGET', '每轮一个核心问题或一次确认，不要同时提交两种。')
+        require(not question and not ids and not design_question and not proposal.get('blocked'), 'EXPLANATION_ONLY', '纯答疑保留原待答内容，不附加采访问题或确认。')
+    require(sum(bool(v) for v in (question, ids, design_question)) <= 1, 'ONE_REPLY_TARGET', '每轮一个核心问题或一次确认，不要同时提交两种。')
     result = {'id': delivery_id, 'text': proposal['text'], 'hash': digest(proposal['text']), 'createdAt': now(), 'mode': proposal.get('mode', 'ordinary'), 'inputId': input_id}
     # The host checks one semantic reply target. Quoted questions and context
     # length cannot reliably be judged by punctuation or character counts.
-    if question:
+    if design_question:
+        require(text(design_question) and widgets.enabled(state) and widgets.books_ready(state), 'WIDGET_STAGE', '小挂件补充问题在四册确认后提出，designQuestion 记录一个具体缺口。')
+        result['designQuestion'] = design_question
+    elif question:
         require(isinstance(question, dict) and 'targetId' in question and not set(question) - {'targetId', 'gapId'}, 'QUESTION_SCHEMA', 'question 使用 {targetId, gapId?}。')
         askable(state, question['targetId'])
         if result['mode'] == 'transition':
@@ -490,22 +514,23 @@ def delivery_record(state, proposal, delivery_id, input_id=None, opening=False,
         scope = proposal.get('confirmationScope', 'object')
         require(scope in {'object', 'booklet'}, 'CONFIRMATION_SCOPE', 'confirmationScope 使用 object 或 booklet。')
         if scope == 'booklet':
+            require(artifacts[0]['stage'] in catalog()['stages'], 'CONFIRMATION_SCOPE', '小挂件使用 object 确认，不新增第五册。')
             require(set(ids) == set(book_ids(artifacts[0]['stage'])), 'BOOKLET_INCOMPLETE', '整册确认必须包含该册全部固定章节。')
         result['confirmationTarget'] = {'scope': scope, 'stage': artifacts[0]['stage'], 'objects': [{'id': a['id'], 'hash': a['hash']} for a in artifacts]}
     blocked = proposal.get('blocked')
     if blocked is not None:
-        require(text(blocked) and not question and not ids, 'BLOCKED_SCHEMA', 'blocked 是具体阻塞及恢复条件，只在无合法下一步时使用。')
+        require(text(blocked) and not question and not ids and not design_question, 'BLOCKED_SCHEMA', 'blocked 是具体阻塞及恢复条件，只在无合法下一步时使用。')
         options = available(state)
         require(not options['questionTargets'] and not options['confirmationObjects'] and not options['canDraftBooklet'],
                 'NOT_BLOCKED', '还有可提问目标、可确认内容或可生成手册，须继续推进。')
         require(not all(book_confirmed(state, s) for s in catalog()['stages']), 'NOT_BLOCKED', '访谈已完成，不是阻塞。')
         result['blocked'] = blocked
         state.pop('questionDeliveryId', None)
-    if not explanation and not question and not ids and not blocked and not state['paused'] and not all(book_confirmed(state, s) for s in catalog()['stages']):
+    if not explanation and not question and not ids and not design_question and not blocked and not state['paused'] and (not all(book_confirmed(state, s) for s in catalog()['stages']) or not widgets.ready(state)):
         raise BuddyError('CONTINUATION_REQUIRED', '访谈还未完成：请在本轮给出下一条有效问题或确切内容确认，不能只回复“已保存”。若需要后台整理，先 draft_publish，再继续完成同一轮。')
     state['deliveries'][delivery_id] = result
     state['currentDeliveryId'] = delivery_id
-    if question or ids:
+    if question or ids or design_question:
         state['questionDeliveryId'] = delivery_id
     elif explanation:
         result['resumeDeliveryId'] = state.get('questionDeliveryId')
@@ -513,6 +538,7 @@ def delivery_record(state, proposal, delivery_id, input_id=None, opening=False,
 
 
 def available(state):
+    import widgets
     questions = []
     for target_id in catalog()['cards']:
         try:
@@ -520,12 +546,16 @@ def available(state):
             questions.append(target_id)
         except BuddyError:
             pass
-    return {'questionTargets': questions, 'confirmationObjects': [a['id'] for a in state['artifacts'].values() if a['stage'] == state['stage'] and confirmation_ready(state, a) and not any(confirmed(state, a['id'], d) for d in ['confirmed', 'accepted', 'rejected'])], 'canDraftBooklet': can_draft(state, state['stage'])}
+    candidates = [a['id'] for a in state['artifacts'].values()
+                  if (a['stage'] == state['stage'] or widgets.enabled(state) and a['kind'] in widgets.KINDS)
+                  and confirmation_ready(state, a) and not any(confirmed(state, a['id'], d) for d in ['confirmed', 'accepted', 'rejected'])]
+    return {'questionTargets': questions, 'confirmationObjects': candidates, 'canDraftBooklet': can_draft(state, state['stage']), 'designPhase': widgets.phase(state)}
 
 
 def context(workspace, state):
     import interview
-    return {'workspace': str(Path(workspace).resolve()), 'revision': state['revision'], 'stage': state['stage'], 'paused': state['paused'], 'pendingTurnId': state.get('pendingTurnId'), 'catalog': catalog(), 'gates': gates(state, state['stage']), 'continuation': available(state), 'interviewGuidance': interview.guidance(state), 'state': state, 'contract': str(ROOT / 'references' / 'host-guide.md'), 'note': '宿主负责真实语义判断，runtime 仅校验结构、证据版本、状态与确认关系。每轮先保存原话，再整理、保存、展示并登记实际展示；不能替用户确认。'}
+    import widgets
+    return {'workspace': str(Path(workspace).resolve()), 'revision': state['revision'], 'stage': state['stage'], 'paused': state['paused'], 'pendingTurnId': state.get('pendingTurnId'), 'catalog': catalog(), 'gates': gates(state, state['stage']), 'continuation': available(state), 'widgetDesign': widgets.projection(state, workspace), 'interviewGuidance': interview.guidance(state), 'state': state, 'contract': str(ROOT / 'references' / 'host-guide.md'), 'note': '宿主负责真实语义判断，runtime 仅校验结构、证据版本、状态与确认关系。每轮先保存原话，再整理、保存、展示并登记实际展示；不能替用户确认。'}
 
 
 def validate_initial_context(value):
@@ -576,6 +606,7 @@ def open_workspace(creation_key=None, workspace=None, initial_context=None):
             require(not unexpected, 'WORKSPACE_NOT_EMPTY', '新项目需要空目录；不能覆盖已有资料或 Node 版项目。', {'files': unexpected[:10]})
             cards = catalog()['cards']
             state = {'schemaVersion': SCHEMA, 'buddyId': base.name, 'workspaceId': 'workspace_' + digest(str(base))[:24], 'creationKeyHash': digest(creation_key), 'revision': '', 'stage': 'definition', 'paused': False, 'inputs': {}, 'turns': {}, 'pendingTurnId': None, 'deliveries': {}, 'presentations': [], 'currentDeliveryId': None, 'targets': {key: {'id': key, 'status': 'unstarted', 'summary': '', 'gaps': [], 'evidence': [], 'answerInputIds': []} for key in cards}, 'artifacts': {}, 'confirmations': [], 'sources': {}, 'sourcePlan': {'sourceIds': [], 'requiredKinds': [], 'discoveryClosed': False}, 'serviceMode': None, 'serviceModelExplained': False, 'drafts': [], 'updatedAt': now()}
+            state['widgetDesignVersion'] = 1
             if initial_context is None:
                 opening = (ROOT / 'references' / 'opening.md').read_text(encoding='utf-8').strip()
                 delivery_record(state, {'text': opening, 'question': {'targetId': 'D01'}, 'mode': 'opening'}, 'delivery_opening', opening=True)
@@ -598,8 +629,10 @@ def active_turn(state, turn_id):
     return turn
 
 
-def finish_turn(state, payload):
+def finish_turn(state, payload, workspace=None):
     import interview
+    import widgets
+    import widget_render
     turn = state['turns'].get(payload.get('turnId'))
     require(turn, 'TURN_NOT_FOUND', '未找到这一轮。')
     payload_hash = digest({k: v for k, v in payload.items() if k != 'operation'})
@@ -610,10 +643,15 @@ def finish_turn(state, payload):
     intent = payload.get('intent', 'answer')
     require(intent in {'answer', 'revision', 'confirmation', 'explanation', 'pause', 'resume'}, 'INTENT_SCHEMA', 'intent 使用 answer/revision/confirmation/explanation/pause/resume。')
     patch = payload.get('patch', {})
-    require(isinstance(patch, dict) and not set(patch) - {'targets', 'artifacts', 'confirmations', 'sourcePlan', 'serviceMode', 'serviceModelExplained', 'paused', 'interview'}, 'PATCH_SCHEMA', 'patch 包含未支持字段。')
+    require(isinstance(patch, dict) and not set(patch) - {'targets', 'artifacts', 'confirmations', 'sourcePlan', 'serviceMode', 'serviceModelExplained', 'paused', 'interview', 'enableWidgetDesign'}, 'PATCH_SCHEMA', 'patch 包含未支持字段。')
     inp = state['inputs'][turn['inputId']]
     if intent == 'explanation':
         require(not patch, 'EXPLANATION_ONLY', '纯答疑不修改采访目标、产物或确认；需要修订时使用 revision。')
+    if 'enableWidgetDesign' in patch:
+        request = patch['enableWidgetDesign']
+        require(isinstance(request, dict) and set(request) == {'evidence'}, 'WIDGET_OPT_IN', '旧作品追加设计需引用本轮开发者的明确请求。')
+        evidence(state, request['evidence'], inp['id'])
+        state['widgetDesignVersion'] = 1
     replied = state['deliveries'].get(inp.get('replyToDeliveryId'), {})
     target_id = replied.get('question', {}).get('targetId')
     interview_patch = patch.get('interview', {})
@@ -666,8 +704,23 @@ def finish_turn(state, payload):
         require(isinstance(patch['paused'], bool), 'PAUSED_SCHEMA', 'paused 使用布尔值，仅按用户明确暂停/恢复意愿设置。')
         state['paused'] = patch['paused']
     proposals = patch.get('artifacts', [])
+    for record in patch.get('confirmations', []):
+        artifact = state['artifacts'].get(record.get('objectId'), {})
+        if artifact.get('kind') in {'widget-prototype', 'widget-acceptance'}:
+            prototype = artifact if artifact['kind'] == 'widget-prototype' else state['artifacts'].get(widgets.object_id(artifact['data']['widgetId']))
+            require(workspace, 'WIDGET_ASSETS_REQUIRED', '通过工作目录调用以校验实际原型资源。')
+            widget_render.require_assets(workspace, state, prototype)
     record_confirmations(state, turn, patch.get('confirmations', []), {a.get('id') for a in proposals})
     put_artifacts(state, proposals, turn['id'])
+    for proposal in proposals:
+        if proposal['kind'] == 'widget-prototype' and workspace:
+            widget_render.render(workspace, state, state['artifacts'][proposal['id']])
+    for key in (payload.get('delivery') or {}).get('confirmationObjectIds', []):
+        artifact = state['artifacts'].get(key, {})
+        if artifact.get('kind') in {'widget-prototype', 'widget-acceptance'}:
+            prototype = artifact if artifact['kind'] == 'widget-prototype' else state['artifacts'].get(widgets.object_id(artifact['data']['widgetId']))
+            require(workspace, 'WIDGET_ASSETS_REQUIRED', '先生成实际原型，再展示确认。')
+            widget_render.require_assets(workspace, state, prototype)
     # Faithful base-case capture is a user answer, not invented consent to a new proposal.
     for proposal in proposals:
         if proposal['kind'] == 'scenario' and proposal['id'].startswith('scenario.M') and proposal.get('data', {}).get('capture') == 'faithful_user_answer':
@@ -686,7 +739,7 @@ def finish_turn(state, payload):
 def call(workspace, payload):
     require(isinstance(payload, dict), 'REQUEST_SCHEMA', '请求必须为 JSON 对象。')
     operation = payload.get('operation')
-    require(operation in {'opening_set', 'turn_begin', 'turn_finish', 'turn_continue', 'presentation_record', 'draft_publish', 'source_import', 'finalize', 'snapshot'}, 'OPERATION_UNKNOWN', '未知 operation。')
+    require(operation in {'opening_set', 'turn_begin', 'turn_finish', 'turn_continue', 'presentation_record', 'draft_publish', 'source_import', 'widget_render', 'finalize', 'snapshot'}, 'OPERATION_UNKNOWN', '未知 operation。')
     workspace = Path(workspace).expanduser().resolve()
     completion_needed = False
     with workspace_lock(workspace):
@@ -739,7 +792,7 @@ def call(workspace, payload):
                 result = {'turn': turn, 'input': inp, 'directive': 'prepare_turn'}
                 changed = True
         elif operation == 'turn_finish':
-            delivery, changed = finish_turn(state, payload)
+            delivery, changed = finish_turn(state, payload, workspace)
             result = {'delivery': delivery, 'turn': state['turns'][payload['turnId']], 'directive': 'present_delivery'}
             completion_needed = all(book_confirmed(state, stage) for stage in catalog()['stages'])
         elif operation == 'turn_continue':
@@ -780,8 +833,17 @@ def call(workspace, payload):
             state['sources'][manifest['id']] = manifest
             changed = old != manifest
             result = {'source': manifest, 'directive': 'source_ready' if manifest.get('status') == 'ready' else 'source_action_required'}
+        elif operation == 'widget_render':
+            import widget_render
+            import widgets
+            artifact = state['artifacts'].get(payload.get('objectId'), {})
+            require(artifact.get('kind') == 'widget-prototype' and not widgets.blockers(state, artifact), 'WIDGET_RENDER_SCOPE', '仅重新生成当前清单的有效原型，不改动确认记录。')
+            widget_render.render(workspace, state, artifact)
+            result = {'assets': widget_render.asset_status(workspace, artifact, state)}
         elif operation == 'finalize':
             require(all(book_confirmed(state, stage) for stage in catalog()['stages']), 'BOOKLETS_UNCONFIRMED', '四册还未全部确认，暂不能完成交付。')
+            import widgets
+            require(widgets.ready(state), 'WIDGET_DESIGN_UNCONFIRMED', '小挂件清单、原型或设计验收尚未确认。', {'phase': widgets.phase(state)})
             completion_needed = True
         else:
             import preview

package/resources/buddy-creator/scripts/completion.py

@@ -8,6 +8,7 @@ import shutil
 import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
+from buddy_core import BuddyError
 
 LABELS = {'definition': '定义', 'knowledge': '知识', 'methods': '方法', 'service': '服务'}
 
@@ -43,9 +44,46 @@ def _confirmed(state, object_id):
 
 
 def _ready(state, catalog):
+    import widgets
     return not state.get('paused') and not state.get('pendingTurnId') and all(
         _confirmed(state, '%s.%d' % (stage, index + 1))
-        for stage in catalog['stages'] for index in range(len(catalog['chapters'][stage])))
+        for stage in catalog['stages'] for index in range(len(catalog['chapters'][stage]))) and widgets.ready(state)
+
+
+def widget_files(workspace, state):
+    import widgets
+    import widget_render
+    if not widgets.enabled(state):
+        return {}
+    catalog = state['artifacts'][widgets.CATALOG]
+    files = {'widgets/catalog.json': _bytes(catalog)}
+    guide = ['# 小挂件交互设计', '', '已完成设计验收；真实会话数据接入、生产 H5 和端到端功能验收由后续开发完成。', '',
+             '小挂件只读。筛选、切换、折叠和浮层只改变阅读状态；编辑统一通过对话完成。',
+             '展开页宽度：屏幕逻辑宽度 − 32；高度：屏幕逻辑高度 × 65%；内容区上下滚动。标题建议 16 Medium、最大 20；正文 16 Regular。', '', catalog['markdown'], '']
+    if not widgets.items(state):
+        guide.extend(['本作品已明确确认不使用小挂件。', catalog['data']['noWidgetsReason'], ''])
+    for item in widgets.items(state):
+        prototype = state['artifacts'][widgets.object_id(item['id'])]
+        acceptance = state['artifacts'][widgets.object_id(item['id'], 'acceptance')]
+        widget_render.require_assets(workspace, state, prototype)
+        prefix = 'widgets/' + item['id'] + '/'
+        for name, raw in widget_render.files(prototype, item).items():
+            files[prefix + name] = raw
+        files[prefix + 'prototype.json'] = _bytes(prototype)
+        files[prefix + 'acceptance.json'] = _bytes({'artifact': acceptance, 'automaticCheck': widget_render.asset_status(workspace, prototype, state),
+            'developerConfirmations': [c for c in state['confirmations'] if c['objectId'] in (prototype['id'], acceptance['id']) and not c.get('invalidatedBy')]})
+        review_labels = {'booklet-fit': '符合搭子需求', 'reading-order': '阅读顺序、长内容与区分度',
+                         'chat-consistency': '对话卡片与展开页一致', 'conversation-update': '数据随对话逐步更新',
+                         'read-only': '只读交互边界'}
+        guide.extend(['## ' + item['name'], '', prototype['markdown'], '',
+                      '[打开可阅读原型](' + prefix + 'index.html)', '',
+                      '原型含首次生成、逐步补充、对话更新三态；每态提供对话卡片与展开页 SVG。H5 原型通过 ?view=expanded&state=partial 等参数查看。', '',
+                      '### 设计验收', '', '当前原型及本版设计验收均已确认。原始确认稿与确认凭据保留在对应 JSON 文件中。', '',
+                      '原型版本：' + prototype['hash'], ''])
+        for key in widgets.REVIEW_CHECKS:
+            guide.extend(['#### ' + review_labels[key], '', acceptance['data']['reviews'][key], ''])
+    files['WIDGET_DESIGN.md'] = '\n'.join(guide).encode('utf-8')
+    return files
 
 
 def _line_chunks(text, columns=32, limit=3):
@@ -128,10 +166,14 @@ def snapshot(workspace, state):
         record = json.loads(path.read_text(encoding='utf-8'))
         if record.get('revision') != state.get('revision'):
             return None
-        if record.get('status') == 'ready' and not (Path(record['directory']) / 'BUDDY_MANUAL.md').is_file():
-            record['status'] = 'failed'
-            record['message'] = '四册确认已保留，本地成果需要重新生成。'
-        return {key: record.get(key) for key in ('revision', 'status', 'message', 'fileCount', 'updatedAt')}
+        checked = return_to_caller(workspace, state, {})
+        if checked.get('completion'):
+            record.update(checked['completion'])
+        result = {key: record.get(key) for key in ('revision', 'status', 'message', 'fileCount', 'updatedAt')}
+        if checked.get('directive') == 'creator_complete':
+            inventory = json.loads((Path(record['directory']) / 'MANIFEST.json').read_text(encoding='utf-8'))
+            result['files'] = [entry['path'] for entry in inventory['files']]
+        return result
     except (OSError, ValueError, KeyError):
         return None
 
@@ -161,10 +203,19 @@ def return_to_caller(workspace, state, result):
                 or inventory.get('complete') is not True or len(entries) != 1
                 or _hash(manual.read_bytes()) != entries[0]['sha256']):
             raise ValueError('手册与已确认成果不一致。')
+        import widgets
+        if widgets.enabled(state):
+            required = {'BUDDY_MANUAL.md', 'SERVICE_MODEL.svg', 'service-blueprint.json', 'versions.json', 'sources.json'} | {'booklets/' + s + '.md' for s in catalog['stages']} | set(widget_files(workspace, state))
+            if {entry['path'] for entry in inventory['files']} != required or len(inventory['files']) != len(required):
+                raise ValueError('交付文件清单缺项或重复。')
+            for entry in inventory['files']:
+                target = directory / entry['path']
+                if any(p.is_symlink() for p in [target, *target.parents] if p != workspace.parent) or _hash(target.read_bytes()) != entry['sha256']:
+                    raise ValueError('交付文件缺失或被修改：' + entry['path'])
         result['completion'] = {key: record[key] for key in
                                 ('revision', 'status', 'directory', 'manualPath', 'fileCount', 'message', 'updatedAt')}
         result['directive'] = 'creator_complete'
-    except (OSError, ValueError, KeyError, TypeError) as error:
+    except (OSError, ValueError, KeyError, TypeError, BuddyError) as error:
         # Never hand off a stale path or a success-shaped but unusable export.
         result['completion'] = {'revision': state.get('revision'), 'status': 'failed',
                                 'message': '四册确认已保留，当前成果缺失、失效或被修改；先用 finalize 恢复交付。',
@@ -199,13 +250,18 @@ def finalize(workspace, state):
             manual.extend([text, ''])
         manual.extend(['## 服务模式图', '', '![服务模式](SERVICE_MODEL.svg)', '',
                        '本手册记录已确认的创作设计，后续开发、内容核实和实际履约仍按具体项目推进。', ''])
+        import widgets
+        if widgets.enabled(state):
+            files.update(widget_files(workspace, state))
+            manual.extend(['## 小挂件交互设计', '', '[小挂件清单、原型与设计验收](WIDGET_DESIGN.md)', '',
+                           '只读 H5 模板由开发者前置定义，对话负责创建与逐步更新实例数据。', ''])
         files['BUDDY_MANUAL.md'] = '\n'.join(manual).encode('utf-8')
         files['SERVICE_MODEL.svg'] = _diagram(state).encode('utf-8')
         files['service-blueprint.json'] = _bytes({
             'data': _blueprint(state),
             'sourceArtifact': {key: state['artifacts'].get('service.blueprint', {}).get(key) for key in ('id', 'hash')},
             'transitionArtifacts': [{key: artifact.get(key) for key in ('id', 'hash')} for artifact in state['artifacts'].values() if artifact.get('kind') == 'transition']})
-        files['versions.json'] = _bytes({'buddyId': state['buddyId'], 'revision': revision,
+        files['versions.json'] = _bytes({'buddyId': state['buddyId'], 'revision': revision, 'bookletRevision': widgets.booklet_revision(state),
                                         'artifacts': state['artifacts'], 'confirmations': state['confirmations']})
         files['sources.json'] = _bytes(list(state.get('sources', {}).values()))
         files['MANIFEST.json'] = _bytes({'format': 'buddy-creator-1', 'buddyId': state['buddyId'],
@@ -230,7 +286,7 @@ def finalize(workspace, state):
             os.replace(str(staging), str(output))
             staging = None
         record.update(status='ready', directory=str(output), manualPath=str(output / 'BUDDY_MANUAL.md'),
-                      fileCount=len(files), message='四册已确认，创作手册和服务模式图已保存在本机。')
+                      fileCount=len(files), message='四册及小挂件设计已确认，手册、原型和验收记录已保存在本机。' if widgets.enabled(state) else '四册已确认，创作手册和服务模式图已保存在本机。')
     except Exception as error:
         record.update(status='failed', error=str(error), message='四册确认已保留，本地成果生成需要重试。')
     finally:

package/resources/buddy-creator/scripts/preview.py

@@ -26,7 +26,7 @@ from urllib.request import HTTPRedirectHandler, ProxyHandler, Request, build_ope
 
 ROOT = Path(__file__).resolve().parent.parent
 RUNTIME_VERSION = "buddy-creator-" + json.loads((ROOT / "version.json").read_text(encoding="utf-8"))["version"]
-COMPATIBLE_RUNTIME_VERSIONS = {RUNTIME_VERSION, "buddy-creator-1.2.0", "buddy-creator-1.1.0", "buddy-creator-1.0.0", "python-trial-1"}
+COMPATIBLE_RUNTIME_VERSIONS = {RUNTIME_VERSION}
 STAGES = ("definition", "knowledge", "methods", "service")
 STAGE_LABELS = dict(zip(STAGES, ("定义", "知识", "方法", "服务")))
 LABELS = {"confirmed": "已确认", "accepted": "已采纳", "rejected": "未采纳",
@@ -177,7 +177,7 @@ def snapshot(workspace, state=None):
     cards, chapters = catalog["cards"], catalog["chapters"]
     stage = state["stage"]
     targets = state.get("targets", {})
-    artifacts = [_artifact_view(state, a) for a in state.get("artifacts", {}).values()]
+    artifacts = [_artifact_view(state, a) for a in state.get("artifacts", {}).values() if a['stage'] in STAGES]
     by_id = {a["id"]: a for a in artifacts}
     delivery = state.get("deliveries", {}).get(state.get("currentDeliveryId"), {})
     if delivery.get("resumeDeliveryId"):
@@ -304,11 +304,13 @@ def snapshot(workspace, state=None):
     except (OSError, ValueError, ImportError):
         if complete:
             completion_view = {"revision": state["revision"], "status": "failed", "message": "四册已确认，成果暂时无法读取。"}
-    if completion_view:
-        completion_view = {k: completion_view.get(k) for k in ("revision", "status", "message")}
+    import widgets
+    widget_design = widgets.projection(state, workspace)
+    if complete and widgets.enabled(state) and not widgets.ready(state):
+        current.update(phase='小挂件交互设计', title=widget_design['nextStep'], status='待确认')
     return {"buddyId": state["buddyId"], "revision": state["revision"], "stage": stage,
             "paused": bool(state.get("paused")), "activity": _activity(state, drafts),
-            "completion": completion_view, "current": current, "stages": stages,
+            "completion": completion_view, "widgetDesign": widget_design, "current": current, "stages": stages,
             "artifacts": artifacts, "sources": sources, "drafts": visible_drafts}
 
 
@@ -347,6 +349,11 @@ def _identity(endpoint, workspace_id, record):
             identity = json.loads(response.read(8192).decode("utf-8"))
     except (OSError, HTTPError, URLError, ValueError):
         return False
+    if (isinstance(identity, dict) and identity.get("workspaceId") == workspace_id
+            and record and identity.get("pid") == record.get("pid") and record.get("workspaceId") == workspace_id
+            and record.get("url") == _url(endpoint)
+            and identity.get("runtimeVersion") in {"buddy-creator-1.3.1", "buddy-creator-1.3.0", "buddy-creator-1.2.0", "buddy-creator-1.1.0", "buddy-creator-1.0.0", "python-trial-1"}):
+        _fail("PREVIEW_UPGRADE_REQUIRED", "当前作品的旧版预览服务仍在运行。由宿主核对该服务后重启，再 open 原工作区；保留固定地址、确认记录和一次性面板提醒。")
     if not isinstance(identity, dict) or identity.get("workspaceId") != workspace_id or identity.get("runtimeVersion") not in COMPATIBLE_RUNTIME_VERSIONS:
         _fail("PREVIEW_IDENTITY_MISMATCH", "端口上的服务不属于当前版本的搭子预览，未接管或停止它。")
     if not record or identity.get("pid") != record.get("pid") or record.get("workspaceId") != workspace_id or record.get("url") != _url(endpoint):
@@ -469,7 +476,8 @@ def serve(workspace):
             self.send_header("Cache-Control", "no-store")
             self.send_header("X-Content-Type-Options", "nosniff")
             self.send_header("Referrer-Policy", "no-referrer")
-            self.send_header("Content-Security-Policy", "default-src 'self'; script-src 'self'; connect-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none'")
+            frame = "'self'" if '/widget-assets/' in urlsplit(self.path).path else "'none'"
+            self.send_header("Content-Security-Policy", "default-src 'self'; script-src 'self'; connect-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors " + frame)
 
         def do_GET(self):
             expected_host = "127.0.0.1:" + str(self.server.server_port)
@@ -488,6 +496,38 @@ def serve(workspace):
                     self.json_reply(snapshot(workspace))
                 elif route == "api/events":
                     self.events()
+                elif route.startswith('widget-assets/'):
+                    import buddy_core
+                    import widgets
+                    import widget_render
+                    pieces = route.split('/')
+                    state = buddy_core.load(workspace)
+                    artifact = next((a for a in state['artifacts'].values() if a.get('kind') == 'widget-prototype' and len(pieces) == 3 and a['hash'] == pieces[1]), None)
+                    if not artifact or widgets.blockers(state, artifact):
+                        self.reply(404)
+                        return
+                    status = widget_render.asset_status(workspace, artifact, state)
+                    if not status['pass'] or pieces[2] not in {f['name'] for f in status.get('files', [])}:
+                        self.reply(404)
+                        return
+                    file = widget_render.directory(workspace, artifact) / pieces[2]
+                    self.reply(200, file.read_bytes(), {'.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml'}[file.suffix])
+                elif route.startswith('deliverables/'):
+                    import buddy_core
+                    import completion
+                    state = buddy_core.load(workspace)
+                    checked = completion.return_to_caller(workspace, state, {})
+                    parts = route.split('/', 2)
+                    if checked.get('directive') != 'creator_complete' or len(parts) != 3 or parts[1] != state['revision']:
+                        self.reply(404)
+                        return
+                    directory = workspace / 'deliverables' / state['revision']
+                    inventory = _read(directory / 'MANIFEST.json')
+                    if parts[2] not in {entry['path'] for entry in inventory['files']}:
+                        self.reply(404)
+                        return
+                    file = directory / parts[2]
+                    self.reply(200, file.read_bytes(), mimetypes.guess_type(str(file))[0] or 'text/plain; charset=utf-8')
                 else:
                     file = (assets / (route or "index.html")).resolve()
                     if assets not in file.parents or not file.is_file():

package/resources/buddy-creator/scripts/widget_render.py

@@ -0,0 +1,66 @@
+"""Versioned read-only prototypes; existing files retain their renderer contract."""
+import hashlib
+from pathlib import Path
+
+import buddy_core as core
+
+
+def files(artifact, item=None):
+    version = artifact['data'].get('rendererVersion')
+    core.require(version in (1, 2, 3, 4), 'WIDGET_RENDERER_VERSION', '不支持的原型模板版本。')
+    if version == 1:
+        from widget_render_v1 import files as render_files
+    elif version == 2:
+        from widget_render_v2 import files as render_files
+    elif version == 3:
+        from widget_render_v3 import files as render_files
+    else:
+        from widget_render_v4 import files as render_files
+    return render_files(artifact, item)
+
+
+def directory(workspace, artifact):
+    root = Path(workspace) / 'widget-assets'
+    path = root / artifact['hash']
+    core.require(re_full_hash(artifact['hash']) and not root.is_symlink() and not path.is_symlink(), 'WIDGET_ASSET_PATH', '小挂件资源目录无效。')
+    return path
+
+
+def re_full_hash(value):
+    return isinstance(value, str) and len(value) == 64 and all(c in '0123456789abcdef' for c in value)
+
+
+def render(workspace, state, artifact):
+    import widgets
+    item = next(i for i in widgets.items(state) if i['id'] == artifact['data']['widgetId'])
+    output = directory(workspace, artifact)
+    output.mkdir(parents=True, exist_ok=True)
+    from completion import _atomic
+    for name, raw in files(artifact, item).items():
+        core.require(not (output / name).is_symlink(), 'WIDGET_ASSET_PATH', '资源文件不能为符号链接。')
+        _atomic(output / name, raw)
+
+
+def asset_status(workspace, artifact, state=None):
+    if not artifact:
+        return {'pass': False, 'message': '原型尚未生成'}
+    try:
+        import widgets
+        state = state or core.load(workspace)
+        core.require(artifact['data'].get('rendererVersion') in (1, 2, 3, 4), 'WIDGET_RENDERER_VERSION', '原型模板版本已变化，需要重新生成并确认设计。')
+        item = next(i for i in widgets.items(state) if i['id'] == artifact['data']['widgetId'])
+        core.require(widgets.item_hash(item) == artifact['data']['itemHash'], 'WIDGET_ITEM_STALE', '清单项已更新，需要重绘原型。')
+        output = directory(workspace, artifact)
+        expected = files(artifact, item)
+        for name, raw in expected.items():
+            path = output / name
+            core.require(not path.is_symlink() and path.read_bytes() == raw, 'WIDGET_ASSET_CHANGED', '原型资源缺失或被修改，请用 widget_render 恢复当前版本。', {'file': name})
+        return {'pass': True, 'message': '尺寸、字体、只读控件及两视图三态资源检查通过；内容和阅读体验由开发者单独验收。',
+                'files': [{'name': name, 'sha256': hashlib.sha256(raw).hexdigest()} for name, raw in expected.items()]}
+    except (core.BuddyError, OSError, StopIteration, KeyError, ValueError) as error:
+        return {'pass': False, 'message': str(error) or '当前资源不可用，请重新生成原型。'}
+
+
+def require_assets(workspace, state, artifact):
+    status = asset_status(workspace, artifact, state)
+    core.require(status['pass'], 'WIDGET_ASSETS_REQUIRED', status['message'])