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.
This commit is contained in:
zizi
parent
9294101611
commit
8ffeba9120
@ -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<AIGameDesignDraftPayload>;
|
||||
};
|
||||
```
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
|
||||
@ -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 数据仍可恢复。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user