From 8ffeba9120d1eb69df16317a14f19f8f144eb3a8 Mon Sep 17 00:00:00 2001 From: zizi Date: Thu, 4 Jun 2026 07:03:10 +0800 Subject: [PATCH] docs(s2): prepare creator workbench handoff Clarify the S1 handoff, require a phase-aware S2 scope gate, and keep S2 P0 agent/generator boundaries explicit before implementation. --- .../2026-05-31-mvp-S2-creator-workbench.md | 113 ++++++++++++++++-- ...6-05-31-mvp-S2-creator-workbench-design.md | 42 +++++-- 2 files changed, 139 insertions(+), 16 deletions(-) diff --git a/docs/superpowers/plans/2026-05-31-mvp-S2-creator-workbench.md b/docs/superpowers/plans/2026-05-31-mvp-S2-creator-workbench.md index 1b540876..8cec630f 100644 --- a/docs/superpowers/plans/2026-05-31-mvp-S2-creator-workbench.md +++ b/docs/superpowers/plans/2026-05-31-mvp-S2-creator-workbench.md @@ -14,6 +14,16 @@ S2 does not make the game playable. It delivers conversation-driven game design generation, structured confirmation/editing, and `GameIR` output. Users must not be forced to manually configure a complete game from blank forms. +## S1 Handoff Constraints + +S1 final verification has passed and is ready to commit with the Task9 scope gate. S2 must build on these existing facts: + +- `MainCreationAgentSession` and `AgentTask` already exist as S1 schema anchors in `apps/api/prisma/schema.prisma`; S2 must extend and enable them, not create duplicate orphan concepts. +- S1 `check:s1-scope` intentionally rejects S2 terms such as `creation-agent/messages`, `AIGameDesignDraft`, `GameIR`, `GameIRArtifact`, and `compile-game-ir`. S2 implementation cannot start until scope checking is upgraded to a phase-aware gate. +- S1 safety boundaries remain mandatory in S2: AuditLog append-only, JobExecutionStore as the only Job runtime writer, worker no-Prisma, guarded state transition writes only through the state-transition service, and raw SQL write fail-closed scanning. +- S2 P0 enables only these internal subagents: `RequirementClarifierAgent`, `GameDraftAgent`, `GameConfigEditAgent`, and `AssetSuggestionAgent`. `PreviewIssueAgent` and `PublishAssistAgent` stay deferred until S4/S6/S8 evidence exists. +- S2 generation uses a generator port. The P0 acceptance path may use deterministic generation fixtures for repeatable tests; a real LLM adapter is optional and must not be represented as verified if it is not exercised. + ## Files - Create: `packages/shared-contracts/src/workflow.ts` @@ -32,6 +42,69 @@ S2 does not make the game playable. It delivers conversation-driven game design - Create tests: `apps/api/src/modules/game-ir/*.spec.ts` - Create tests: `apps/web/src/components/workbench/*.test.tsx` +## Task 0: Upgrade Scope Gate For S2 + +**Files:** +- Rename or create: `scripts/check-scope.mjs` +- Modify: `package.json` +- Keep or wrap: `scripts/check-s1-scope.mjs` + +- [ ] **Step 1: Add phase-aware scope tests** + +The new scope gate must support: + +```bash +node scripts/check-scope.mjs --phase S1 +node scripts/check-scope.mjs --phase S2 +``` + +Expected: + +```text +S1: existing S1 scope fixtures still pass/fail exactly as before. +S2: S2-approved files may contain creation-agent/messages, AIGameDesignDraft, DesignSection, GameIR, GameIRArtifact, compile-game-ir. +S2: S3-S8 terms still fail, including web-runtime, mini-game-conversion, MiniGameProject, MiniGameCodeConversion, ConversionReport, FeedItem, GameDailyStats, CreatorDailyStats, /events/batch. +S2: AuditLog update/delete, Job runtime writes outside JobExecutionStore, worker Prisma imports, guarded state writes outside state-transition, runtime guard setters, and raw SQL write bypasses still fail. +``` + +- [ ] **Step 2: Implement the phase gate** + +Refactor the S1 scanner rather than deleting it: + +```text +scripts/check-scope.mjs + parses --phase S1|S2 + runs shared S1 safety scanners for all phases + applies phase-specific business-scope allow/deny lists + +scripts/check-s1-scope.mjs + compatibility wrapper that calls check-scope with --phase S1 +``` + +`package.json` must expose: + +```json +{ + "scripts": { + "check:s1-scope": "node scripts/check-scope.mjs --phase S1", + "check:s2-scope": "node scripts/check-scope.mjs --phase S2" + } +} +``` + +- [ ] **Step 3: Verify scope gate** + +Run: + +```bash +node scripts/check-scope.mjs --phase S1 +node scripts/check-scope.mjs --phase S2 +pnpm check:s1-scope +pnpm check:s2-scope +``` + +Expected: all commands pass on the current S1 codebase before S2 business files are added. Dedicated temporary fixtures prove S2 approved terms are allowed only under S2-approved paths. + ## Task 1: Define AI Design, Section, And GameIR Contracts **Files:** @@ -61,7 +134,7 @@ export type TargetRuntime = Define `PromptRecord`, `AIGameDesignDraft`, and `DesignSection` shapes. `PromptRecord` must include raw prompt, normalized prompt, template hint, uploaded asset ids, moderation status, idempotency key, `sessionId`, and `agentTaskId`. `AIGameDesignDraft` must include `sessionId`, `agentTaskId`, generation task id, source prompt id, template version, status, sections, risks, and checksum. -Define `MainCreationAgentSession`, `AgentTask`, `RequirementBrief`, and `DesignSectionPatch` shapes. `AgentTask` must include task type, assigned subagent, input reference, output reference, status, timeout, error code, and audit id. +Define `RequirementBrief` and `DesignSectionPatch` shapes. Re-export S1-compatible `MainCreationAgentSession` and `AgentTask` DTO shapes from the shared contracts without adding extra properties to their S0 projection. `AgentTask` must include task type, assigned subagent, input reference, output reference, status, timeout, error code, and audit id. Define `SimulationGameIR` with map, facilities, economy, npc, objectives, resources, targetRuntimes. Define `LightGameIR` with the smallest playable loop needed to prove the path is not hard-coded to simulation management. @@ -95,7 +168,7 @@ export type GameIRArtifact = { Run: ```bash -pnpm --filter shared-contracts test -- workflow game-ir +pnpm --filter @huijing/shared-contracts test -- workflow game-ir ``` Expected: valid prompt/design draft/sections pass; missing facility/economy/NPC rules fail. @@ -108,13 +181,13 @@ Expected: valid prompt/design draft/sections pass; missing facility/economy/NPC - Create: `apps/api/src/modules/workbench/**` - Modify: `apps/api/prisma/schema.prisma` -- [ ] **Step 1: Add `MainCreationAgentSession`, `AgentTask`, `PromptRecord`, `AIGameDesignDraft`, `DesignSection`, and `DesignSectionPatch` models** +- [ ] **Step 1: Extend S1 agent anchors and add S2 design models** Model fields: ```text -MainCreationAgentSession: id, creatorId, projectId, versionId, status, contextSummary, createdAt, updatedAt -AgentTask: id, sessionId, taskType, subagentId, inputRef, outputRef, status, timeoutAt, errorCode, auditLogId, createdAt, updatedAt +MainCreationAgentSession: keep S1 fields id, creatorId, projectId, versionId, status, contextSummary, createdAt, updatedAt; add only S2 fields that do not break exact S0 DTO projection, such as lastPromptRecordId? or activeDraftId? if needed. +AgentTask: keep S1 fields id, sessionId, taskType, subagentId, inputRef, outputRef, status, timeoutAt, errorCode, auditLogId, createdAt, updatedAt; extend AgentTaskType enum for game_config_edit and asset_suggestion. PromptRecord: id, creatorId, projectId, versionId, sessionId, agentTaskId, rawPrompt, normalizedPrompt, templateHint, uploadedAssetIds, moderationStatus, idempotencyKey, createdAt AIGameDesignDraft: id, projectId, versionId, sessionId, agentTaskId, promptRecordId, generationTaskId, templateVersion, status, payloadJson, riskJson, checksum, createdAt, updatedAt DesignSection: id, projectId, versionId, sessionId, agentTaskId, draftId, sectionKey, payloadJson, validationStatus, userEdited, checksum, createdAt, updatedAt @@ -131,6 +204,8 @@ DesignSectionPatch: sectionId + resultChecksum Every `PromptRecord`, `AIGameDesignDraft`, `DesignSection`, and `DesignSectionPatch` must trace back to the `MainCreationAgentSession` and the internal `AgentTask` that produced or changed it. Records without this lineage are invalid. +The migration must preserve S1 S0 projection tests for `MainCreationAgentSession` and `AgentTask`. If S2 adds internal columns, S0 DTO serializers must continue returning exact schema-compatible objects with no additional properties. + - [ ] **Step 2: Add API tests** Cover: @@ -138,12 +213,16 @@ Cover: ```text creator sends message to MainCreationAgent intent router classifies requirement clarification / draft generation / config edit / preview issue +intent router classifies asset suggestion +preview issue and publish assist intents are deferred and return a stable not-available response without dispatching a subagent MainCreationAgent creates AgentTask for the selected subagent unknown intent asks one minimal clarification question and creates no generation task subagent failure marks AgentTask failed and preserves prior draft creator submits prompt and receives PromptRecord moderation rejected prompt does not create generation task AI design generation creates AIGameDesignDraft and six DesignSections +deterministic generator adapter produces schema-valid AIGameDesignDraft from prompt/template/assets +real LLM adapter is not required for P0 unless credentials and sandbox are explicitly configured creator can request a section edit through MainCreationAgent section edit creates DesignSectionPatch with baseChecksum/resultChecksum/actor/agentTaskId/conflictStatus checksum conflict returns 409 and does not update DesignSection @@ -165,12 +244,27 @@ GET /projects/:projectId/versions/:versionId/design-sections Only `POST /creation-agent/messages` is a public write entry. Prompt creation, draft generation, section generation, and section patch application are internal services triggered by `MainCreationAgent` tasks. If an internal handler exists for tests or workers, it must require `sessionId + agentTaskId + taskType + outputRef` and reject user-origin direct calls with 403 or malformed internal calls with 422. +The generator implementation must be behind a port: + +```ts +export type AIGameDesignGenerator = { + generateDraft(input: { + prompt: string; + templateHint: string | null; + uploadedAssetIds: readonly string[]; + generationTaskId: string; + }): Promise; +}; +``` + +The default S2 implementation should be deterministic and fixture-backed so tests are repeatable. A real LLM adapter can be added later without changing `MainCreationAgent` or persistence contracts. + - [ ] **Step 4: Run tests** Run: ```bash -pnpm --filter api test -- creation-agent ai-design workbench +pnpm --filter @huijing/api test -- creation-agent ai-design workbench ``` Expected: main-agent routing, subagent task, prompt, generation draft, section persistence, and permission tests pass. @@ -259,7 +353,7 @@ The endpoint must enforce project ownership and return the current validated Gam Run: ```bash -pnpm --filter api test -- game-ir +pnpm --filter @huijing/api test -- game-ir ``` Expected: valid simulation and light template fixtures pass; invalid fixtures fail with field paths. @@ -310,8 +404,8 @@ Kuaishou conversion target Run: ```bash -pnpm --filter web test -- workbench -pnpm --filter web typecheck +pnpm --filter @huijing/web test -- workbench +pnpm --filter @huijing/web typecheck ``` Expected: component tests and typecheck pass. @@ -354,6 +448,7 @@ Run: pnpm lint pnpm typecheck pnpm test +pnpm check:s2-scope node harness/scripts/validate-harness.mjs --contract GameIR --input apps/api/src/modules/game-ir/fixtures/compiled-simulation-game-ir-valid.json ``` diff --git a/docs/superpowers/specs/2026-05-31-mvp-S2-creator-workbench-design.md b/docs/superpowers/specs/2026-05-31-mvp-S2-creator-workbench-design.md index 6bdaeeb4..ba57c105 100644 --- a/docs/superpowers/specs/2026-05-31-mvp-S2-creator-workbench-design.md +++ b/docs/superpowers/specs/2026-05-31-mvp-S2-creator-workbench-design.md @@ -12,6 +12,16 @@ S2 下游于 S0/S1： 交付 PC 创作工作台底座：创作者通过自然语言对话描述游戏意图，AI 生成模拟经营游戏设计草稿，工作台把 AI 设计拆成可审核、可编辑的结构化 sections，确认后编译出平台中立 `GameIR` 草稿。S2 只保证对话生成、结构化确认和 IR 入口成立，不要求游戏已经可玩。 +## S1 Handoff / S1 交接事实 + +S1 final gate 已通过，S2 可以进入 spec/plan review，但不能直接实现。S2 必须继承以下 S1 事实： + +- S1 已有 `MainCreationAgentSession` 与 `AgentTask` schema anchor；S2 不是重新创建同名孤儿模型，而是在现有 anchor 上启用对话和子代理编排，并补充 `PromptRecord`、`AIGameDesignDraft`、`DesignSection`、`DesignSectionPatch`、`GameIRArtifact` 等 S2 业务模型。 +- S1 的 `scripts/check-s1-scope.mjs` 明确拒绝 `creation-agent/messages`、`AIGameDesignDraft`、`GameIR`、`GameIRArtifact`、`compile-game-ir` 等 S2 合法术语。进入 S2 实现前，必须先把 scope gate 升级为阶段感知门禁，例如 `check:scope --phase S2` 或 `check:s2-scope`，保留 S1 安全边界，同时允许 S2 批准的路径、模型和合同。 +- `JobExecutionStore` 仍是 Job runtime state 唯一写入口；S2 的 AI generation / compile job 必须通过 S1 job boundary，不允许子代理或 worker 直接写 Job 状态。 +- `AuditLog` 仍 append-only；S2 的 prompt、agent task、section patch、compile 行为只能追加审计事实。 +- `GameVersion`、`ReviewRecord`、`LifecycleEvent` guarded state 仍只能走 state-transition boundary；S2 不得直接推进 publish/review 状态。 + ## Scope / 范围 P0 做： @@ -23,6 +33,10 @@ P0 做： - 可选择模板、风格、目标平台和上传素材作为约束，但这些约束应由主 Agent 解释为自然语言建议，不要求用户理解底层字段。 - 子代理生成 `AIGameDesignDraft`，包含玩法、地图、设施、经济、NPC、目标、封面说明和标签建议。 - 生成结果必须可追溯到 `PromptRecord`、模板版本、素材引用和生成任务 id。 +- 受控生成 adapter： + - P0 先实现可替换的 generator port 和 deterministic generator，用真实 fixture 证明主链路、schema、审计、幂等和失败处理。 + - 真实 LLM adapter 只能作为后续可替换实现接入；没有真实模型凭证或稳定沙箱时，不得阻塞 S2 验收，也不得把 mock 结果标记成真实 AI 能力。 + - 无论 deterministic 还是真实 LLM adapter，输出都必须通过 schema validation，并落入受控合同。 - AI 设计草稿结构化 review sections： 1. 游戏主题与目标。 2. 地图/地块网格。 @@ -80,14 +94,14 @@ flowchart TD Intent --> Draft[GameDraftAgent] Intent --> Edit[GameConfigEditAgent] Intent --> Asset[AssetSuggestionAgent] - Intent --> Preview[PreviewIssueAgent] - Intent --> Publish[PublishAssistAgent] + Intent -. deferred until S4 .-> Preview[PreviewIssueAgent] + Intent -. deferred until S6/S8 .-> Publish[PublishAssistAgent] Req --> Main Draft --> Main Edit --> Main Asset --> Main - Preview --> Main - Publish --> Main + Preview -. planned only .-> Main + Publish -. planned only .-> Main Main --> UI[Structured Review/Edit Workbench] ``` @@ -100,8 +114,8 @@ P0 子代理建议： | `GameDraftAgent` | 基于需求生成游戏设计草稿 | `AIGameDesignDraft` | design draft schema、模板能力边界 | | `GameConfigEditAgent` | 根据用户修改意图更新 sections 或 IR 候选 | `DesignSectionPatch` | section schema、差异审计、不可绕过用户确认 | | `AssetSuggestionAgent` | 根据主题建议素材、封面和标签 | asset suggestions | 素材权限、版权和安全扫描 | -| `PreviewIssueAgent` | 解释预览失败、runtime smoke 失败和可修复项 | diagnostic summary、上游修复建议 | 只能建议修上游设计/配置/logic，不直接改平台代码 | -| `PublishAssistAgent` | 解释审核、导出、转换状态和风险 | publish checklist、risk summary | 不宣称渠道上架或真机通过 | + +P0 只启用前四个子代理：`RequirementClarifierAgent`、`GameDraftAgent`、`GameConfigEditAgent`、`AssetSuggestionAgent`。`PreviewIssueAgent` 需要 S4 runtime smoke evidence，`PublishAssistAgent` 需要 S6/S8 审核发布链路；S2 只能保留其计划位，不实现业务入口。 扩展规则： @@ -110,6 +124,8 @@ P0 子代理建议： - 子代理输出必须回到 `DesignSection`、`GameIR`、`GameConfig`、`GameLogicModule` 或诊断报告等受控合同。 - 主 Agent 必须把复杂字段转成用户能理解的选择和确认，降低用户心智负担。 - 用户可以用自然语言继续修改，例如“顾客多一点”“地图小一点”“改成猫咖主题”，由主 Agent 分派给对应子代理生成 patch。 +- 每一次子代理分派都必须创建或更新 `AgentTask`，并记录 `taskType/subagentId/inputRef/outputRef/status/errorCode/auditLogId`。没有 `AgentTask` lineage 的草稿、section、patch、GameIR 都无效。 +- 子代理可以调用生成 adapter，但不能直接调用 DB mutation；持久化只能由对应 service 在权限、幂等、schema、审计检查后完成。 ## Core Contracts / 核心合同 @@ -130,6 +146,17 @@ P0 子代理建议： | `GameIR` | S2 编译器 | S3/S4/S5 | S0 schema、平台中立 | simulation + light template IR fixtures | | `GameIRArtifact` / `GameIRDraft` | 编译成功后持久化 | S3/S4/S5 | `versionId -> GameIR` 唯一关联、checksum、schemaVersion、S0 gate 通过 | compile/read tests | +### Scope Gate Contract / 阶段门禁合同 + +S2 必须新增或重构 scope scanner，形成阶段化门禁： + +| Phase | Allowed | Still forbidden | +| --- | --- | --- | +| S1 | 只允许 S1 foundation anchors | S2-S8 business implementation | +| S2 | 允许 `creation-agent/messages`、`AIGameDesignDraft`、`DesignSection`、`GameIR`、`GameIRArtifact`、`compile-game-ir` 等 S2 批准项 | Web runtime、mini-game conversion、publish/feed/telemetry/deploy implementation | + +S2 scope gate 必须继续继承 S1 的安全扫描：AuditLog append-only、Job runtime 单写入口、guarded state transition、worker no-Prisma、raw SQL write fail-closed。不能为了允许 S2 术语而关闭 S1 安全边界。 + ## UI Requirements / UI 要求 - PC 优先，移动端只需可查看草稿，不要求完整编辑。 @@ -143,8 +170,9 @@ P0 子代理建议： ## Acceptance Criteria / 验收标准 - creator 能通过自然语言创建项目并得到 AI 生成的模拟经营设计草稿。 -- `MainCreationAgent` 能识别生成、需求确认、配置修改、预览问题解释等 P0 意图，并派发到对应子代理。 +- `MainCreationAgent` 能识别生成、需求确认、配置修改和素材建议等 P0 意图，并派发到对应子代理；预览问题解释和发布辅助在 S2 只保留计划位，不作为 P0 验收。 - 子代理产物必须回到受控合同，且有 `AgentTask` 审计记录。 +- S2 scope gate 能允许 S2 合法 implementation，同时继续阻断 S3-S8 泄漏和 S1 安全边界绕过。 - AI 生成草稿能拆成 6 个结构化 review sections。 - creator 能确认或微调结构化 sections，不需要从零手动配置所有游戏数据。 - 刷新页面后 PromptRecord、AI 草稿和 sections 数据仍可恢复。