重构世界模拟器为模块化配方架构，完善创作编排、会话运行时与 Web UI，并清理过时技能。
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
@@ -1,150 +1,301 @@
|
||||
# 整体架构
|
||||
# 本地多 Agent 文本创作系统架构
|
||||
|
||||
## 1. 方向
|
||||
## 1. 文档定位
|
||||
|
||||
**标签驱动黑板** + **agent tool loop** + **5 相位阶段机** + **skill 能力库**。
|
||||
本文档描述**系统级运行内核**：模块边界、创作定义与运行实例如何分离、总管 / Worker / Skill / 上下文如何协作、数据如何持久化，以及外部项目按层借鉴的原则。
|
||||
|
||||
```text
|
||||
Skill 包（orchestrator manifest + workers/*/SKILL.md） 静态能力定义
|
||||
Session + 黑板 tag 一次运行的实参
|
||||
Book 跨 Session 的项目与资产
|
||||
|
||||
Agent（总管） running 相位内 tool loop，调度 invoke 哪个 skill
|
||||
Runtime 拼接上下文、校验 tool、写黑板、驱动阶段机边界
|
||||
阶段机 谁可动、何时等用户、产物生命周期——不是流水线剧本
|
||||
```
|
||||
|
||||
核心文档：
|
||||
|
||||
```text
|
||||
docs/tag-blackboard.md 黑板、标签、分工
|
||||
docs/context-assembly.md ★ 上下文拼接（上半固定、下半动态）
|
||||
docs/tool-contracts.md 总管 / worker tool
|
||||
docs/runtime-state-machine.md 5 相位、tool 边界
|
||||
docs/book-storage.md 长期存储（过程 / 资产 / 游玩）
|
||||
docs/skill-design-guide.md 新 skill 包设计方法
|
||||
docs/implementation-guide.md 代码文件职责
|
||||
```
|
||||
本文档**不**设计具体剧本 Skill 的提示词、步骤或字段。剧本与创作方法见独立文档（如 `design-orchestrator-guide.md`）；Skill 包格式见 `skill-format.md` 系列。
|
||||
|
||||
---
|
||||
|
||||
## 2. 术语
|
||||
## 2. 产品目标
|
||||
|
||||
本地运行的多 Agent 文本生成平台，兼容多种创作模式（角色扮演、长短篇小说、仿写扩写、思想实验、信息隔离模拟、世界观/角色卡/模板创作、动态表与长期状态、存档分支等）。
|
||||
|
||||
这些模式共享同一运行内核，区别来自：
|
||||
|
||||
- 装载哪些 Skill / 能力包
|
||||
- 实例规格（Worker 声明）如何配置
|
||||
- 上下文如何按契约编译
|
||||
- 对状态读写实施什么权限
|
||||
|
||||
不为每一种创作模式各实现一套固定工作流。
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心架构原则
|
||||
|
||||
### 3.1 创作定义与运行实例分离
|
||||
|
||||
| 层 | 当前实现对应 | 含义 |
|
||||
|----|--------------|------|
|
||||
| **创作定义 / 规格** | accept 后的 `设计.worker集`、静态设定 tag；可存为 `instance` / `opening` 快照 | 可复用的「函数声明」：Worker、表、常驻上下文、权限与能力边界 |
|
||||
| **运行实例** | Book + Session + 黑板 + `run` 快照 | 一次具体创作/游玩过程：对话、变量、轮次、中间产物 |
|
||||
|
||||
同一规格可多次开档；实例应**钉住**某次规格截面。规格更新后，已有实例不自动跟随；需显式加载/迁移到新截面。
|
||||
|
||||
语义上：`instance` 快照 ≈ 已发布的规格版本；`run` 快照 ≈ 运行过程存档。正式 `DefinitionVersion` 发布与迁移协议在现有快照之上增量补齐，不另起一套推倒重写。
|
||||
|
||||
### 3.2 总管只负责任务调配
|
||||
|
||||
总管 Agent（Main Agent）负责：判断目标是否完成、决定下一项任务、选择 Worker、必要时询问用户或结束。
|
||||
|
||||
总管**不**负责：直接创作最终正文、临场拼接完整上下文、绕过权限读私有信息、直接改正式状态、同时兼创作与评测、把隐藏推理写入长期状态。
|
||||
|
||||
任务所需信息由总管**声明意图**（如 invoke 哪个 worker）；真正发给 Worker 的上下文由 Runtime 的上下文编译器按 Skill / 声明契约生成。
|
||||
|
||||
### 3.3 Agent 决策与程序控制分离
|
||||
|
||||
| Agent（非确定） | Runtime（确定） |
|
||||
|-----------------|-----------------|
|
||||
| 下一步做什么 | 权限与声明校验 |
|
||||
| 调用哪个能力 | 上下文装载与 Token 裁剪 |
|
||||
| 是否返工 / 问用户 | 状态提交、表 `rev` 合并 |
|
||||
| | 相位边界、burst、失败处理 |
|
||||
|
||||
不能依赖提示词保证权限与信息隔离；访问限制在 Tool 与 Context Compiler 层执行。
|
||||
|
||||
### 3.4 动态调度，不用固定创作 DAG
|
||||
|
||||
「下一步 invoke 哪个 skill」由 agent tool loop 决定。
|
||||
|
||||
**5 相位阶段机**（`idle` / `running` / `waiting_user` / `done` / `error`）是并发与权限模型——谁可动、何时等用户、产物何时算事实——**不是**流水线剧本。详见 `runtime-state-machine.md`、`tool-contracts.md`。
|
||||
|
||||
确定性后台流程（导入导出、索引、迁移、批量评测）可用固定步骤；整场 AIRP / 小说创作流程不固化为完整 DAG。
|
||||
|
||||
---
|
||||
|
||||
## 4. 总体架构
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ Web / Electron Frontend │
|
||||
│ 创作 / 游玩 / 存档 / 检查器 / 调试 │
|
||||
└─────────────────────┬───────────────────────┘
|
||||
│ HTTP（+ 流式事件）
|
||||
┌─────────────────────▼───────────────────────┐
|
||||
│ Application API │
|
||||
│ Book、Session、快照、资源、模型配置 │
|
||||
└─────────────────────┬───────────────────────┘
|
||||
│
|
||||
┌─────────────────────▼───────────────────────┐
|
||||
│ Agent Runtime │
|
||||
│ Main Agent（tool loop） │
|
||||
│ Phase Machine + Phase Runtime │
|
||||
│ Skill Registry / Worker 声明校验 │
|
||||
│ Context Compiler（assembleWorkerContext） │
|
||||
│ Commit：黑板写入、表 rev、acceptance │
|
||||
└─────────────────────┬───────────────────────┘
|
||||
│
|
||||
┌─────────────────────▼───────────────────────┐
|
||||
│ Domain / Storage │
|
||||
│ Book · Session · Blackboard · Snapshots │
|
||||
│ Artifacts · RuntimeEvent history │
|
||||
│ 文件资源（books/…）；向量检索可插拔 │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
合成边界：
|
||||
|
||||
> Book/规格描述可以运行什么，Session/快照保存实际发生了什么，相位机决定谁可动，总管决定下一步 invoke 谁，Context Compiler 决定 Worker 看见什么，Runtime 决定哪些修改正式生效。剧本 Skill 是可装载能力，不是系统固定流水线。
|
||||
|
||||
---
|
||||
|
||||
## 5. 系统核心模块
|
||||
|
||||
### 5.1 规格与 Book（Definition 侧）
|
||||
|
||||
- Book：长期项目容器（过程、资产、游玩状态）
|
||||
- `设计.worker集` accept 后 → 本实例 Worker 声明
|
||||
- `instance` / `opening` 快照：规格与可选开局截面
|
||||
- 导入导出、复制、从截面新开 play 线
|
||||
|
||||
细节：`book-storage.md`、`run-snapshot.md`。
|
||||
|
||||
### 5.2 Session 与 Instance Manager（运行侧）
|
||||
|
||||
- 按规格创建 / 加载 Session
|
||||
- 自动续作 `session.json` 与手动 `run-snapshots/`
|
||||
- 消息 swipe / branch checkpoint
|
||||
- 从 earlier 快照恢复后重 roll
|
||||
|
||||
### 5.3 Main Agent（Supervisor）
|
||||
|
||||
接收压缩后的任务视图（目标、相位、可调用能力、最近产物摘要等），经 tool loop 输出调度意图；Runtime 校验后执行。
|
||||
|
||||
### 5.4 Phase Runtime（Dynamic Scheduler 的具体形态）
|
||||
|
||||
执行总管决定并维护相位边界：
|
||||
|
||||
1. 校验 Worker id ∈ 声明
|
||||
2. 编译上下文
|
||||
3. 短生命周期执行 Worker
|
||||
4. 收集写入请求 → 校验 / 合并 / 提交
|
||||
5. 按 acceptance 可能进入 `waiting_user`
|
||||
6. 预算：`maxBurst`；后续补齐嵌套深度、重复任务检测、Token/调用预算
|
||||
|
||||
实现：`src/runtime/phase-machine.ts`、`phase-runtime.ts`。
|
||||
|
||||
### 5.5 Worker
|
||||
|
||||
按任务实例化的短生命周期调用。保留的是事件、产物与状态修改，不是 Agent 对象。
|
||||
|
||||
### 5.6 Skill Registry
|
||||
|
||||
架构层两种能力层级：
|
||||
|
||||
- **包 / Orchestrator manifest**：能力发现、验收与进 play 门槛
|
||||
- **Worker 契约**：声明驱动的输入输出、上下文段、工具边界
|
||||
|
||||
注册、加载、版本与磁盘格式见 Skill 系列文档；**具体剧本步骤不在本文**。
|
||||
|
||||
### 5.7 Context Compiler
|
||||
|
||||
确定性模块：按任务、Worker 权限与实例状态构建 Context View。
|
||||
|
||||
当前实现：`inputTags` / `contextSegments` + `assembleWorkerContext()`（`context-assembly.md`）。
|
||||
|
||||
演进契约：
|
||||
|
||||
- **Context Trace**：记录装载了什么、来源、权限依据、因预算/权限排除了什么
|
||||
- 逻辑分区语义（public / narrative / characters / tables / artifacts / runtime）可映射到 tag 与可见范围；实现仍以 tag 黑板为主
|
||||
|
||||
### 5.8 Blackboard
|
||||
|
||||
带类型与来源的运行状态（tag 条目），不是全体 Agent 共享的大字符串。表字段使用 `value + rev + source`；正式写入经 Runtime。见 `tag-blackboard.md`。
|
||||
|
||||
### 5.9 Artifact 与验收
|
||||
|
||||
较长或需反复编辑的内容以黑板 tag / 产物记录保存；`drafted → under_review → accepted|rejected|revision_requested`；accepted 前不得当下游事实。
|
||||
|
||||
### 5.10 Commit and Validation
|
||||
|
||||
Worker 不直接改「当前事实」。路径：输出 → 声明/schema 校验 → 权限与 rev 合并 → 提交事件 → 更新黑板。结构化状态用受控写入；正文类产物仍记录来源与版本。
|
||||
|
||||
---
|
||||
|
||||
## 6. 数据持久化
|
||||
|
||||
当前以**状态快照为主**，会话内保留 `RuntimeEvent` history；完整领域事件溯源（投影 + 事件日志 + 周期快照）按分支/迁移/审计痛点再加深。
|
||||
|
||||
| 需求 | 机制 |
|
||||
|------|------|
|
||||
| 续作 | `session.json` |
|
||||
| 规格截面 | `instance` / `opening` 快照 |
|
||||
| 游玩存档 / 重 roll | `run` 快照；load = 恢复到该档 |
|
||||
| 同开局多线 | 保留 opening/instance 层，清空或分支 run 层 |
|
||||
| 调试回放 | `RuntimeSession.history` |
|
||||
|
||||
分支不要求复制整库；记录父档 / 基准快照即可。
|
||||
|
||||
---
|
||||
|
||||
## 7. 信息隔离
|
||||
|
||||
隔离由 Runtime 强制：Worker 只看到契约允许的 tag / 段。多角色模拟时，角色 Worker 不得看到他角私有记忆、未公开事件、总管隐藏调度信息。
|
||||
|
||||
Context Trace 是排查泄漏的主工具（契约已定，实现渐进）。
|
||||
|
||||
---
|
||||
|
||||
## 8. 技术栈（现状与边界）
|
||||
|
||||
| 层 | 现状 | 边界 |
|
||||
|----|------|------|
|
||||
| 语言 | TypeScript / Node.js | — |
|
||||
| Agent Runtime | 自研（main-agent、phase-runtime、llm） | 领域对象不绑定外部 Agent 框架内部类型；Mastra 等仅可作按层参考或远期适配 |
|
||||
| 前端 | `web/` + Electron | 不强制 Next.js / assistant-ui；可借鉴交互模式 |
|
||||
| 存储 | 文件系统 Book JSON | SQLite/Drizzle 非近端前提 |
|
||||
| Skill | `skills/` + registry | 包内剧本与系统内核分离 |
|
||||
|
||||
外部仓库按模块借鉴，见 `references.md`；许可证见仓库根 `THIRD_PARTY_NOTICES.md`。
|
||||
|
||||
---
|
||||
|
||||
## 9. 术语对照
|
||||
|
||||
| 规划用语（抽象） | 本仓库用语（实现） |
|
||||
|------------------|-------------------|
|
||||
| CreationDefinition / DefinitionVersion | `设计.worker集` 截面；`instance` / `opening` 快照 |
|
||||
| RunInstance | Book + Session + 黑板 + `run` 快照 |
|
||||
| 导演 Skill / 能力包 | `orchestrator.md` 包（UI 可选；registry 一项） |
|
||||
| 剧本层（动态） | 对话谈成的 Worker 集 + play 期 tool loop 调度（非死板选单） |
|
||||
| Supervisor | Main Agent（tool loop） |
|
||||
| Dynamic Scheduler | Phase Machine + Phase Runtime |
|
||||
| Worker Factory | `run_worker` → 声明校验 → executor |
|
||||
| Context Compiler | `assembleWorkerContext` / contextSegments |
|
||||
| Blackboard | tag 黑板（`BlackboardItem`） |
|
||||
| Commit Layer | 写入校验、表 rev 合并、acceptance |
|
||||
| Skill Registry | `skills/` loader + orchestrator manifest |
|
||||
|
||||
用户可见中文口径（禁止裸露内部 id）见 `ui-glossary.md`。
|
||||
|
||||
| 词 | 含义 |
|
||||
|----|------|
|
||||
| **skill** | `SKILL.md` 定义的能力（设计期能力库中的一条） |
|
||||
| **worker** | 某 skill 被 invoke 的一次执行 |
|
||||
| **stage** | 业务阶段：`design`（实例化）→ `play`（运行）→ `done` |
|
||||
| **phase** | 运行相位：`idle` \| `running` \| `waiting_user` \| `done` \| `error` |
|
||||
|
||||
不使用 **step** 指代设计步骤编号，避免与管道混淆。
|
||||
| **Worker 声明** | accept 后的 `设计.worker集` |
|
||||
| **worker** | 一次 `run_worker` invoke |
|
||||
| **stage** | `design` → `play` → `done`（创作 → 游玩 → 已完成） |
|
||||
| **phase** | `idle` \| `running` \| `waiting_user` \| `done` \| `error` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Agent tool loop
|
||||
## 10. 文档地图
|
||||
|
||||
```text
|
||||
用户硬事件（输入 / 确认 / 验收）
|
||||
→ phase = running，toolLoopBurst 计数归零
|
||||
→ while running && burst < N:
|
||||
LLM(messages, tools)
|
||||
→ 循环 tool（read_blackboard …）→ 结果 append 到 messages
|
||||
→ 边界 tool（run_worker / ask_user / finish）→ 退出 burst
|
||||
→ 若需用户 → waiting_user
|
||||
```
|
||||
|
||||
- **burst 上限 N**：两次用户操作之间的最大推理轮数，非 Session 终身额度。
|
||||
- **循环 tool**：不改 phase，只追加 agent 对话。
|
||||
- **边界 tool**：触发阶段机转移（等用户、跑 worker、结束）。
|
||||
|
||||
代码：`src/main-agent/tool-loop.ts`、`src/runtime/phase-runtime.ts`。
|
||||
|
||||
目标态：worker 执行也用 tool loop（`submit` / `ask_user`），上下文仍由 Runtime 拼接，见 `docs/tool-contracts.md`。
|
||||
| 层级 | 文档 |
|
||||
|------|------|
|
||||
| **系统架构（本文）** | `architecture.md` |
|
||||
| 运行内核 | `runtime-state-machine.md`、`tool-contracts.md`、`context-assembly.md`、`tag-blackboard.md` |
|
||||
| 持久化 | `book-storage.md`、`run-snapshot.md` |
|
||||
| UI | `ui-design.md`、`ui-glossary.md` |
|
||||
| 实现顺序 | `implementation-guide.md` |
|
||||
| **产品体验路线** | **`px-roadmap.md`**（PX0–PX5 交付与 DoD） |
|
||||
| **日常场景 → P0** | **`daily-use-p0.md`**（场景、功能表、P0 工作包） |
|
||||
| 外部参考 | `references.md` |
|
||||
| **剧本 / 创作方法（非系统架构）** | `design-orchestrator-guide.md`、`creation-playbook.md` |
|
||||
| **Skill 包格式（非系统架构）** | `skill-format.md`、`orchestrator-skill-format.md`、`worker-skill-format.md`、`skill-design-guide.md`、`preset-format.md` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 阶段机做什么
|
||||
## 11. 在现有内核上补齐（路线）
|
||||
|
||||
阶段机 **不是** 编排表执行器，而是：
|
||||
已具备：相位机、Agent tool loop、Skill loader、design-intake、Worker 声明、上下文拼装、表 rev、Web UI、快照 API。
|
||||
|
||||
```text
|
||||
1. Actor 门禁 此刻用户 / agent / worker 谁在场
|
||||
2. Tool 边界 当前态允许哪些 tool
|
||||
3. 事实生命周期 draft → accepted；用户才能 accept
|
||||
4. 等待原因 waitingReason 细分等什么
|
||||
```
|
||||
1. **PX0**：导演选择 UI；AIRP + 长文/爽文主路径；**存档/续作硬稳定**；剧本层保持动态
|
||||
2. **PX1–PX2**：创作/游玩体验（可抄 UI）；副作用与多 run 线
|
||||
3. **PX3**：Context Trace、调度预算、规格钉版本、E2E
|
||||
4. **PX4–PX5**：长文加深；隔离模拟 + 调试（新方法边界可用新导演包）
|
||||
5. SQLite / 框架适配仅当痛点单开，不插入 PX0 关键路径
|
||||
|
||||
业务「先跑哪个 skill」由 **agent 在 tool loop 里决定**，不由 orchestrator 逐步剧本写死。
|
||||
权威表：[`px-roadmap.md`](./px-roadmap.md)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 实例化：skill 能力库
|
||||
## 12. 主要技术风险
|
||||
|
||||
实例化 = agent 在 `design` stage 按需 invoke **instantiate skill**（原「设计步骤」），不是固定 1→14 管道。
|
||||
|
||||
```text
|
||||
交互范式 skill → 产出 设计.run_skill清单（run 阶段需要哪些 skill）
|
||||
每个 run skill 倒推 → 缺什么 instantiate skill → agent invoke
|
||||
declare_instance_ready → 进入 play stage
|
||||
```
|
||||
|
||||
orchestrator.md = **manifest**（有哪些 skill、约束、验收策略），不是逐步思维链。
|
||||
| 风险 | 解决边界 |
|
||||
|------|----------|
|
||||
| 上下文污染 | 全部经 Context Compiler；补 Trace |
|
||||
| 自然语言误改状态 | 结构化状态只走受校验写入 / Patch |
|
||||
| 调度死循环 | burst、后续嵌套/重复/预算限制 |
|
||||
| 规格更新污染旧档 | 实例钉规格截面；显式迁移 |
|
||||
| 框架耦合 | 领域与持久化不保存外部 Agent 框架内部对象 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 上下文拼接
|
||||
|
||||
**上半固定、下半动态**。规则在 skill 定义 + 实例 contextProfile；Runtime 执行。
|
||||
见 `docs/context-assembly.md`。
|
||||
|
||||
---
|
||||
|
||||
## 7. 模块
|
||||
|
||||
```text
|
||||
phase-machine.ts 纯函数：event → phase（边界规则）
|
||||
phase-runtime.ts Session IO、tool loop 驱动、worker 执行
|
||||
main-agent/ tool loop、tool 定义
|
||||
worker/executor.ts assembleWorkerContext、run skill
|
||||
blackboard.ts tag 池
|
||||
skills/loader.ts 解析 orchestrator + SKILL.md
|
||||
book/ Book、快照、持久化
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 数据流（目标态）
|
||||
|
||||
```text
|
||||
选 orchestrator 包
|
||||
→ design：agent burst → invoke instantiate skills → 设计.* tag
|
||||
→ declare ready → play
|
||||
→ play：用户输入 → agent burst → invoke run skills → 运行.* tag
|
||||
→ 过程/资产/游玩 归档 Book（见 book-storage.md）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 边界
|
||||
|
||||
```text
|
||||
Agent 调度 skill；read_blackboard；不传 inputTags；不写黑板（边界 tool 除外）
|
||||
Runtime 拼接上下文；校验 tool；写黑板；执行 worker
|
||||
Worker LLM 在拼接后的 prompt 内产出；submit 写 declared outputTags
|
||||
用户 approve、accept、输入
|
||||
阶段机 只响应 event，不调 LLM
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 实现进度（摘要）
|
||||
## 13. 实现进度（摘要）
|
||||
|
||||
```text
|
||||
✅ phase-machine、phase-runtime、skills loader
|
||||
✅ 总管 tool loop（read_blackboard、run_worker、…）
|
||||
⬜ toolLoopBurst 按用户事件归零
|
||||
⬜ assembleWorkerContext（contextSegments）
|
||||
⬜ worker tool loop
|
||||
⬜ Book：designTrace / CardAsset / PlayBook
|
||||
⬜ orchestrator 从编排表迁为 manifest
|
||||
✅ design-intake + Worker 声明校验
|
||||
✅ 声明驱动 worker 执行 + acceptance
|
||||
✅ 表字段格 rev 合并
|
||||
✅ Book session / run-snapshots / message branch
|
||||
✅ 导演选择 UI（新建作品）；instance/run 存档人话 kind
|
||||
✅ 长文模板 outline / chapter-writer；引导覆盖爽文/分段
|
||||
✅ 失败/revision/error 出口；黑板用户手改 API
|
||||
⬜ Context Trace
|
||||
⬜ 规格版本发布与迁移协议
|
||||
⬜ 调度嵌套 / 重复任务 / Token 预算补齐
|
||||
⬜ 边沿副作用完整调度器
|
||||
⬜ 标准 fixture E2E（双线黄金路径自动化）
|
||||
```
|
||||
|
||||
435
docs/briefs/capability-authoring-brief.md
Normal file
435
docs/briefs/capability-authoring-brief.md
Normal file
@@ -0,0 +1,435 @@
|
||||
# 能力撰写交接简报（泛用）
|
||||
|
||||
> **用途**：把本文**整份**交给另一 AI / 作者，用于撰写任意【能力】的 `modules/{id}/prompt.md`。
|
||||
> **本文是自洽规范**：不依赖读者已熟悉本仓库。
|
||||
> **不要**让撰写方改程序代码；**不要**只写某一能力的特例而不遵守通用格式。
|
||||
|
||||
范例（深度与结构对齐）：`skills/dialogue/world-simulator/modules/aesthetics-interaction/prompt.md`
|
||||
能力池清单（选题用）：`docs/world-simulator-modules.md`
|
||||
术语权威：`docs/ui-glossary.md` §0
|
||||
|
||||
---
|
||||
|
||||
# 第一部分：项目是什么
|
||||
|
||||
## 1.1 一句话
|
||||
|
||||
**writing-agent** 是本地运行的多 Agent **文本创作 / 游玩**系统：用户选一个【导演】，在【创作】期谈成【剧本】，再在【游玩】期让【演员】按剧本上场，产出可读文本（角色扮演、长文/爽文、扩写、思想实验等共用同一内核）。
|
||||
|
||||
## 1.2 要解决什么问题
|
||||
|
||||
| 要 | 不要 |
|
||||
|----|------|
|
||||
| 用程序控制「每一步注入什么上下文」 | 把整本长说明书一次塞进 LLM |
|
||||
| 用 Agent 按用户体验**编排**用哪些能力、什么顺序 | 死板选单 DAG，或全程让 LLM 自由发明工序 |
|
||||
| 产物可解析、可渲染、对人可读 | 产物里堆满英文变量名让用户难受 |
|
||||
| 规格（能复用的声明）与一局游玩过程分离 | 每种玩法重写一套运行时 |
|
||||
|
||||
## 1.3 两段生命周期
|
||||
|
||||
```text
|
||||
【创作 design】选导演 → 编排剧本（步骤=能力）→ 逐步执行能力 → 谈成可运行规格
|
||||
│
|
||||
▼ 用户手动进入
|
||||
【游玩 play】用户输入 → 演员按规格上场 → 可见终稿；可存档 / 重 roll
|
||||
```
|
||||
|
||||
- **创作**：谈清「这局要什么体验、用哪些能力钉成什么产物」。
|
||||
- **游玩**：按已验收规格跑；用户新输入通常视为认可上一轮展示（否则重 roll）。
|
||||
|
||||
## 1.4 运行时怎么分工（撰写能力时必须懂）
|
||||
|
||||
| 角色 | 做什么 | 不做什么 |
|
||||
|------|--------|----------|
|
||||
| **导演（Agent）** | 决定下一步调哪个演员；编排剧本步骤 | 不直接写小说正文；不私自改相位 |
|
||||
| **程序（Runtime）** | 校验权限；按契约拼上下文；切步；发 opening；验收门控 | 不替用户发明体验 |
|
||||
| **能力（modules）** | 某一步「怎么和用户谈、产出什么形状」的方法正文 | 不是整场流水线 |
|
||||
| **演员（Worker）** | 一次 LLM 执行（创作期跑能力，或游玩期跑声明内 ref） | 不决定全局调度 |
|
||||
|
||||
关键路径：
|
||||
|
||||
```text
|
||||
用户选【导演】（如世界模拟器）
|
||||
→ design-flow：从【能力】排出**近期**步骤，写出 设计.创作流程
|
||||
（可变增量 DAG：每步 id + 固定中文名 + depends_on；status=open|closed）
|
||||
→ 用户验收近期流程
|
||||
→ 反复 design-step：程序注入「当前能力」的 prompt 切片 + 依赖产物
|
||||
→ 步骤做完仍 open → 再 design-flow（可追加同能力多次，如生成规则 / 具体实例）
|
||||
→ closed 后收成可进游玩的规格，如 设计.worker集
|
||||
→ 用户手动进游玩
|
||||
```
|
||||
|
||||
## 1.5 磁盘上两层内容（作者视角）
|
||||
|
||||
```text
|
||||
【导演】recipes/{导演id}/recipe.yaml 该方法的建议近期起点 / 调味说明
|
||||
【能力】modules/{能力id}/prompt.md 共用工序；多导演可选用同一能力
|
||||
modules/catalog.yaml 能力目录：中文名 + 短声明 + 产物 tag（+ 可选 repeatable）
|
||||
```
|
||||
|
||||
- 新建作品**只选导演一层**，不再叠「能力包 + 配方」。
|
||||
- 导演给出的步骤是**近期起点**；本局可增量追加、可反复调用标了 `repeatable` 的能力；验收的是本局【剧本】，不是磁盘死菜谱。
|
||||
|
||||
---
|
||||
|
||||
# 第二部分：称呼定义（必须统一）
|
||||
|
||||
对用户与能力正文，优先用**拍摄隐喻**。括号内为内部/旧称，撰写时勿当用户主词。
|
||||
|
||||
## 2.1 四个核心词
|
||||
|
||||
| 称呼 | 含义 | 内部大致对应 | 禁止对用户说 |
|
||||
|------|------|--------------|--------------|
|
||||
| **导演** | ① 新建时选一次的方法起点（世界模拟器、扩写助手…）；② 会话里负责调度的 Agent | `recipes/`、Main Agent / orchestrator | 总管、配方（作选型主词）、能力包（作第二层选项） |
|
||||
| **剧本** | 本局谈成的流程与规格（活的） | `设计.创作流程` + 各能力产物 + 终稿 `设计.worker集` 等 | 「剧本 Skill 菜单」、死板流程卡 |
|
||||
| **演员** | 上场执行的一次单元 | Worker / `run_worker` | 对用户堆 `Worker · english-id` |
|
||||
| **能力** | 共用工序模块；导演从池里选型编排 | `modules/{id}/` | 组件池、模块（作者文档可用；用户文案用「能力」） |
|
||||
|
||||
关系口诀：
|
||||
|
||||
```text
|
||||
选导演 → 用能力编排 → 谈成剧本 → 演员按剧本上场
|
||||
```
|
||||
|
||||
## 2.2 阶段与界面
|
||||
|
||||
| 称呼 | 含义 |
|
||||
|------|------|
|
||||
| **创作** | lifecycle `design`：谈剧本 |
|
||||
| **游玩** | lifecycle `play`：演员上场 |
|
||||
| **产物** | 某步待验收输出（写入黑板 tag） |
|
||||
| **验收 / 接受** | 用户确认产物算数 |
|
||||
| **黑板** | 按 tag 存正文的上下文板 |
|
||||
| **询问卡** | 结构化提问（选项可改写） |
|
||||
|
||||
## 2.3 创作调度相关（可出现在作者文档，少直接甩给用户）
|
||||
|
||||
| 内部 id | 用户可见 | 含义 |
|
||||
|---------|----------|------|
|
||||
| `design-flow` | 创作 · 流程编排 | 编排/增量修订可变 DAG → `设计.创作流程` |
|
||||
| `design-step` | 创作 · 执行步骤 | 执行剧本中当前那一个能力 |
|
||||
| `opening-generator` | 开局 · 开场白 | 可选；规格收成后的开场白 |
|
||||
|
||||
## 2.4 剧本流程 JSON（编排产物：增量 DAG）
|
||||
|
||||
```json
|
||||
{
|
||||
"brief": "可选：一句话体验复述",
|
||||
"status": "open",
|
||||
"steps": [
|
||||
{ "id": "美学纲领与交互范式", "name": "美学纲领与交互范式", "depends_on": [] },
|
||||
{ "id": "生成规则", "name": "生成规则", "depends_on": ["美学纲领与交互范式"] },
|
||||
{ "id": "生成规则#2", "name": "生成规则", "depends_on": ["生成规则"] }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 规则 |
|
||||
|------|------|
|
||||
| `status` | `open` = 还可追加；`closed` = 不再扩步。缺省兼容旧稿视为已收口 |
|
||||
| `steps` 顺序 | 建议执行顺序 |
|
||||
| `id` | 本局步骤唯一键；同能力多次必须不同 |
|
||||
| `name` | 必须与能力目录中的**固定中文名**完全一致（可重复） |
|
||||
| `depends_on` | 依赖的其它步骤 **id**（若某 name 在本流程唯一，也可写 name） |
|
||||
|
||||
程序用中文 `name` 映射到 `artifact` tag；流程 JSON **不写**英文模块 id / tag。
|
||||
**禁止**一次排死全程固定长链；「生成规则」「具体实例」等标了 `repeatable` 的能力应允许多次编入。
|
||||
|
||||
## 2.5 已合并能力（勿拆回）
|
||||
|
||||
| 错误拆法 | 正确能力 |
|
||||
|----------|----------|
|
||||
| 「交互范式」+「美学纲领」两步 | **美学纲领与交互范式**（`aesthetics-interaction`）一步 |
|
||||
|
||||
询问相近则合并为一步；不要在新能力里建议再拆开。
|
||||
|
||||
## 2.6 命名纪律
|
||||
|
||||
| 种类 | 规则 | 例 |
|
||||
|------|------|-----|
|
||||
| 能力中文名 | 稳定、给人看、进流程 JSON | `实现机制` |
|
||||
| 能力 id | 英文 kebab，= 文件夹名 | `mechanism` |
|
||||
| 产物 tag | 通常 `设计.{中文名或约定名}` | `设计.实现机制` |
|
||||
| 游玩演员 ref | 英文 kebab | `narrator` |
|
||||
| 游玩演员展示名 | 中文 `name` | `叙事转述` |
|
||||
| UI | 禁止裸露内部英文 id | 不要写 `design-step` 给用户 |
|
||||
|
||||
---
|
||||
|
||||
# 第三部分：什么是「能力」（泛用定义）
|
||||
|
||||
## 3.1 定义
|
||||
|
||||
**能力** = 创作期可被编排进剧本的**一步工序**：
|
||||
|
||||
1. 有固定中文名与产物 tag；
|
||||
2. 有一份程序可切割的方法文档（`prompt.md`）；
|
||||
3. 执行时只注入**本能力**方法 + **依赖产物** + 用户表述；
|
||||
4. 与用户对话后产出**可验收**的结构化结果。
|
||||
|
||||
能力**不是**：整场游戏引擎、游玩期每轮演员、也不是导演本身。
|
||||
|
||||
## 3.2 能力在系统中的生命周期
|
||||
|
||||
```text
|
||||
catalog 登记（短声明给编排看；可选 repeatable）
|
||||
→ 导演/编排增量选入 设计.创作流程（可同能力多次）
|
||||
→ 用户验收流程（或后续扩步后再验）
|
||||
→ 轮到该步：若有 opening → 程序先发出
|
||||
→ 用户首答 → LLM 按能力方法谈/写
|
||||
→ 写入 artifact tag → 用户验收
|
||||
→ 下游能力可读该产物（若 depends_on 声明了）
|
||||
→ 不够则再 design-flow 追加同能力新 id
|
||||
```
|
||||
## 3.3 能力作者要交付的两样东西
|
||||
|
||||
| 交付物 | 路径 | 给谁看 |
|
||||
|--------|------|--------|
|
||||
| 目录行 | `modules/catalog.yaml` 一行 | 编排：只看短 `declaration` |
|
||||
| 方法全文 | `modules/{id}/prompt.md` | 执行该步的 LLM + 程序切割 |
|
||||
|
||||
编排时**禁止**把全文 prompt 塞进导演上下文；执行时才注入切割后的方法块。
|
||||
|
||||
## 3.4 能力之间如何相处
|
||||
|
||||
- **正推**：需要 [体验/产物] → 才纳入某能力；勿默认全选池内能力。
|
||||
- **边界**：每个能力在 `meta.boundary` 写清「本步定什么 / 不定什么 / 交给谁」。
|
||||
- **依赖**：由剧本 `depends_on` 声明；执行期程序注入对应产物。
|
||||
- **合并**：询问主题高度重叠 → 合成一个能力（如美学+交互）。
|
||||
- **缩减**：每增必问能否删、能否常驻替代、能否合并。
|
||||
|
||||
## 3.5 方法层硬禁止（写任何能力都适用）
|
||||
|
||||
- 题材 → 固定演员清单。
|
||||
- 否定式路由（「因为是 X 所以不需要 Y」）；应写「需要 A 体验 → 用 B 手段」。
|
||||
- 把「世界模拟」当成一切开场的默认答案。
|
||||
- 为排版/格式单独发明演员；能程序拼则程序拼。
|
||||
- 临时发明 tool。
|
||||
- 一次 burst 写齐全部能力产物。
|
||||
- 在能力产物里堆大量用户看不懂的英文变量名（机器 id 可有，但须有中文展示字段）。
|
||||
|
||||
---
|
||||
|
||||
# 第四部分：能力文档格式规范（程序契约）
|
||||
|
||||
每个能力 = `modules/{id}/prompt.md` + `catalog.yaml` 一行。
|
||||
|
||||
程序**只认 fence 的语言标签**切割，**不认**仅靠 `##` 标题。
|
||||
|
||||
## 4.1 块一览
|
||||
|
||||
| fence 标签 | 必填 | 用途 |
|
||||
|------------|------|------|
|
||||
| `meta` | 强烈建议 | YAML 元数据：选型与边界 |
|
||||
| `opening` | 可选 | **默认问题**；程序发给用户，**不经**本步 LLM |
|
||||
| `task` | **必填** | 本步任务与验收边界 |
|
||||
| `principles` | 强烈建议 | 原则 |
|
||||
| `probe` | 强烈建议 | 追问策略 |
|
||||
| `output` | **必填** | 产物形状（多为 JSON） |
|
||||
| `checklist` | 强烈建议 | 自检 |
|
||||
| `examples` | 可选 | 好/坏对照 |
|
||||
|
||||
未列出的 fence 名：**不要发明**（除非先改程序切割器）。
|
||||
|
||||
## 4.2 标准骨架
|
||||
|
||||
````markdown
|
||||
# {能力中文名}
|
||||
|
||||
> 可选说明。
|
||||
|
||||
## meta
|
||||
|
||||
```meta
|
||||
name: {与 catalog 完全一致的中文名}
|
||||
id: {文件夹 id}
|
||||
artifact: 设计.{…}
|
||||
declaration: >
|
||||
{一行选型话术；与 catalog 对齐}
|
||||
when: |
|
||||
{什么情况下应被编排进来}
|
||||
when_not: |
|
||||
{什么情况下不要进来}
|
||||
boundary: |
|
||||
本能力：…
|
||||
邻接能力：…（点名其它能力中文名，说明分工）
|
||||
```
|
||||
|
||||
## opening
|
||||
|
||||
```opening
|
||||
{用户第一眼看到的引导；整块可省略或留空 = 本步直接 LLM}
|
||||
```
|
||||
|
||||
## task
|
||||
|
||||
```task
|
||||
{只做本步；写清产物 tag；如何对待 opening 首答与依赖产物}
|
||||
```
|
||||
|
||||
## principles
|
||||
|
||||
```principles
|
||||
{正推、缩减、禁止项、与体验的关系}
|
||||
```
|
||||
|
||||
## probe
|
||||
|
||||
```probe
|
||||
{缺什么问什么；一轮 1～2 点；优先具体选项/短场景；勿重复已答清}
|
||||
```
|
||||
|
||||
## output
|
||||
|
||||
```output
|
||||
{推荐产物 JSON 形状：中文键、可渲染}
|
||||
```
|
||||
|
||||
## checklist
|
||||
|
||||
```checklist
|
||||
- [ ] …
|
||||
```
|
||||
|
||||
## examples
|
||||
|
||||
```examples
|
||||
{可选}
|
||||
```
|
||||
````
|
||||
|
||||
## 4.3 `meta` 字段
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `name` | 固定中文名（= 流程 `steps[].name`） |
|
||||
| `id` | 英文 id（= 目录名） |
|
||||
| `artifact` | 本步写入的黑板 tag |
|
||||
| `declaration` | 给编排看的短声明（不是全文） |
|
||||
| `when` / `when_not` | 何时该/不该入选剧本 |
|
||||
| `boundary` | 与邻接能力的分工 |
|
||||
|
||||
## 4.4 `catalog.yaml` 一行
|
||||
|
||||
```yaml
|
||||
- id: example-id
|
||||
name: 示例能力中文名
|
||||
declaration: >-
|
||||
一句话说明何时选用、解决什么
|
||||
artifact: 设计.示例能力中文名
|
||||
```
|
||||
|
||||
| 字段 | 谁用 |
|
||||
|------|------|
|
||||
| `declaration` | 插入导演/编排提示，选型 |
|
||||
| `name` / `artifact` | 流程与执行映射 |
|
||||
| `opening` | 可选覆盖；一般只写在 prompt 的 `opening` 块 |
|
||||
|
||||
改 `name` 会破坏已有剧本 JSON，尽量不改。
|
||||
|
||||
## 4.5 opening 节奏（通用）
|
||||
|
||||
```text
|
||||
若 opening 非空：
|
||||
程序发 opening → 用户首答 → 再调 LLM
|
||||
LLM 上下文含：方法块（通常不含再贴一遍 opening 策略以产品为准）
|
||||
+ 首答 + 依赖产物 + 用户需求
|
||||
task 必须写：禁止重复同一开场；在首答上补洞。
|
||||
```
|
||||
|
||||
## 4.6 注入 LLM 时包含哪些块
|
||||
|
||||
按顺序拼接切割结果，**默认不含** `opening`（开场已由程序发出）。
|
||||
`meta` 是否注入以运行实现为准；撰写时把给人/模型的方法写在 `task`/`principles`/`probe`/`output`/`checklist`。
|
||||
|
||||
## 4.7 产物（`output`）通用要求
|
||||
|
||||
- 形状稳定，便于 UI 按 JSON 渲染。
|
||||
- **键名对人友好**（中文或稳定中文标签）。
|
||||
- 机器 id（如 `ref`）若需要，与中文名成对出现。
|
||||
- 写清「本步完成的定义」；未决放 `开放问题`，不要假完备。
|
||||
- 不要在本能力产物里偷偷交下游能力该交的终稿（除非本能力就是收成步）。
|
||||
|
||||
## 4.8 追问（`probe`）通用要求
|
||||
|
||||
- 一轮 askUser **1～2** 点。
|
||||
- 优先：可直接采用或微调的完整句选项 / 短场景。
|
||||
- 能推断则先写入再复述；只问影响本步核心且不能瞎填的点。
|
||||
- 依赖产物已钉死的内容禁止重问。
|
||||
|
||||
---
|
||||
|
||||
# 第五部分：撰写任一能力时的工作步骤
|
||||
|
||||
1. **定身份**：中文名、id、artifact；写清 when / when_not / boundary。
|
||||
2. **看邻接**：上/下游能力各定什么；禁止重叠问卷。
|
||||
3. **定产物形状**：先定 `output` JSON，再写 task/probe 如何填满它。
|
||||
4. **定 opening**：需要程序先问再 LLM → 写 opening；否则留空。
|
||||
5. **写 principles / probe / checklist**：正推、缩减、禁止套件。
|
||||
6. **对照范例**：深度不低于 `aesthetics-interaction`。
|
||||
7. **自检**：§4 块齐全；name 与 catalog 一致；用户文案无裸英文 id。
|
||||
|
||||
---
|
||||
|
||||
# 第六部分：给撰写 AI 的通用任务指令（粘贴用）
|
||||
|
||||
请撰写（或重写）一个【能力】文档：
|
||||
`skills/dialogue/world-simulator/modules/{id}/prompt.md`
|
||||
（具体中文名 / id / 边界由出题方在指令末行指定。）
|
||||
|
||||
必须遵守：
|
||||
|
||||
1. 本文**第一部分～第四部分**的项目理解、称呼与格式契约。
|
||||
2. 只使用规定的 fence 块；不要发明新 fence 名。
|
||||
3. 对用户话术使用导演/剧本/演员/能力；不要写「总管调度 design-xxx」。
|
||||
4. 正推：体验 → 手段；禁止题材套件与否定式路由。
|
||||
5. 交互与美学已合并为「美学纲领与交互范式」；禁止建议拆回两步。
|
||||
6. 不要修改程序代码；默认只交付 `prompt.md`（除非出题方要求改 catalog）。
|
||||
7. 输出完整 Markdown 文件正文。
|
||||
|
||||
出题方填写：
|
||||
|
||||
```text
|
||||
能力中文名：
|
||||
id：
|
||||
artifact：
|
||||
上游依赖（常见）：
|
||||
明确不做（交给谁）：
|
||||
特殊产物要求（可选）：
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 第七部分：当前能力池速查（选题，非本文重点）
|
||||
|
||||
世界模拟器常用（编排按需，勿默认全选）：
|
||||
|
||||
| 能力 | id | 状态（以仓库为准） |
|
||||
|------|-----|-------------------|
|
||||
| 美学纲领与交互范式 | `aesthetics-interaction` | 范例 |
|
||||
| 实现机制 | `mechanism` | 待细写 |
|
||||
| 世界蓝图与人文地理 | `world-blueprint` | 已写 |
|
||||
| 生成规则 | `generation-rules` | 待细写 |
|
||||
| 具体实例 | `concrete-instances` | 待细写 |
|
||||
| 拓扑图谱 | `topology` | 待细写 |
|
||||
| 叙事指南 | `narrative` | 待细写 |
|
||||
| 变量设计与更新规则 | `variable-design` | 待细写 |
|
||||
| 变量控制上下文 | `variable-context` | 待细写 |
|
||||
| 设计状态栏 | `status-bar` | 待细写 |
|
||||
| 设计回复格式 | `reply-format` | 待细写 |
|
||||
| Worker 规格 | `worker-spec` | 待细写 |
|
||||
| 细化终稿 | `refine` | 待细写 |
|
||||
|
||||
导演示例：世界模拟器、扩写助手（见 `recipes/`）。
|
||||
|
||||
---
|
||||
|
||||
# 附录：与旧文档关系
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| 本文 | **泛用**能力撰写 + 项目/称呼；给外部 AI 的主交接 |
|
||||
| `world-simulator-modules.md` | 仓库内清单与格式摘要 |
|
||||
| `ui-glossary.md` | 用户可见文案权威 |
|
||||
| `architecture.md` | 运行内核；写能力时不必复述实现细节 |
|
||||
| 旧 `capability-mechanism-handoff.md` | 已过时为「单能力特例」；以本文为准 |
|
||||
20
docs/briefs/capability-mechanism-handoff.md
Normal file
20
docs/briefs/capability-mechanism-handoff.md
Normal file
@@ -0,0 +1,20 @@
|
||||
# （已迁移）实现机制单能力简报
|
||||
|
||||
本文件原先只讲「实现机制」特例，**已废弃**。
|
||||
|
||||
请改用泛用交接简报：
|
||||
|
||||
→ **[`capability-authoring-brief.md`](./capability-authoring-brief.md)**
|
||||
|
||||
其中包含：项目概述、导演/剧本/演员/能力称呼、泛用能力格式规范，以及可粘贴给其它 AI 的任务指令。
|
||||
|
||||
若要写「实现机制」，在泛用简报第六部分末行填写：
|
||||
|
||||
```text
|
||||
能力中文名：实现机制
|
||||
id：mechanism
|
||||
artifact：设计.实现机制
|
||||
上游依赖（常见）：美学纲领与交互范式
|
||||
明确不做（交给谁）：拓扑图谱 / Worker 规格 / 变量* / 状态栏 / 回复格式 / 细化终稿
|
||||
特殊产物要求（可选）：总览最小可运行结构；含「为何需要」「未纳入与原因」；正推禁止默认世界模拟套件
|
||||
```
|
||||
@@ -11,14 +11,19 @@ Worker / skill 执行时，Runtime 将黑板 tag 与固定体裁说明拼成 LLM
|
||||
|
||||
## 2. 上半固定、下半动态
|
||||
|
||||
每条 worker prompt 分为两段：
|
||||
每条 worker prompt 自上而下拼接（**一段式 stack，越稳定越靠上**）：
|
||||
|
||||
```text
|
||||
┌─ Preset（会话 presetId）────────────────────────────┐
|
||||
│ 生成参数、prompt 条目（system / 文风片段等） │
|
||||
│ 见 preset-format.md；与 skill 包正交 │
|
||||
└────────────────────────────────────────────────────┘
|
||||
┌─ 上半：固定上下文（Static）────────────────────────┐
|
||||
│ shared-context.md（包级体裁约束） │
|
||||
│ worker SKILL.md 正文（能力说明、自检） │
|
||||
│ contextSegments 中 tier=static 的 tag │
|
||||
│ 例：角色卡.确认稿、世界.蓝图、设计.交互范式 │
|
||||
│ 例：角色卡.确认稿、世界.蓝图、设计.worker集 切片 │
|
||||
│ （含 narrator 的 presentation，无单独美学纲领 tag）│
|
||||
└────────────────────────────────────────────────────┘
|
||||
┌─ 下半：动态上下文（Dynamic）────────────────────────┐
|
||||
│ contextSegments 中 tier=dynamic 的 tag │
|
||||
@@ -30,7 +35,7 @@ Worker / skill 执行时，Runtime 将黑板 tag 与固定体裁说明拼成 LLM
|
||||
原则：
|
||||
|
||||
```text
|
||||
越稳定、越少改 → 越靠上（static）
|
||||
越稳定、越少改 → 越靠上（preset / static）
|
||||
越增量、每轮变 → 越靠下（dynamic）
|
||||
```
|
||||
|
||||
@@ -80,7 +85,11 @@ contextSegments:
|
||||
| `label` | 拼进 prompt 的 Markdown 标题（可选） |
|
||||
| `policy` | 动态段裁剪，见 §5 |
|
||||
|
||||
未声明 `contextSegments` 时，Runtime 回退：按 `inputTags` 顺序输出 JSON `inputs`（当前实现）。
|
||||
未声明 `contextSegments` 时，Runtime 回退：按 `inputTags` 顺序输出 JSON `inputs`。
|
||||
|
||||
有 `contextSegments` 时：按 static → dynamic 顺序拼 Markdown（含 `label` 标题）；实现见 `src/skills/context-segments.ts` → `assembleWorkerContext()`。
|
||||
|
||||
创作前情：`创作.已验收内容` 存各单位**最后一次验收**的内容切片，拼装时格式化为只读前情提要。
|
||||
|
||||
---
|
||||
|
||||
@@ -93,17 +102,20 @@ contextSegments:
|
||||
| `tail_lines_N` | 事件流等取最后 N 行 |
|
||||
| `tail_tokens_N` | 按估算 token 截断（预留） |
|
||||
|
||||
上下文过长时：
|
||||
上下文过长时（**本节管 Run worker 拼装**；创作会话见 `design-orchestrator-guide.md` §7.2）：
|
||||
|
||||
1. 优先靠 policy 裁剪动态段
|
||||
2. 实例 manifest 可覆盖 variant（如 `historyPolicy: last_10_turns`）
|
||||
3. agent 可 invoke 显式 **compress-history** skill 写摘要 tag（调度 skill，不是随手删 prompt）
|
||||
2. **Run 验收后压缩**：过程 tag 归档，仅终产物 + `上下文.定稿摘要` 进入下一 worker（`compress-after-worker.ts`）
|
||||
3. 实例 manifest 可覆盖 variant（如 `historyPolicy: last_10_turns`）
|
||||
4. 长线再考虑显式 compress-history / RAG，禁止「完整历史喂一个 LLM 再筛给另一个」
|
||||
|
||||
**创作**不走本拼装栈：讨论放 session `messages`；单位验收后 **删交互、留产物**。Worker 执行仍始终按契约从黑板重装。
|
||||
|
||||
---
|
||||
|
||||
## 6. contextProfile（实例 manifest）
|
||||
|
||||
实例化阶段产出（写入 `设计.run_skill清单` 或 Book manifest），agent **只选预置档位**，不列 tag：
|
||||
实例化阶段产出（写入 `设计.worker集` 或 Book manifest），agent **只选预置档位**，不列 tag：
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -161,7 +173,7 @@ user:
|
||||
{按 segment 顺序格式化的 Markdown 或结构化块}
|
||||
```
|
||||
|
||||
实现：`src/worker/executor.ts` → `assembleWorkerContext()`（待从纯 JSON inputs 升级）。
|
||||
实现：`src/skills/context-segments.ts` → `assembleWorkerContext()`；由 `src/worker/executor.ts` 调用。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,10 +1,13 @@
|
||||
# 创作流程指南（Creation Playbook）
|
||||
|
||||
> **文档层级：剧本 / 创作流程概念（非系统架构）。**
|
||||
> 系统模块与边界见 [`architecture.md`](./architecture.md)。
|
||||
|
||||
## 0. 内容在哪
|
||||
|
||||
**流程定义在 skill 包里**（orchestrator manifest + `workers/*/SKILL.md`）。本文只保留概念。
|
||||
|
||||
写新包 → `skill-design-guide.md` → 新建 `skills/.../orchestrator.md`。
|
||||
**设计方法（正推、三大步、表与副作用）** → **`design-orchestrator-guide.md`**（权威）。
|
||||
**流程落地**在 skill 包（`orchestrator.md` + `design-intake`）。
|
||||
写新包 → `skill-design-guide.md`（包格式薄层）→ `skills/.../orchestrator.md`。
|
||||
|
||||
---
|
||||
|
||||
@@ -14,30 +17,52 @@
|
||||
Orchestrator 包 能力库 + manifest（静态）
|
||||
黑板 tag 一次 Session 的实参（动态）
|
||||
Book 跨 Session：过程、资产、游玩
|
||||
设计.worker集 实例规格（JSON；accept 后 = Worker 声明）
|
||||
```
|
||||
|
||||
| 层 | 管什么 |
|
||||
|----|--------|
|
||||
| **运行相位** | `idle` / `running` / `waiting_user` — 系统在等什么 |
|
||||
| **业务 stage** | `design`（实例化）→ `play`（运行）→ `done` |
|
||||
| **Agent** | tool loop 内 invoke 哪个 skill |
|
||||
| **Skill** | 读哪些 tag、写哪些 tag、上下文怎么拼 |
|
||||
| **业务 stage** | `design`（创作）→ `play`（游玩）→ `done` |
|
||||
| **Agent** | tool loop 内 invoke 哪个 worker |
|
||||
| **声明** | play 可调度哪些 ref；executor 读声明（非题材管道） |
|
||||
| **Book** | 长期存储，见 `book-storage.md` |
|
||||
|
||||
---
|
||||
|
||||
## 2. 启动
|
||||
## 2. 默认包创作流
|
||||
|
||||
```text
|
||||
skill_selection 选 orchestrator 包
|
||||
intake 启动询问（最小信息）
|
||||
design stage agent 按需 invoke instantiate skill
|
||||
declare ready 进入 play
|
||||
play stage 用户输入 → agent burst → run skill
|
||||
done 归档 Book
|
||||
新建作品 → UI 引导 → 用户首句 → 创作单位逐步谈
|
||||
→ 宜：phase:core → 纲领类 fixed:* → worker:* → refine
|
||||
（非死管道；可穿插，但禁止默认「先写完 worker 再填上下文」）
|
||||
→ 单位 = 已写出的 fixed:* / resident:* | worker:*（示例话题可问用户，非填空）
|
||||
→ 单位跑：只写 设计.worker集.草稿；讨论进 messages
|
||||
→ 用户接受 → 删本单位交互消息，只留产物；草稿保留
|
||||
→ ……谈完后终稿写 设计.worker集 → 验收后才可进 play
|
||||
→ （可选）开局 · 开场白 → 用户手动进游玩
|
||||
→ run：worker 按契约从黑板重装；acceptance=review 处停、压缩过程 tag
|
||||
```
|
||||
|
||||
`startupCompleted` / `instanceReady`：agent 声明 + 程序校验「当前 run_skill清单 可运行」，非固定 prerequisite 打勾。
|
||||
固定上下文 tag 的主收益是 **跨 worker 复用同一份正文**；写下游时仍依赖上游定稿（不能只报 tag 名省掉正文）。能省的是扯皮过程（验收折叠）。
|
||||
|
||||
不再要求用户选择 skill 包；默认 orchestrator 见 `src/config/default-orchestrator.ts`。
|
||||
方法细节见 **`design-orchestrator-guide.md` §7.2**。不要以「世界模拟器」为默认总形态。
|
||||
|
||||
### 进入游玩
|
||||
|
||||
- Worker 集 **accepted**（试验期最低门槛）
|
||||
- **进 play 由用户手动决定**；开局锁定非强制
|
||||
|
||||
### 编辑与重 roll
|
||||
|
||||
```text
|
||||
关键节点可存快照
|
||||
不满意 → 加载 earlier 快照 / 重 roll
|
||||
play：重 roll 替代每轮验收；新输入 = 隐式认可上轮终稿
|
||||
```
|
||||
|
||||
见 `run-snapshot.md`。
|
||||
|
||||
---
|
||||
|
||||
@@ -45,9 +70,9 @@ done 归档 Book
|
||||
|
||||
| | Agent | Runtime |
|
||||
|--|-------|---------|
|
||||
| 决定 | invoke 哪个 skill、何时 ask_user/finish | — |
|
||||
| 拼接上下文 | 只用 read_blackboard 辅助决策 | assembleWorkerContext |
|
||||
| 写黑板 | 否（边界 tool 驱动 worker 写） | 校验 outputTags 后写入 |
|
||||
| 决定 | invoke 哪个 worker、何时 ask_user/finish | — |
|
||||
| 拼接上下文 | 只用 read_blackboard 辅助决策 | 常驻上下文 + 声明拼装 |
|
||||
| 写黑板 | 否（边界 tool 驱动 worker 写） | 校验后写入；表字段尊重 rev |
|
||||
|
||||
Agent **不指定 inputTags**。见 `context-assembly.md`。
|
||||
|
||||
@@ -55,29 +80,16 @@ Agent **不指定 inputTags**。见 `context-assembly.md`。
|
||||
|
||||
## 4. Tool loop burst
|
||||
|
||||
每次用户硬事件后，agent 进入 `running`，在 **burst 上限内** 多轮 tool；碰到边界 tool 或需用户则停。
|
||||
每次用户硬事件后，agent 进入 `running`，在 burst 上限内多轮 tool；碰到边界 tool 或需用户则停。
|
||||
见 `tool-contracts.md`、`runtime-state-machine.md`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 角色卡（一种 Book 形态）
|
||||
|
||||
```text
|
||||
创建过程 designTrace + 对话 → CardBook（design）
|
||||
创建结果 角色卡.确认稿 等 → CardAsset（可导入资产）
|
||||
游玩过程 playTrace + runState → PlayBook
|
||||
游玩存档 PlaySnapshot
|
||||
```
|
||||
|
||||
不拆独立 author/play 包；见 `book-storage.md` §角色卡。
|
||||
|
||||
---
|
||||
|
||||
## 6. 相关文档
|
||||
## 5. 相关
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| `architecture.md` | 总览 |
|
||||
| `skill-design-guide.md` | 设计方法 |
|
||||
| `context-assembly.md` | 上下文拼接 |
|
||||
| **`design-orchestrator-guide.md`** | ★ 创作设计方法 |
|
||||
| `skill-design-guide.md` | 包与字段格式 |
|
||||
| `run-snapshot.md` | 存档 |
|
||||
| `tag-blackboard.md` | 标签 |
|
||||
|
||||
274
docs/daily-use-p0.md
Normal file
274
docs/daily-use-p0.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# 日常使用场景 → P0 详细路径
|
||||
|
||||
## 0. 怎么用本文
|
||||
|
||||
1. **先定场景**：日常到底在干什么（§1）
|
||||
2. **再列功能**：每个场景要哪些能力、是否已有（§2）
|
||||
3. **收成 P0**：只把「日常阻断 / 高频刚需」推进 P0 详细路（§3）
|
||||
4. **其余进后续**：体验打磨与加固，不塞进 P0（§4）
|
||||
|
||||
系统边界见 `architecture.md`；总路线见 `px-roadmap.md`。
|
||||
|
||||
### 0.1 已确认取向（2026-07-26）
|
||||
|
||||
| # | 结论 |
|
||||
|---|------|
|
||||
| 1 | 日常包含 **两类**：AIRP/交互扮演 **与** 长文/爽文创作（同一运行内核） |
|
||||
| 2 | **UI 不自研美学**：布局/控件直接抄参考产品即可；**存档与续作稳定是硬指标** |
|
||||
| 3 | **导演**：新建时用 UI **选一个**（世界模拟器 / 扩写助手…；初期可只有 1 项） |
|
||||
| 4 | **剧本动态**：不在 UI 里点选死板「剧本菜单」；选定导演后，由导演（Agent）听用户说话谈出本局剧本（创作流程 / Worker 集）与调度 |
|
||||
|
||||
用户侧拍摄术语权威对照：**`ui-glossary.md` §0**（导演 / 剧本 / 演员 / 能力）。
|
||||
|
||||
### 0.2 导演 vs 剧本（动态）
|
||||
|
||||
```text
|
||||
导演 = 用户 UI 选一次的方法起点（可调味）
|
||||
= 内部 recipes / 原「能力包·配方」合一
|
||||
= 例：世界模拟器、扩写助手
|
||||
|
||||
剧本 ≠ 再选一张固定流程卡
|
||||
= 选定导演之后：用户说话 → 导演调度创作
|
||||
→ 产出 设计.创作流程 + 设计.worker集（本局活剧本）
|
||||
→ 游玩再按声明让【演员】上场
|
||||
|
||||
能力 = 共用工序（美学纲领与交互范式…）；导演从中编排
|
||||
演员 = 实际上场的 Worker
|
||||
```
|
||||
|
||||
| | 导演 | 剧本（动态） |
|
||||
|--|------|----------------|
|
||||
| 谁选 | **用户 UI**（显式，一层） | **导演 Agent + 用户对话**（隐式） |
|
||||
| 变不变 | 选项相对稳定 | 每局流程、Worker 集、回合调度都可变 |
|
||||
| 忌讳 | 再叠一层「配方」选择 | 固化成死 DAG / 死选单 |
|
||||
| 本仓库对应 | `recipes/` + 默认 skill 包 | `设计.创作流程` / `设计.worker集` |
|
||||
|
||||
因此：**只给导演一个选择 UI**；**不要**再给「剧本 / 配方」做第二层死板选择器。
|
||||
|
||||
**多导演**才有意义的情况：方法边界真不同（世界模拟 vs 扩写助手），而不是同一导演内的题材分化——后者留在剧本层动态谈成。
|
||||
|
||||
---
|
||||
|
||||
## 1. 日常使用场景（产品视角）
|
||||
|
||||
### 1.1 主场景（P0 对准）— 两条产品线，同一内核
|
||||
|
||||
#### 线 A：AIRP / 交互扮演
|
||||
|
||||
| ID | 场景 | 用户在干什么 |
|
||||
|----|------|--------------|
|
||||
| **A1** | 开新档创作 | 描述想扮演/交互什么，谈到可玩的 Worker 集 |
|
||||
| **A2** | 验收定稿 | 接受/重来/跳过询问，直到可进游玩 |
|
||||
| **A3** | 进游玩 + 多回合 | 读终稿 → 输入 → 再生成；偶发重 roll |
|
||||
| **A4** | 续作 + 存档读档 | 关掉再开接着玩；关键节点存/读档 |
|
||||
|
||||
#### 线 B：长文 / 爽文创作
|
||||
|
||||
| ID | 场景 | 用户在干什么 |
|
||||
|----|------|--------------|
|
||||
| **B1** | 开新档创作 | 描述题材/爽点/篇幅；站位偏「写手/统筹」或「助手分段」 |
|
||||
| **B2** | 验收定稿 | 钉大纲/章结构/写手类 Worker 与固定上下文，可进「写」 |
|
||||
| **B3** | 分段出文 | 按大纲或指令生成章/节正文；不满意重 roll 该段 |
|
||||
| **B4** | 续作 + 存档读档 | 连载式接着写；章节点存档、读档不丢正文与进度 |
|
||||
|
||||
A4 / B4 **共用**同一套存档语义（`session.json` + `instance`/`run` 快照）；P0 把稳定性做硬。
|
||||
|
||||
### 1.2 次场景（P0 不精做）
|
||||
|
||||
| ID | 场景 | 说明 |
|
||||
|----|------|------|
|
||||
| S7 | 改表 / 状态面板 | 有就不炸；精致编辑 → 后 |
|
||||
| S8 | 改规格再开写/玩 | 有 instance 加载即可，流程打磨 → 后 |
|
||||
| S9 | 开局 swipe / 多版本对比 | 有更好，非 P0 闸门 |
|
||||
| S10 | 预设商店式管理 | 失败可读即可 |
|
||||
|
||||
### 1.3 明确非 P0
|
||||
|
||||
| ID | 说明 |
|
||||
|----|------|
|
||||
| N2 | 狼人杀级信息隔离 |
|
||||
| N3 | Context Trace 专业调试台 |
|
||||
| N4 | 多导演**运营商店**（P0 只要选择 UI，可仅 1 项） |
|
||||
| N5 | DefinitionVersion 完整发布迁移协议 |
|
||||
| N6 | SillyTavern 卡批量导入导出 |
|
||||
| N7 | 自研精美 UI / 按 `ui-design` 大改布局（**抄参考即可**） |
|
||||
|
||||
---
|
||||
|
||||
## 2. 场景 → 功能需求（含现状）
|
||||
|
||||
图例：✅ 基本有 🟡 有但糙/易踩坑 ❌ 缺或不可靠
|
||||
|
||||
### 共用：创作 / 验收 / 进出
|
||||
|
||||
| 功能 | 现状 | P0? |
|
||||
|------|------|-----|
|
||||
| 新建作品 → 选导演（能力包；初期可仅一项） | ✅/🟡 | **必做**（有选择 UI；一项时默认选中即可） |
|
||||
| 意图可走扮演 **或** 写手/爽文（剧本层动态，不另选死板剧本卡） | 🟡 | **必做** |
|
||||
| 验收出口无死胡同 | 🟡 | **必做** |
|
||||
| 进入游玩/写作阶段门槛清晰 | 🟡 | **必做** |
|
||||
| UI 自研打磨 | — | **不做**；缺块就抄参考产品交互 |
|
||||
|
||||
### 线 A：多回合扮演
|
||||
|
||||
| 功能 | 现状 | P0? |
|
||||
|------|------|-----|
|
||||
| 连续 ≥3 回合不卡死 | 🟡 | **必做** |
|
||||
| 失败可重试 | 🟡 | **必做** |
|
||||
|
||||
### 线 B：长文 / 爽文
|
||||
|
||||
| 功能 | 现状 | P0? |
|
||||
|------|------|-----|
|
||||
| 创作能产出「大纲 + 写章」类 Worker 声明（模板或谈成） | 🟡 | **必做**（不新开第二包；缺则补 **templates / 引导**，不是多包） |
|
||||
| play 期能按段生成正文并展示 | 🟡 | **必做**（≥2 段/章连续） |
|
||||
| 章/段级重 roll 或读档回到段前 | 🟡 | **必做**（与存档同一套：load earlier → 重来） |
|
||||
| 独立长文编辑器 / Monaco | ❌ | **不做**（抄现有主舞台展示正文即可） |
|
||||
|
||||
### 存档 / 续作（最高优先级）
|
||||
|
||||
| 功能 | 现状 | P0? |
|
||||
|------|------|-----|
|
||||
| `session.json` 续作相位正确 | 🟡 | **硬必做** |
|
||||
| 手动存 / 列表 / 加载后可继续 | 🟡 | **硬必做**（线 A、线 B 各验一次） |
|
||||
| 存档不丢终稿正文与关键 tag | 🟡 | **硬必做** |
|
||||
| 分支树 UI | ❌ | 不做 |
|
||||
|
||||
---
|
||||
|
||||
## 3. P0 详细路径
|
||||
|
||||
**P0 一句话**：用户用 UI 选好**导演 Skill**（初期可只有一个）后，AIRP 与长文/爽文都在**剧本层动态**谈成并跑起来，且 **存档/续作稳定**；UI 抄参考即可。
|
||||
|
||||
### 3.1 黄金路径（两条都要绿）
|
||||
|
||||
**线 A（扮演）**
|
||||
|
||||
```text
|
||||
A-GP1 新建 → UI 选导演（可仅一项）→ 描述扮演/交互意图
|
||||
A-GP2 验收至可进游玩
|
||||
A-GP3 ≥3 回合输入→终稿
|
||||
A-GP4 存 run 档 → 刷新/重开续作成功
|
||||
A-GP5 加载 earlier 档或新开一条线之一可用
|
||||
```
|
||||
|
||||
**线 B（长文/爽文）**
|
||||
|
||||
```text
|
||||
B-GP1 新建 → UI 选导演 → 描述爽文/长篇意图（写手或分段助手）
|
||||
B-GP2 验收至可进写作（Worker 集含大纲/写章类能力，勿只能聊天扮演）
|
||||
B-GP3 连续生成 ≥2 段（章）正文
|
||||
B-GP4 存档含已生成正文 → 续作能接着写下一段
|
||||
B-GP5 回到 earlier 档重 roll 某段 或 等价恢复可用
|
||||
```
|
||||
|
||||
### 3.2 工作包
|
||||
|
||||
#### WP-S 存档稳定（最先 / 贯穿）
|
||||
|
||||
| # | 项 | 验收 |
|
||||
|---|-----|------|
|
||||
| S1 | 续作：打开 Book = 恢复可操作相位 + 输入区与等待态一致 | A-GP4 / B-GP4 |
|
||||
| S2 | 手动存：人话 kind；写入后列表可见 | 同上 |
|
||||
| S3 | 加载：黑板 + 消息 + 运行进度一致，可继续生成 | A-GP5 / B-GP5 |
|
||||
| S4 | 回归：线 A、线 B 各完整存读一轮，不手改 `books/` | 双线绿 |
|
||||
| S5 | 已知「存档丢正文 / 续作进死相位」类 bug 清零 | 无阻断 |
|
||||
|
||||
#### WP-D 导演选择（与存档并列早做）
|
||||
|
||||
| # | 项 | 验收 |
|
||||
|---|-----|------|
|
||||
| D0 | 新建作品可选导演（registry）；仅 1 项时默认选中并可确认 | 进入该包创作 |
|
||||
| D1 | 人话展示导演名/简介，不暴露路径 | 可选懂 |
|
||||
|
||||
#### WP-A 进出与失败出口（文案够用即可）
|
||||
|
||||
| # | 项 | 验收 |
|
||||
|---|-----|------|
|
||||
| A1 | 裸 id 不进用户主路径（glossary 底线） | 无 `design-core` 裸露 |
|
||||
| A2 | `waiting_user` 有主按钮出口 | 无死胡同 |
|
||||
| A3 | 进游玩/写作门槛提示 | 误进可理解 |
|
||||
| A4 | LLM/worker 失败：中文 + 重试 | 可回到可输入 |
|
||||
|
||||
#### WP-R 线 A 回合可靠
|
||||
|
||||
| # | 项 | 验收 |
|
||||
|---|-----|------|
|
||||
| R1 | ≥3 回合无卡死 | A-GP3 |
|
||||
| R2 | 假死可刷新恢复且不腐档 | 与 WP-S 一致 |
|
||||
|
||||
#### WP-L 线 B 长文/爽文最小闭环
|
||||
|
||||
| # | 项 | 验收 |
|
||||
|---|-----|------|
|
||||
| L1 | 启动引导明确支持「写爽文/长篇/先大纲再写」 | B-GP1 |
|
||||
| L2 | design 能稳定收到写手向 Worker 集（补 template 或 design 提示，**同一导演内动态谈成**） | B-GP2 |
|
||||
| L3 | play 连续 ≥2 段正文 | B-GP3 |
|
||||
| L4 | 正文在存档/续作中仍在 | B-GP4 |
|
||||
|
||||
#### WP-U UI（抄，不雕）
|
||||
|
||||
| # | 项 | 验收 |
|
||||
|---|-----|------|
|
||||
| U1 | 缺的存档列表/确认/重试控件：直接仿参考产品，不写设计长文 | 能点、能完成 GP |
|
||||
| U2 | **禁止** P0 内按 `ui-design.md` 做大布局重构 | 范围不膨胀 |
|
||||
|
||||
#### WP-E 闸门
|
||||
|
||||
| # | 项 | 验收 |
|
||||
|---|-----|------|
|
||||
| E1 | 线 A、线 B 黄金路径各冷启动 + 续作通过 | 全绿 |
|
||||
| E2 | 更新 `px-roadmap` / `architecture` 进度勾选 | 文档同步 |
|
||||
|
||||
### 3.3 P0 明确不做
|
||||
|
||||
- 第二套死板「剧本选单」/ 固定题材 DAG
|
||||
- 自研精美 UI、工作台大改
|
||||
- 隔离模拟、Trace 台、完整副作用调度、版本迁移协议
|
||||
- 为文采大改全套提示词（仅修**阻断线 B 收不成写手规格**的引导/模板）
|
||||
|
||||
### 3.4 建议顺序
|
||||
|
||||
```text
|
||||
1. WP-S 存档稳定（先修已知腐档）
|
||||
2. WP-D 导演选择 UI（可仅一项）
|
||||
3. WP-A 失败出口 / 进出
|
||||
4. WP-R 线 A 回合
|
||||
5. WP-L 线 B 长文最小闭环（引导 + template + 存档验正文）
|
||||
6. WP-U 仅补抄来的缺口控件（含选导演/存档若未齐）
|
||||
7. WP-E 双线验收闸门 → P0 完成
|
||||
```
|
||||
|
||||
### 3.5 P0 DoD
|
||||
|
||||
- [ ] 线 A：A-GP1–5 通过（含选导演、续作/读档）
|
||||
- [ ] 线 B：B-GP1–5 通过（含选导演、正文不丢）
|
||||
- [ ] 导演选择 UI 可用（可仅一项）
|
||||
- [ ] 无等待死胡同；失败可重试
|
||||
- [ ] 不依赖手改磁盘文件
|
||||
- [ ] UI 无大改承诺；存档稳定优先于观感
|
||||
|
||||
---
|
||||
|
||||
## 4. 日常功能 → 阶段归属（修订）
|
||||
|
||||
| 日常能力 | 阶段 |
|
||||
|----------|------|
|
||||
| 导演选择 UI（可仅一项）、剧本层动态谈规格、AIRP+长文主路径、**存档续作硬稳定** | **P0** |
|
||||
| 抄来的 UI 缺口补齐 | **P0（U）** / 不够再后补 |
|
||||
| 表编辑精修、改规格心流、副作用完整 | **PX1/PX2** |
|
||||
| Trace、预算、版本协议、E2E | **PX3** |
|
||||
| 长文「专业编辑器 / 评测 / 多卷」加深 | **原 PX4 收窄**（P0 已含最小长文） |
|
||||
| 隔离 + 专业调试 | **PX5** |
|
||||
| 多个导演包（方法真不同时再加） | **需要时再加**；非「剧本菜单」 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 假设状态
|
||||
|
||||
| # | 原假设 | 状态 |
|
||||
|---|--------|------|
|
||||
| 1 | 仅 AIRP | **已订正**：+ 长文/爽文 |
|
||||
| 2 | UI 要按设计稿打磨 | **已订正**：抄参考；存档稳定优先 |
|
||||
| 3 | 永远自动加载、无选包 UI | **已订正**：UI 选**导演**；剧本层保持动态 |
|
||||
| 4 | 单包 = 不能多种玩法 | **已澄清**：一个导演内剧本动态分化 |
|
||||
511
docs/design-orchestrator-guide.md
Normal file
511
docs/design-orchestrator-guide.md
Normal file
@@ -0,0 +1,511 @@
|
||||
# 创作设计指导（总管 / 分步 design skills）
|
||||
|
||||
> **文档层级：剧本 / 创作方法（非系统架构）。**
|
||||
> 运行内核边界见 [`architecture.md`](./architecture.md)；本文不定义相位机、持久化或 Context Compiler。
|
||||
|
||||
权威说明：如何从用户意图收成 **实例规格（`设计.worker集` JSON）**，并指导 play 期声明调度。
|
||||
非固定创作流水线；`world-simulator` 等只是可选能力 ref，不是默认总形态。
|
||||
|
||||
相关：`context-assembly.md`（拼装）、`preset-format.md`（全局预设）、`tag-blackboard.md`（黑板）、`run-snapshot.md`（快照）。
|
||||
|
||||
包内落地：
|
||||
|
||||
| 文件 | 角色 |
|
||||
|------|------|
|
||||
| `orchestrator.md` | 总管调度 |
|
||||
| `design-common.md` | 创作共同开头（注入各 design-*） |
|
||||
| `workers/design-core/` | A 核心（开放，不拆 A1→A2→A3 管道） |
|
||||
| `workers/design-worker/` | 一次一个 worker |
|
||||
| `workers/design-fixed/` | 一次一块固定上下文 |
|
||||
| `workers/design-refine/` | C 细化 / 终稿 |
|
||||
|
||||
**运行时以各 SKILL + design-common 为准**；本文是方法长文，改方法时与 skill 切片一起改。
|
||||
|
||||
---
|
||||
|
||||
## 0. 总原则
|
||||
|
||||
```text
|
||||
三大步（每步含自检，可反复，无强制题材工序）
|
||||
A 核心 → 站位 + 系统扮演/输出/交互 + 体验检验
|
||||
B 细节交互 → Worker/常驻上下文能否撑起世界与交互；冲突请用户选
|
||||
C 细化 → 钉死不能瞎发挥的关键前提；表/数据拓扑/副作用；用户是否满意
|
||||
|
||||
全程正推：需要 [体验] → 用 [常驻上下文 | 表 | worker | 程序 | 预设 | tool] 维持/产出
|
||||
每增必问：能否缩减？常驻上下文能否替代？能否合并？黑板够不够/是否多余？
|
||||
```
|
||||
|
||||
**禁止**
|
||||
|
||||
- 题材 → 固定 worker 清单；否定式路由；完整历史喂 LLM 再筛给另一 LLM
|
||||
- 格式/排版专用 worker；临时生成 tool；默认 input 整理 worker
|
||||
- 把「世界模拟」当成开场默认答案
|
||||
- 固定 instantiate 管道（world-blueprint 等）
|
||||
|
||||
**预设**：凡 LLM 请求（总管 / agent / worker）均插入用户预设。
|
||||
**进 play**：用户手动满意后进入（程序不强制开局锁定）。
|
||||
**Play 回合**：用户新输入 = 认可上一轮最终展示；否则重 roll / 编辑后重 roll。表维护可延后。
|
||||
|
||||
**规格格式**：`设计.worker集` 为 **JSON**（权威存储）；解析层可兼容旧 YAML 草稿，新产出必须 JSON。
|
||||
|
||||
---
|
||||
|
||||
## 1. 交互流程（先定「怎么和人轮转」）
|
||||
|
||||
输出本质可以都是「系统给出一截用户可见结果」，但 **轮转形态**不同，规格必须写明：
|
||||
|
||||
| 形态 | 典型 | 规格要点 |
|
||||
|------|------|----------|
|
||||
| 对话回合 | 最终展示一轮 ↔ 用户一轮 | 终稿 tag；无每轮验收 |
|
||||
| 助手分段 | 先大纲/细纲，用户填表再继续 | 表可编辑；阶段门控；大纲可走表副作用 |
|
||||
| 其它 | 旁观多角、写手统筹… | 站位 + 系统扮演共同决定 |
|
||||
|
||||
用户可 **编辑表（精确到字段格）** → 必须有 **字段级版本**（见 §5）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 三大步
|
||||
|
||||
### A. 核心
|
||||
|
||||
#### A1. 用户站位（扮演什么）
|
||||
|
||||
单角代入 / 代理操控 / 旁观·实验 / 写手统筹 / 多角切换…
|
||||
→ 谁决策、输入如何解释、结构骨架。
|
||||
|
||||
#### A2. 系统扮演什么（play agent 整体）
|
||||
|
||||
指整个 **play agent 系统** 要：
|
||||
|
||||
- **扮演什么**（世界执行者？对白对手？写作助手？陈述实验？）
|
||||
- **输出什么**（叙事、摘要、选项、表、大纲块…）
|
||||
- **怎么输出**（单段终稿 / 程序拼状态栏+正文 / 多面板）
|
||||
- **怎么与用户交互**（回合对话、填表驱动、先大纲后正文…）
|
||||
|
||||
由此才谈：要不要转述、程序拼格式、表是否上屏等。
|
||||
|
||||
#### A3. 核心体验检验（首要评分，自检必做）
|
||||
|
||||
对当前理解与「现有 worker/上下文草案」打分或文字判定。
|
||||
|
||||
**对内**：可只在思维链里过一遍。
|
||||
**对外**（总管 `ask_user.assessment`，或关键分叉复述）：写成用户可读的完备度评价，再据此出题。
|
||||
|
||||
**首要（必须检）**
|
||||
|
||||
| 维 | 含义 |
|
||||
|----|------|
|
||||
| 核心体验 / 满足来源 | 用户最想反复感到什么；爽点从哪来（权力、求生、关系、解谜…）——**一切评价与追问以此为轴** |
|
||||
| 用户–`<user>` 关系 | 用户与代入角色/叙述对象的关系是否清楚 |
|
||||
| 焦点位置 | 注意力与镜头落在哪 |
|
||||
|
||||
**可选（有缺口才写，不必凑齐）**
|
||||
|
||||
| 维 | 含义 |
|
||||
|----|------|
|
||||
| 内容维度 | 情节/日常/战斗/推理…比重与情绪质感 |
|
||||
| 人物与关系 | 核心关系动态 |
|
||||
| 身体与感官 | 物质、亲密、暴力等描写边界 |
|
||||
| 背景与规则 | 世界架与规则用途 |
|
||||
| 意义与主题 | 快感 / 代价 / 终点 |
|
||||
|
||||
`assessment` 建议结构（按需删维）：
|
||||
|
||||
```text
|
||||
# 内容维度
|
||||
核心感觉: 完备度 40%
|
||||
已知: …
|
||||
待探: 用户期望的【情绪质感】是【方向A】？【方向B】？还是组合？
|
||||
|
||||
人物与关系: 完备度 50%
|
||||
已知: …
|
||||
待探: …
|
||||
```
|
||||
|
||||
`questions`：只针对「待探」里必须用户拍板的点；一次 1～2 题。
|
||||
- `prompt`：明确题干（「你更倾向于哪种…」）
|
||||
- `options`：**建议示范**（可含短场景钩子 + 点题句），用户可改写后采用；禁止空泛是/否
|
||||
|
||||
自问：缺口是常驻上下文、表、worker，还是必须问用户？能推断就别问。
|
||||
|
||||
变造世界提示：用户常给「基础架 + 变种设定」；核心体验往往来自变种——从设定读内核，但 **不要**写成固定工序，也不要题材锁死体验。
|
||||
|
||||
#### A 步通用自检
|
||||
|
||||
见 §3。
|
||||
|
||||
---
|
||||
|
||||
### B. 细节交互
|
||||
|
||||
对照 A 的结论，检查草案：
|
||||
|
||||
1. **现有 worker（+ 常驻上下文）能否满足需求？**
|
||||
2. **能否支撑起整个世界/助手流程？**
|
||||
3. **有无冲突必须用户选择？**（两套互斥满足来源、互斥交互形态等 → `ask_user`）
|
||||
|
||||
仍用正推补洞；能固定上下文则不上 worker（§6：示例话题可问用户，不是填空表）。
|
||||
**顺序软规则**：纲领类固定上下文（风格/叙事/美学）宜先于大量 worker——同一份 tag 挂多个 worker，而不是先列 worker 再填上下文。
|
||||
然后 §3 自检。
|
||||
|
||||
---
|
||||
|
||||
### C. 细化
|
||||
|
||||
原则：只钉 **不能交给 AI 自由发挥、又对体验关键** 的东西。
|
||||
变造世界已能推出的（已知现代 → 不问常规科技树）默认不问，除非用户提过。
|
||||
|
||||
常钉类（按需）：规则与 **核心实现前提**、状态、**表结构**、**整体叙事指南**（≠ 文风：管世界态度与体验边界）、输入协议。
|
||||
|
||||
本步更盯 **数据**：
|
||||
|
||||
- 什么要 **拓扑化**（依赖、阶段边、触发边）？
|
||||
- 什么要 **数据化/进表**？
|
||||
- 表字段、显隐（折叠防剧透，非防用户）、维护规则、副作用是否清楚？
|
||||
- **用户是否满意** 这些钉死项？
|
||||
|
||||
大纲：**不必**单独「大纲管道」。需要时用 **表 + 副作用**——例如表字段 `当前章=第一章` → 边沿触发插入「第一章细纲」上下文（与好感改人设同一套机制，见 §5）。
|
||||
|
||||
然后 §3 自检。
|
||||
|
||||
---
|
||||
|
||||
## 3. 每一步自检清单（三大步与每一小步共用）
|
||||
|
||||
每完成一截推理或改草案，强制过一遍：
|
||||
|
||||
| # | 问 |
|
||||
|---|-----|
|
||||
| 1 | **能否缩减？** 这条能力/字段/worker 删了是否仍成立？ |
|
||||
| 2 | **增加的必要性？** 删掉会丢掉哪段体验？ |
|
||||
| 3 | **上文是否足够** 辅助主 LLM 完成其 duty？不足补常驻/表/黑板，而非盲目加工人 |
|
||||
| 4 | **写入黑板的内容** 够不够？是否多余？ |
|
||||
| 5 | **能否与其它 worker 合并？** 或 **常驻上下文替代？** |
|
||||
| 6 | **上下文插入是否按「变动/重要度」顺序？**（稳定块与易变块分层；参考 ST 注入位思路） |
|
||||
| 7 | （C 步加重）数据传播、表、副作用、字段版本是否自洽？有无「持续为真每轮触发」？ |
|
||||
|
||||
复述给用户时：说明有什么、**为何没有** 某重型件。
|
||||
|
||||
---
|
||||
|
||||
## 4. 短板加装（表见 §5）
|
||||
|
||||
| 短板 | 做法 |
|
||||
|------|------|
|
||||
| 可见文本质量 | 转述 worker **或** 常驻文风；能轻则轻 |
|
||||
| 记忆 / 长线 / 大纲 / 随机分支 / 人设阶段 | **统一用表**（§5）：维护 + 显隐 + 副作用插换上下文 |
|
||||
| 信息差玩法 | 分角 worker；极贵，慎用 |
|
||||
| 格式 | 程序拼 |
|
||||
| 真随机 / 骰子卡组计算 | 用户触发或填入，或表；已有 tool 手动调；不临时造 tool |
|
||||
| 用户不应知道的信息 | 程序固定注入，不进可见区；非 input 整理 worker |
|
||||
| 输入协议 | 常驻上下文（`()` 元要求、`""` 对白、无包裹=事实等） |
|
||||
|
||||
长线记忆：**不上**则靠模型；**要上**则 RAG（固定少设计）或表；禁止历史互喂筛选。
|
||||
|
||||
---
|
||||
|
||||
## 5. 表（结构 · 版本 · 维护 · 副作用 · 大纲）
|
||||
|
||||
### 5.1 用途
|
||||
|
||||
状态与物品、显隐信息、阶段/章节、随机与事件权重、人设态度段、**大纲/细纲挂载**、驱动常驻上下文插入或替换。
|
||||
|
||||
### 5.2 结构与显隐
|
||||
|
||||
- 扁平、利于二维表 UI；schema 写在 Worker 集
|
||||
- **显形 / 隐藏（可折叠）**：防剧透、分层观看，不是防用户
|
||||
- 维护规则可执行，并带触发语义（默认 once + edge）
|
||||
|
||||
### 5.3 字段格版本（防互相覆盖）
|
||||
|
||||
每一 **字段格**（非仅整表）含至少：
|
||||
|
||||
```text
|
||||
value, rev, updatedAt, source # source: user | worker:<id> | system
|
||||
```
|
||||
|
||||
合并规则：
|
||||
|
||||
- 用户编辑升 `rev`，`source=user`
|
||||
- Worker 写回须带 **读时的 rev**；若当前 rev 已变 → **不覆盖**，跳过或 ask_user
|
||||
- 禁止无条件用维护结果盖掉用户格
|
||||
|
||||
### 5.4 维护 worker
|
||||
|
||||
读：正文/裁决、维护规则、当前表 → 写：字段更新。
|
||||
可不写用户终稿；可与展示链解耦、**延后**跑。
|
||||
|
||||
### 5.5 副作用（含大纲、人设、事件）
|
||||
|
||||
表值变化满足条件 → 触发声明内专用逻辑（改写态度段、插入第 N 章细纲、替换某常驻块等）。
|
||||
|
||||
优先：查表换段；跨阶段再跑改写 LLM。
|
||||
|
||||
**防无限触发（程序约定，写入规格）：**
|
||||
|
||||
1. **边沿**：`prev` 不满足且 `now` 满足才触发
|
||||
2. **阶段字段**：规则绑「进入 stage」，不绑「处于 stage」
|
||||
3. **`fired` / ruleId**：once 规则触发后标记，不再入队
|
||||
4. 可重复须显式（`mode: every_edge`）+ 冷却/边沿
|
||||
5. 同 round 同 ruleId 最多一次；对本轮维护用快照算边沿，限制连锁爆炸
|
||||
|
||||
例：`好感>=60→恋爱` 不得每轮触发；`当前章=第一章`→插入细纲须 edge 或章字段变更 once。
|
||||
|
||||
**规格字段（`tables.side_effects[]`）：**
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "affinity-romance",
|
||||
"field": "好感",
|
||||
"op": "gte",
|
||||
"value": 60,
|
||||
"mode": "once",
|
||||
"action": {
|
||||
"type": "write_tag",
|
||||
"tag": "上下文.角色态度",
|
||||
"content": "恋爱模式：……"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `op` | `eq` / `neq` / `gte` / `lte` / `gt` / `lt` / `truthy` / `changed` |
|
||||
| `mode` | `once`（边沿 + 记 fired）\| `every_edge`（可反复跨边沿） |
|
||||
| `action.type` | `write_tag` / `replace_tag` / `queue_worker` |
|
||||
|
||||
实现：`src/blackboard/table-side-effects.ts`；写 `变量.当前` / `运行.初始变量` 后由 runtime 求值；fired 存 `运行.表副作用.fired`。
|
||||
|
||||
### 5.6 与交互流程
|
||||
|
||||
助手流：生成大纲/细纲 → **用户写入/改表** → 副作用或调度读表继续；始终尊重字段 `rev`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 固定上下文族与预设
|
||||
|
||||
**「固定上下文」是概称**：不必单独开 worker、由程序按契约插入 prompt 的内容。
|
||||
**不上 worker ≠ 不重要**——谈清楚并写进规格的纲领/范式，往往比某个中间 worker 更决定体验。
|
||||
|
||||
### 6.0 Tag 的真正用途（纠正）
|
||||
|
||||
固定上下文用稳定 **tag / 单位 id** 命名（如美学纲领、叙事指南），便于：
|
||||
|
||||
1. **同一份正文挂到多个 worker**（`mount` / `contextSegments` / 声明映射）——这是主收益
|
||||
2. **创作单位分块验收**——扯皮过程可折叠，定稿切片进「创作.已验收内容」（已做）
|
||||
|
||||
**不是**「只报 tag 名就能省掉创作期依赖正文」。写 B 块时若依赖 A 的内容，仍要把 A 的定稿喂给写 B 的 LLM；tag 不能替代依赖传递。
|
||||
|
||||
```text
|
||||
能省：反复扯皮直到定稿之前的过程（验收折叠）
|
||||
不能省：写下游时对上游定稿正文的依赖
|
||||
主收益：跨 worker 复用同一份固定上下文，而不是为每个 worker 各写一份
|
||||
```
|
||||
|
||||
### 6.1 用法（重要：不是填空）
|
||||
|
||||
§6.2 里的名称 **只是示例话题**：告诉 design / 总管——**可以向用户询问类似内容**，再收成固定上下文。
|
||||
|
||||
```text
|
||||
不是：按表逐项填空、默认必谈、谈完才算过关
|
||||
而是：对话中若体验需要钉死某类边界/呈现/协议 → 可以按这类话题问用户 → 写入规格并注入
|
||||
```
|
||||
|
||||
正推仍成立：需要维持 [体验/边界/呈现] 且宜稳定注入 → 固定上下文；会变 → 表；本轮推理 → worker。
|
||||
问什么、问几句、要不要问，由当前体验缺口决定——**禁止把示例表当成问卷。**
|
||||
|
||||
### 6.2 示例话题（可问用户的方向）
|
||||
|
||||
| 话题（示例） | 大致在问什么 | 若收成规格，常见落点 |
|
||||
|--------------|--------------|----------------------|
|
||||
| 交互怎么转 | 站位、系统扮演、输出、怎么一轮一轮交手 | `interaction`（多由 `phase:core` 收） |
|
||||
| 叙事指南 | 世界/助手态度与体验边界（≠ 文风） | `narrative_guide` |
|
||||
| 美学纲领 | 呈现给用户的可读终稿气质 | `presentation` / 常驻美学块 |
|
||||
| 输入协议 | `()` / `""` / 无包裹等约定 | `input_protocol` |
|
||||
| 核心前提 | 不能瞎发挥又关键的硬前提 | `core_premises` |
|
||||
| 其它常驻片段 | 只给部分 worker 的稳定句（态度段、轻规则…） | `resident_context[]` |
|
||||
|
||||
落点 id（`fixed:*` / `resident:*`）仅在 **已经写出内容、要当创作单位验收** 时使用；没有内容就不要当成待填格子。
|
||||
实现里的 `FIXED_CONTEXT_CATALOG` 同样是提示目录，不是 UI 填空项。
|
||||
|
||||
### 6.3 创作顺序（软）
|
||||
|
||||
```text
|
||||
phase:core（核心体验 + 交互）
|
||||
→ 纲领类固定上下文（风格 / 叙事 / 美学…）——宜先于大量 worker
|
||||
→ 一次一个 worker（声明挂载哪些已有 tag，勿复制纲领）
|
||||
→ 杂项常驻 / 表 / 副作用 → 终稿
|
||||
```
|
||||
|
||||
**禁止默认**「先写完 worker 列表，再为每个 worker 填写上下文」。
|
||||
Worker 规格应回答：职责是什么、读哪些已有 tag、写哪些 tag——而不是顺带发明一份私有美学。
|
||||
|
||||
**UI**：检查器把固定上下文做成 **独立卡片区**（非 Worker 子项），每张卡展示 **塞进哪些 Worker**；见 `worker-set-view.ts` 的 `contextTags`。
|
||||
|
||||
### 6.4 常驻条目与预设
|
||||
|
||||
杂项常驻（`resident_context[]`）形状示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "tone",
|
||||
"position": "static",
|
||||
"importance": 2,
|
||||
"content": "文风克制、偏冷",
|
||||
"mount": ["narrator"]
|
||||
}
|
||||
```
|
||||
|
||||
- 默认黑板 tag `上下文.常驻.{id}`；可显式 `tag`
|
||||
- `mount` 空 = 全部 worker；否则仅列出的 ref
|
||||
- 能常驻则不上 worker；叙事指南 / 美学 / 交互等 **若已谈清**，用对应规格字段，不要全塞进含糊 `tone`
|
||||
- 越稳、越决定体验边界 → 插入位越靠上
|
||||
|
||||
预设 = 全局；固定上下文 = 实例/worker 级。
|
||||
用户不可见、模型必须知 → **程序固定拼装**，不是整理用户输入的 worker。
|
||||
实现：`src/skills/resident-context.ts`。
|
||||
|
||||
---
|
||||
|
||||
## 7. 产出与验收
|
||||
|
||||
产出：`设计.worker集` JSON，建议包含：
|
||||
|
||||
- `interaction`：站位、系统扮演、输出形态、与用户轮转方式
|
||||
- `experience_check`：首要三维（及可选维）摘要
|
||||
- `workers[]`：`ref` / `duty` / `rationale` / **`acceptance`（run 验收点，见 §7.3）**
|
||||
- `resident_context[]`：位置、内容摘要、挂载哪些 worker
|
||||
- `tables`：schema、显隐、维护规则、副作用（含 edge/once/stage）
|
||||
- `narrative_guide` / `core_premises`：叙事指南与核心实现前提
|
||||
- `input_protocol`：若需要
|
||||
- `design_end`：可选开局 · 开场白等备忘（非强制管道）
|
||||
|
||||
验收复述须含：站位；系统扮演/输出/交互；体验首要三维；有何 worker/表/副作用；**run 在哪些 worker 后停下来给人看**；为何没有某件；进 play 由用户决定。
|
||||
|
||||
交稿自检：题材词可替换仍成立；§3 清单通过；无持续为真每轮触发；格式程序化；字段级 rev 已设计；每个面向用户的可读终稿点有明确 `acceptance`。
|
||||
|
||||
---
|
||||
|
||||
## 7.1 强用户可读（前端约定）
|
||||
|
||||
创作期检查器须让用户看懂：
|
||||
|
||||
| 面板 | 内容 |
|
||||
|------|------|
|
||||
| **设计** | Worker 集卡片（含 run 验收点标注）、设计进度 |
|
||||
| **验收** | 当前产物结构化预览 + 接受/不接受（主确认点） |
|
||||
| **上下文** | 终产物 tag、活跃 tag、定稿摘要、已归档过程计数 |
|
||||
| **历史** | 调度时间线（可折叠） |
|
||||
|
||||
主 feed：隐藏过程调度；验收中的全文进验收 Tab；**创作对话 messages 全量保留供浏览**；拼给下一 design worker 的「创作.对话」才裁 AI（见 §7.2）。
|
||||
|
||||
---
|
||||
|
||||
## 7.2 创作与 Run：两套上下文（勿混）
|
||||
|
||||
| | 创作 `design` | Run / play |
|
||||
|--|---------------|------------|
|
||||
| 单位 | **创作单位**：一个 worker，或固定上下文族中的一块（交互范式 / 叙事指南 / 美学纲领 / …），同级 | 声明内的 run worker |
|
||||
| 会话 | 用户 ↔ 设计讨论进 **session `messages`（全量，用户可回看）**；**隐藏 AI 历史只作用于拼给模型的 transcript** | Worker **按契约从黑板重装**（`contextSegments` / `inputTags`） |
|
||||
| 验收后折叠 | **不删 messages**；产物在黑板/规格；同步「创作.对话」供下一单位 | 过程 tag 归档 + `上下文.定稿摘要`（`compress-after-worker.ts`） |
|
||||
| 禁止 | 一次收齐整份 worker 集 + 全部固定上下文；把纲领当成「顺便写的备注」 | 把创作闲聊塞进 worker prompt |
|
||||
|
||||
### 创作单位（粒度）
|
||||
|
||||
「固定上下文」= **族名**。族内某块 **只有谈出来并写入规格后** 才成为创作单位；§6.1 示例话题不是待填格子。
|
||||
|
||||
典型推进（非强制工序）：
|
||||
|
||||
1. `phase:core`：站位 + 交互 + 核心体验
|
||||
2. 需要时：风格 / 叙事 / 美学等 **纲领类** 固定上下文先验收（`design-fixed`）
|
||||
3. 各 `worker:{ref}`：挂载已有 tag，勿复制纲领
|
||||
4. 其它 `resident:*` → 表 / 副作用 → 终稿 `设计.worker集`
|
||||
|
||||
单位跑只写 `设计.worker集.草稿`；终稿才写 `设计.worker集`（才 `designInstanceReady`）。
|
||||
|
||||
### 创作会话（简单）
|
||||
|
||||
```text
|
||||
本单位进行中：问答、复述、草稿讨论 → 照常 append 到 messages（用户浏览全量）
|
||||
拼给 AI：写入黑板 tag「创作.对话」= 用户全量 + 仅最后一次 AI 输出（含未完成提问）
|
||||
不需要：步内 policy、创作专用拼装栈改写 messages
|
||||
```
|
||||
|
||||
### 创作折叠（简单）
|
||||
|
||||
```text
|
||||
用户接受本单位产物
|
||||
→ session.messages 不删（用户可继续浏览历史）
|
||||
→ 产物本身在黑板/规格里；已验收内容写入「创作.已验收内容」
|
||||
→ 同步「创作.对话」transcript（仍按：用户全量 + AI 只留最后一次）
|
||||
→ 下一单位从「已定稿产物 + 新对话」继续
|
||||
```
|
||||
|
||||
不在创作期做「定稿摘要再注入下一 design LLM」的复杂链；产物本身在黑板/规格里，够用。
|
||||
「隐藏 AI 历史」= 仅 transcript 裁剪，**绝不**从主 feed 删掉或折叠创作过程消息。
|
||||
|
||||
### Run 压缩（与创作正交）
|
||||
|
||||
```text
|
||||
用户在 run 验收点接受产物
|
||||
→ 终产物 tag 标记 final
|
||||
→ 过程 tag（worker 答复、*.草稿 等）归档
|
||||
→ 写入 上下文.定稿摘要
|
||||
→ 下一 worker 按契约重装时带上摘要与终产物
|
||||
```
|
||||
|
||||
实现：`src/runtime/compress-after-worker.ts`。
|
||||
禁止把完整过程讨论继续喂给下一 **run** worker。
|
||||
|
||||
---
|
||||
|
||||
## 7.3 Run 验收点（创作时必须设计进 Worker 集）
|
||||
|
||||
**不是**「整条 run 有没有验收」的二选一，也不是创作阶段的特例。
|
||||
|
||||
**是：** 规定 **跑完哪个 worker 之后必须停下来让用户阅读/验收**；其余可连续调度。
|
||||
|
||||
| `workers[].acceptance` | 含义 |
|
||||
|------------------------|------|
|
||||
| `review` | 本 worker 完成后进入用户验收；接受后才压缩并允许续跑 |
|
||||
| `continue` | 完成后可接着调下一个，不打断用户 |
|
||||
|
||||
**正推示例（写入 rationale / 复述给人听）：**
|
||||
|
||||
| 意图 | 典型停点 |
|
||||
|------|----------|
|
||||
| 自主长篇 | 大纲 / 主题 worker → `review`；正文链多段 → `continue`，直到用户叫停或大纲段落再 `review` |
|
||||
| 交互 / RP | 产出用户可见终稿的转述（如 narrator）→ `review`；世界裁决等中间层 → `continue` |
|
||||
|
||||
创作期按 **§7.2 创作单位** 分块验收（worker 与固定上下文同级），与上表正交。
|
||||
design-intake / 创作调度必须为 **每个** run worker 写出 `acceptance`；缺省时不得假设「全都不用验收」——面向用户的可读输出默认倾向 `review`，纯中间层倾向 `continue`，吃不准就 ask_user。
|
||||
|
||||
---
|
||||
|
||||
## 7.4 开局 · 开场白（opening-generator）
|
||||
|
||||
创作末尾、Worker 集已 accept 之后。此时 **世界设定、故事设定、表结构通常已经很详细**。
|
||||
|
||||
**主产物是开场白**（玩家迈进世界的第一段可读文本），不是填表。
|
||||
|
||||
```text
|
||||
结合前面的世界 + 故事 + 表结构 → 写开场白
|
||||
初值表 = 与开场同一真相的状态快照（辅）
|
||||
能从已有设定/用户话推出的字段 → 直接填并对齐开场，别问卷
|
||||
只有开场必须成立却推不出的点 → 轻量 ask_user
|
||||
```
|
||||
|
||||
例：已有校园末日设定 + 用户「普通大学生」→ 开场写宿舍/校园第一拍；表里年龄/资产/身份自然对齐；**不要**先发一张年龄资产问卷。
|
||||
|
||||
产出：`输出.开场白`（主）+ `运行.初始变量` / `变量.当前`（辅，字段格）。
|
||||
须用户验收。实现：`workers/opening-generator/SKILL.md`。
|
||||
|
||||
---
|
||||
|
||||
## 8. Play / Run 边界（给总管；运行时按声明执行）
|
||||
|
||||
- 只 `run_worker` 声明内的 ref
|
||||
- 遇 `acceptance: review` → 停、给人看、接受后压缩再继续
|
||||
- 遇 `acceptance: continue` → 可在 burst 内续调下一 worker（受 burst 上限约束）
|
||||
- 表维护 / 副作用可在终稿展示之后延后；写表须尊重字段 `rev` / `source=user`
|
||||
- 开局类 skill 仅创作末尾可选，禁止当 run 每轮技能
|
||||
@@ -16,28 +16,57 @@
|
||||
|
||||
## 2. 文档地图
|
||||
|
||||
| 文档 | 管什么 |
|
||||
|---|---|
|
||||
| `tag-blackboard.md` | **★ 主规格**：标签黑板、skill 分工 |
|
||||
| `context-assembly.md` | **★ 上下文拼接**：上半固定、下半动态 |
|
||||
| `architecture.md` | 总览、agent tool loop、模块边界 |
|
||||
| `runtime-state-machine.md` | 5 相位、tool 边界、burst |
|
||||
| `tool-contracts.md` | 总管 / worker tool |
|
||||
| `orchestrator-skill-format.md` | manifest 写法（非编排表） |
|
||||
| `worker-skill-format.md` | SKILL.md、contextSegments |
|
||||
| `skill-format.md` | 包存储、registry |
|
||||
| `skill-design-guide.md` | 新包设计方法 |
|
||||
| `creation-playbook.md` | 创作流程概念 |
|
||||
| `book-storage.md` | Book、CardAsset、PlayBook、过程存储 |
|
||||
| `run-snapshot.md` | 手动存档 |
|
||||
| `preset-format.md` | 预设导入 |
|
||||
| `implementation-guide.md` | 本文件：文件顺序与职责 |
|
||||
| 层级 | 文档 | 管什么 |
|
||||
|---|---|---|
|
||||
| **系统架构** | **`architecture.md`** | 模块边界、定义/实例、调度、上下文、持久化原则、风险 |
|
||||
| 运行内核 | `runtime-state-machine.md` | 5 相位、tool 边界、burst |
|
||||
| 运行内核 | `tool-contracts.md` | 总管 / worker tool |
|
||||
| 运行内核 | `context-assembly.md` | 上下文拼接：上半固定、下半动态 |
|
||||
| 运行内核 | `tag-blackboard.md` | 标签黑板 |
|
||||
| 持久化 | `book-storage.md` | Book、CardAsset、PlayBook、过程存储 |
|
||||
| 持久化 | `run-snapshot.md` | 手动存档 |
|
||||
| UI | `ui-design.md` | 工作台布局、检查器、composer |
|
||||
| UI | **`ui-glossary.md`** | 用户可见中文口径；禁止裸露内部 id |
|
||||
| 外部参考 | `references.md` | 按层借鉴的 GitHub 仓库 |
|
||||
| 本文件 | `implementation-guide.md` | 文件顺序与职责；在现有内核上补齐 |
|
||||
| **产品体验路线** | **`px-roadmap.md`** | PX0–PX5 交付、DoD、明确不做 |
|
||||
| **日常 → P0** | **`daily-use-p0.md`** | 日常场景、功能映射、P0 详细工作包 |
|
||||
| **剧本 / 方法（非系统架构）** | `design-orchestrator-guide.md` | 创作三大步、表/副作用、自检 |
|
||||
| **剧本 / 方法（非系统架构）** | `creation-playbook.md` | 创作流程概念（指向指导） |
|
||||
| **Skill 格式（非系统架构）** | `orchestrator-skill-format.md` | manifest 写法（非编排表） |
|
||||
| **Skill 格式（非系统架构）** | `worker-skill-format.md` | SKILL.md、contextSegments |
|
||||
| **Skill 格式（非系统架构）** | `skill-format.md` | 包存储、registry |
|
||||
| **Skill 格式（非系统架构）** | `skill-design-guide.md` | 包格式薄层 |
|
||||
| **Skill 格式（非系统架构）** | `preset-format.md` | 预设导入 |
|
||||
|
||||
许可证占位：仓库根 `THIRD_PARTY_NOTICES.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 实现分期
|
||||
## 3. 在现有内核上补齐（当前优先）
|
||||
|
||||
### Phase A0 — 可运行阶段机（当前优先）
|
||||
相位机、Agent tool loop、Skill loader、Worker 声明、上下文拼装、表 rev、Web UI、快照 API **已具备**。
|
||||
**不要**按绿场「领域库 → Mastra → …」重开；增量挂在现有 `phase-runtime` / Book 存储上。系统边界见 `architecture.md` §11。
|
||||
|
||||
**权威执行顺序与验收 DoD → [`px-roadmap.md`](./px-roadmap.md)**（当前焦点 **PX0**）。
|
||||
**日常场景与 P0 工作包 → [`daily-use-p0.md`](./daily-use-p0.md)**。
|
||||
|
||||
| 路线阶段 | 目标 | 备注 |
|
||||
|----------|------|------|
|
||||
| **PX0（当前）** | 导演 UI + 双线主路径 + 存档硬稳定 | 详见 `daily-use-p0.md` / `px-roadmap.md` |
|
||||
| PX1–PX2 | 创作/游玩体验打磨；副作用 | UI 仍可抄 |
|
||||
| PX3 | Trace、预算、规格版本、E2E | — |
|
||||
| PX4 | 长文加深（P0 已含最小闭环） | — |
|
||||
| PX5 | 隔离 + 调试；必要时新导演包 | — |
|
||||
| 延后 | SQLite / 事件溯源 / Mastra·Next | — |
|
||||
|
||||
历史分期 A0–E 见下节（多数已 done，作文件职责索引，不再当作「当前从零启动」路线）。
|
||||
|
||||
---
|
||||
|
||||
## 3b. 历史实现分期（索引）
|
||||
|
||||
### Phase A0 — 可运行阶段机
|
||||
|
||||
目标：**不依赖 LLM**，阶段机整体可运行、可手动驱动、可脚本跑通最小闭环。
|
||||
|
||||
|
||||
@@ -1,37 +1,41 @@
|
||||
# 总管 Skill 格式（Orchestrator / Manifest）
|
||||
|
||||
> **文档层级：Skill 包 manifest 格式（非系统架构）。**
|
||||
> 总管与相位机边界见 [`architecture.md`](./architecture.md)、[`runtime-state-machine.md`](./runtime-state-machine.md)。
|
||||
|
||||
## 1. 定位
|
||||
|
||||
**orchestrator.md** = 本包的 **manifest**：注册有哪些 skill、如何验收、如何声明 instance ready。
|
||||
**不**写逐步流水线剧本；**不**写「总管思维链」逐步调度。
|
||||
**orchestrator.md** = 本包的 **manifest**：注册有哪些 capability、如何验收、何时可进 play。
|
||||
**不**写逐步流水线剧本。
|
||||
**创作方法**见 **`design-orchestrator-guide.md`**（三大步、表、自检）。
|
||||
|
||||
```text
|
||||
用户选包
|
||||
→ design：agent 按需 invoke instantiate skill
|
||||
→ declare ready → play：agent invoke run skill
|
||||
→ done：归档 Book
|
||||
新建作品 → 默认包
|
||||
→ design：design-intake → 设计.worker集 JSON（实例声明）
|
||||
→ 用户验收 → 用户手动进 play
|
||||
→ play：Agent 按 Worker 声明 invoke worker
|
||||
```
|
||||
|
||||
| 谁决定 | 什么 |
|
||||
|--------|------|
|
||||
| **Agent** | 何时 invoke 哪个 skill（tool loop） |
|
||||
| **Manifest** | 可用 skill 列表、验收策略、readiness 规则 |
|
||||
| **Worker SKILL.md** | inputTags、contextSegments、怎么做 |
|
||||
| **Agent** | 何时 invoke 哪个 worker id（tool loop） |
|
||||
| **Manifest** | design worker 列表、验收策略、readiness |
|
||||
| **Worker 集** | 本实例启哪些 worker、表、常驻上下文、副作用 |
|
||||
| **templates** | design-intake 合并用的可选默认契约（非运行时权威） |
|
||||
|
||||
`shared-context.md`：包级 **固定上下文上半**，注入各 worker prompt。总管不读。
|
||||
|
||||
见 `architecture.md`、`skill-design-guide.md`、`context-assembly.md`。
|
||||
见 `architecture.md`、`creation-playbook.md`、`design-orchestrator-guide.md`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 存储位置
|
||||
|
||||
```text
|
||||
skills/novel/weird-rules-short/
|
||||
skills/dialogue/world-simulator/
|
||||
├── orchestrator.md
|
||||
├── shared-context.md # 可选
|
||||
├── worker-templates/ # 可选 ref 模板（design 缺省）
|
||||
└── workers/
|
||||
└── write-rules/SKILL.md
|
||||
└── design-intake/SKILL.md
|
||||
```
|
||||
|
||||
- 文件固定名 **`orchestrator.md`**。
|
||||
@@ -43,142 +47,74 @@ skills/novel/weird-rules-short/
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: weird-rules-short
|
||||
description: >-
|
||||
何时选用：用户要写规则怪谈、守则类短篇。
|
||||
category: novel
|
||||
bookKind: novel
|
||||
name: world-simulator
|
||||
description: >
|
||||
默认能力库：Worker 集即实例声明…
|
||||
category: dialogue
|
||||
bookKind: dialogue
|
||||
workers:
|
||||
- write-rules
|
||||
- review-infer
|
||||
- review-author
|
||||
sharedContext: shared-context.md
|
||||
- design-intake
|
||||
demandTag: 用户.需求
|
||||
startupMode: agent-first
|
||||
uiPrompt: |
|
||||
…
|
||||
---
|
||||
```
|
||||
|
||||
| 字段 | 用途 |
|
||||
|------|------|
|
||||
| `description` | 何时选本包 |
|
||||
| `workers` | run / design 可调度 skill id 白名单（loader 用） |
|
||||
| `bookKind` | Book 存储形态 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 正文章节（推荐）
|
||||
|
||||
```markdown
|
||||
# 标题
|
||||
|
||||
## 启动询问 # 最小 intake
|
||||
## Skill 注册表 # instantiate + run skill 清单与说明（见 §5）
|
||||
## 验收策略 # 哪些 skill 产出需 user_confirmed / approve
|
||||
## Instance Ready # 按 run_skill清单 的动态最低可行性
|
||||
## contextProfile # 可选 variant 说明（见 context-assembly.md）
|
||||
## 用户回合 # user-turn 等（可选）
|
||||
## 禁用行为
|
||||
```
|
||||
|
||||
**不应出现：**
|
||||
|
||||
- 逐步 **Worker 编排表** / **总管思维链**（已废弃为主流程）
|
||||
- `inputTags` / `outputTags` 列表 → 在 `workers/*/SKILL.md`
|
||||
- 写作细则 → Worker SKILL 正文
|
||||
|
||||
---
|
||||
|
||||
## 5. Skill 注册表（替代编排表）
|
||||
|
||||
列出本包 **能力库**，供 agent `list_workers` 与 manifest 校验：
|
||||
## 4. Manifest 正文应有的节
|
||||
|
||||
```markdown
|
||||
## Skill 注册表
|
||||
|
||||
### Instantiate（design stage）
|
||||
|
||||
| id | 说明 | 典型 outputTags |
|
||||
|----|------|-----------------|
|
||||
| interaction-paradigm | 定交互范式与 run_skill清单 | 设计.run_skill清单 |
|
||||
| world-blueprint | 世界背景 | 设计.世界.蓝图 |
|
||||
| persona-draft | 角色卡草稿 | 角色卡.草稿 |
|
||||
|
||||
### Run（play stage）
|
||||
|
||||
| id | 说明 | 默认 acceptance |
|
||||
|----|------|-----------------|
|
||||
| write-rules | 写规则 | user_confirmed |
|
||||
| review-infer | 读者视角验收 | programmatic_review |
|
||||
## Instance Ready / 进入游玩
|
||||
## 验收策略
|
||||
## 总管优先行为
|
||||
## 禁用行为
|
||||
```
|
||||
|
||||
agent **按需 invoke**，不必按表顺序跑全。
|
||||
**不应包含：** 「第 N 步必须跑某 worker」管道剧本。
|
||||
方法细节指向 `design-orchestrator-guide.md`，勿在 manifest 重复长文。
|
||||
|
||||
---
|
||||
|
||||
## 6. 启动询问与 Instance Ready
|
||||
## 5. Skill 注册表
|
||||
|
||||
**启动询问：** 只收集 agent 无法从空推断的最小信息 → `用户.需求` 等。
|
||||
### Design
|
||||
|
||||
**Instance Ready：** 不写死「14 步全完成」，而写：
|
||||
| id | 说明 |
|
||||
|----|------|
|
||||
| design-intake | 产出 设计.worker集 JSON |
|
||||
| （可选）开局赋初值 | 创作末尾可选，非每轮 |
|
||||
|
||||
### Play
|
||||
|
||||
不在 manifest 写死清单。Agent 只调度 **`设计.worker集` 声明内的 ref**。
|
||||
|
||||
---
|
||||
|
||||
## 6. Instance Ready
|
||||
|
||||
```markdown
|
||||
## Instance Ready
|
||||
|
||||
当 `设计.run_skill清单` 已 accepted，且清单中每个 run skill 的
|
||||
**最低 input 要求**（见各 SKILL.md）已在黑板存在或已记录跳过理由。
|
||||
由 agent `declare_instance_ready` + Runtime 校验。
|
||||
当 `设计.worker集` 已 accepted；进 play 由用户手动决定。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收策略
|
||||
|
||||
```markdown
|
||||
## 验收策略
|
||||
|
||||
| skill | requiresApproval | acceptanceMode |
|
||||
|-------|------------------|----------------|
|
||||
| setup-scenario | true | user_confirmed |
|
||||
| world-engine | false | no_confirmation |
|
||||
| present-round | false | user_confirmed |
|
||||
```
|
||||
| design-intake | true | user_confirmed |
|
||||
|
||||
agent 通过 `run_worker(..., requiresApproval)` 触发；默认值也可写在 manifest 供 Runtime 填充。
|
||||
play：**无**每轮强制验收；用户新输入 = 认可上轮终稿；重 roll 替代 reject。
|
||||
|
||||
---
|
||||
|
||||
## 8. contextProfile
|
||||
|
||||
若同一 skill 有多种游玩/创作模式，在 manifest 列出 variant 名与含义；实例化写入 Book。
|
||||
格式见 `context-assembly.md`。
|
||||
|
||||
---
|
||||
|
||||
## 9. 与 Worker SKILL 的关系
|
||||
## 8. 与 Worker 声明的关系
|
||||
|
||||
```text
|
||||
orchestrator.md 注册 + 验收 + readiness
|
||||
workers/*/SKILL.md 能力 + 上下文契约（contextSegments）
|
||||
accept 设计.worker集 → Runtime 构建 InstanceWorkerDeclaration
|
||||
play：仅允许声明内 activeWorkerIds
|
||||
表维护 / 副作用按规格边沿触发（见 design-orchestrator-guide §5）
|
||||
```
|
||||
|
||||
Prompt 注入：
|
||||
|
||||
```text
|
||||
Agent：session 摘要 + tool；可用 read_blackboard
|
||||
Worker：shared-context + SKILL + assembleWorkerContext（上固定下动态）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 迁移说明
|
||||
|
||||
旧包中的 `## Worker 编排`、`## 总管思维链` 仍可作为 **人工参考**，但新包与 world-simulator **不应**以此为主流程。
|
||||
Runtime 目标态以 agent tool loop + manifest 注册表为准。
|
||||
|
||||
---
|
||||
|
||||
## 11. 相关文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| `skill-design-guide.md` | 设计方法 |
|
||||
| `worker-skill-format.md` | SKILL.md 字段 |
|
||||
| `creation-playbook.md` | 概念 |
|
||||
|
||||
195
docs/px-roadmap.md
Normal file
195
docs/px-roadmap.md
Normal file
@@ -0,0 +1,195 @@
|
||||
# PX 路线图（产品体验与交付）
|
||||
|
||||
## 0. 定位
|
||||
|
||||
当前仓库的**执行计划表**。系统边界见 [`architecture.md`](./architecture.md)；日常场景与 P0 工作包见 [`daily-use-p0.md`](./daily-use-p0.md)；文件级索引见 [`implementation-guide.md`](./implementation-guide.md)。
|
||||
|
||||
**不**绿场重写、**不**近端迁 Mastra/Next/SQLite。挂在现有相位机 + Book/快照 + 声明驱动 Worker 上增量交付。
|
||||
|
||||
### 0.1 已锁定产品取向
|
||||
|
||||
| 项 | 决定 |
|
||||
|----|------|
|
||||
| 日常玩法 | **AIRP/交互** + **长文/爽文**（同一内核） |
|
||||
| 导演 Skill | 新建时 **UI 选择**能力包；初期可只有 1 项（默认选中） |
|
||||
| 剧本层 | **动态**：听用户说话谈 Worker 集 + tool loop；不做死板剧本选单/DAG |
|
||||
| UI | **抄参考**即可，不自研美学 |
|
||||
| 硬指标 | **存档 / 续作稳定** |
|
||||
| 多导演 | 仅当方法边界真不同时再加包；爽文≠新导演 |
|
||||
|
||||
### 0.2 成功标尺
|
||||
|
||||
| 级别 | 含义 |
|
||||
|------|------|
|
||||
| **L1 可演示** | 带路能跑通一轮 |
|
||||
| **L2 可自助** | 选导演 → 创作 → 玩/写，少踩坑 |
|
||||
| **L3 可日常** | 双线存档续作可靠；少死循环 |
|
||||
| **L4 可扩展** | 新导演包或隔离模式不改内核边界 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 总计划表（主表）
|
||||
|
||||
| 阶段 | 名称 | 目标标尺 | 核心交付 | 状态 |
|
||||
|------|------|----------|----------|------|
|
||||
| **PX0** | 双线可日常最小集 | L2→摸 L3 | 导演选择 UI；线 A 扮演 + 线 B 长文/爽文主路径；**存档硬稳定**；失败出口；UI 只抄缺口 | **进行中（核心已落地）** |
|
||||
| **PX1** | 创作体验 | L3 design | 规格可读可改、进度可见、表/黑板可手改、instance 改规格 | **进行中（定稿存读+黑板改+进度面板已有）** |
|
||||
| **PX2** | 游玩/写作体验 | L3 play | 阅读主舞台（抄）、状态抽屉、重 roll 顺手、副作用调度、多 run 线打磨 | 未开始 |
|
||||
| **PX3** | 运行可信 | L3 加固 | Context Trace、调度预算、规格钉版本、mock E2E | 未开始 |
|
||||
| **PX4** | 长文加深 | L4 | 章产物/多卷、局部评测、更好的长文阅读面（P0 已含最小长文） | 未开始 |
|
||||
| **PX5** | 隔离 + 调试 | L4 | 私有上下文、泄漏测试；Trace/成本/分支调试台 | 未开始 |
|
||||
|
||||
```text
|
||||
现在 → PX0（存档+双线+导演UI）
|
||||
→ PX1（创作好改）
|
||||
→ PX2（玩/写好用）
|
||||
→ PX3（可信可测）
|
||||
→ PX4 / PX5（按需，可调序）
|
||||
```
|
||||
|
||||
顺序原则：先 **PX0 双线硬路径**，再体验（1–2），再加固（3），再扩展（4–5）。
|
||||
若 PX0–2 出现腐档/死循环，允许提前插入 PX3 对应子项。
|
||||
|
||||
预估（单人全职约）：PX0 1.5–2 周；PX1/PX2 各 2–3 周；PX3 2–3 周；PX4/PX5 各 3–5 周。
|
||||
|
||||
---
|
||||
|
||||
## 2. PX0 — 双线可日常最小集（当前）
|
||||
|
||||
**权威细项**：[`daily-use-p0.md`](./daily-use-p0.md) §3。
|
||||
|
||||
### 2.1 计划表（工作包）
|
||||
|
||||
| 序 | 工作包 | 内容 | 验收要点 |
|
||||
|----|--------|------|----------|
|
||||
| 1 | **WP-S** 存档稳定 | 续作相位正确；手动存/列表/加载；正文与关键 tag 不丢 | 线 A、B 各存读一轮，不手改磁盘 |
|
||||
| 2 | **WP-D** 导演选择 | 新建作品 UI 选导演；registry 列表；仅 1 项时默认选中 | 能选中并进入该包创作 |
|
||||
| 3 | **WP-A** 进出与失败 | glossary 底线；`waiting_user` 有主按钮；LLM/worker 失败可重试 | 无死胡同、无裸 id 挡路 |
|
||||
| 4 | **WP-R** 线 A | 扮演 ≥3 回合不卡 | A-GP1–5 |
|
||||
| 5 | **WP-L** 线 B | 引导+template 能谈成写手规格；≥2 段正文；续作不丢文 | B-GP1–5 |
|
||||
| 6 | **WP-U** UI 抄补 | 仅补存档/确认/选导演等缺口控件 | 不按 ui-design 大重构 |
|
||||
| 7 | **WP-E** 闸门 | 双线冷启动+续作验收；勾选 DoD | 全绿才出 PX0 |
|
||||
|
||||
### 2.2 黄金路径（摘要）
|
||||
|
||||
- **线 A**：选导演 → 扮演意图 → 验收 → ≥3 回合 → 存档 → 续作/读档
|
||||
- **线 B**：选导演 → 爽文/长篇意图 → 验收写手规格 → ≥2 段正文 → 存档含正文 → 续作/读档
|
||||
|
||||
### 2.3 非范围
|
||||
|
||||
死板剧本选单；自研精美 UI；Trace；隔离；完整副作用；多导演商店（列表可扩展，P0 不追求多包运营）。
|
||||
|
||||
### 2.4 DoD
|
||||
|
||||
- [ ] WP-S～E 完成
|
||||
- [ ] 线 A、线 B 黄金路径各冷启动 + 续作通过
|
||||
- [ ] 导演选择 UI 可用（可仅一项）
|
||||
- [ ] 更新本文状态列 + `architecture.md` §13
|
||||
|
||||
### 2.5 挂载
|
||||
|
||||
`web/`（新建选导演、saves）、`session-manager`、`skill-catalog` / registry、`phase-runtime`、引导与 `worker-templates`
|
||||
|
||||
---
|
||||
|
||||
## 3. PX1 — 创作体验
|
||||
|
||||
| 项 | 内容 | DoD |
|
||||
|----|------|-----|
|
||||
| 规格工作台 | 产物为主舞台（可抄 Notion/PR 式验收） | 不看文档能验完 Worker 集进 play |
|
||||
| 进度 | 创作单位已验收/进行中可见 | — |
|
||||
| 表 | 字段可编辑 + rev 不覆盖手改 | 手改后 worker 写入可解释 |
|
||||
| 规格回退 | load instance 再改 | 至少一条路径可用 |
|
||||
|
||||
挂载：`worker-set-view`、`creation-units`、questions UI、表编辑 API。
|
||||
|
||||
---
|
||||
|
||||
## 4. PX2 — 游玩 / 写作体验
|
||||
|
||||
| 项 | 内容 | DoD |
|
||||
|----|------|-----|
|
||||
| 阅读面 | 终稿/章文主视线（抄 ST/阅读器） | ≥10 回合或等价连续写段不卡 |
|
||||
| 重 roll | 发现入口；与快照语义一致 | 存/读/重 roll 各至少一次 |
|
||||
| 状态 | 抽屉看表/变量 | — |
|
||||
| 副作用 | `side_effects` 边沿完整可观测 | fixture：once / changed |
|
||||
| 多线 | 同开局新开 play 线 | 不串 run 状态 |
|
||||
|
||||
挂载：`table-side-effects`、`phase-runtime`、play UI、`run-snapshot`。
|
||||
|
||||
---
|
||||
|
||||
## 5. PX3 — 运行可信
|
||||
|
||||
| 子项 | DoD |
|
||||
|------|-----|
|
||||
| Context Trace | 失败调用能看出装载了什么 |
|
||||
| 调度预算 | 重复/嵌套/Token 触顶可读停止 |
|
||||
| 规格钉版本 | 改规格不污染未迁移旧 run |
|
||||
| mock E2E | 双线+存档脚本可进 CI |
|
||||
|
||||
---
|
||||
|
||||
## 6. PX4 — 长文加深（P0 之后）
|
||||
|
||||
P0 已要求最小长文/爽文闭环。本阶段加深：
|
||||
|
||||
- 章/卷 Artifact 更清晰；多段目录
|
||||
- 简单质量检查（程序优先）
|
||||
- 更好的长文阅读/对照面（仍可抄，可不上 Monaco）
|
||||
|
||||
**不做**：固定小说 DAG；为长文另起调度内核。
|
||||
|
||||
---
|
||||
|
||||
## 7. PX5 — 隔离模拟 + 专业调试
|
||||
|
||||
| 块 | 内容 |
|
||||
|----|------|
|
||||
| 隔离 | 私有上下文、公私事件、泄漏测试（依 Trace） |
|
||||
| 调试 | 调度时间线、Trace 检查器、Token/成本、分支树 |
|
||||
|
||||
若隔离需要**不同方法边界**，以**新导演包**形式加入（UI 多一项），仍保持包内剧本动态。
|
||||
|
||||
---
|
||||
|
||||
## 8. 明确不做（周期内）
|
||||
|
||||
- Mastra / LangGraph 换相位机；Next 重写前端
|
||||
- 完整事件溯源 + SQLite 近端必达
|
||||
- 题材固定 instantiate 管道；死板剧本选单
|
||||
- 把创作方法长文塞回系统架构文
|
||||
|
||||
---
|
||||
|
||||
## 9. 里程碑
|
||||
|
||||
| 里程碑 | 退出 | 产出 |
|
||||
|--------|------|------|
|
||||
| **M0** | PX0 DoD | 双线验收记录；导演 UI；存档稳定 |
|
||||
| **M1** | PX1+PX2 DoD | 内部「可日常」说明 |
|
||||
| **M2** | PX3 DoD | Trace/预算/E2E 绿灯 |
|
||||
| **M3** | PX4 或 PX5 | 长文加深或隔离/调试演示 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 文档 / 代码映射
|
||||
|
||||
| 阶段 | 文档 | 代码 |
|
||||
|------|------|------|
|
||||
| PX0 | `daily-use-p0.md`、`ui-glossary.md` | `web/`、session、saves、catalog、templates |
|
||||
| PX1 | `ui-design.md`（可抄着落地）、design-guide | worker-set、creation-units |
|
||||
| PX2 | `run-snapshot.md`、tag-blackboard | side-effects、phase-runtime |
|
||||
| PX3 | `context-assembly.md`、architecture | assemble、budgets、tests |
|
||||
| PX4 | Skill 薄层 | artifacts、长文面 |
|
||||
| PX5 | 隔离短文（待写） | Trace 强制、debug、stats |
|
||||
|
||||
---
|
||||
|
||||
## 11. 下一行动（立即）
|
||||
|
||||
1. **手工跑双线黄金路径**（线 A ≥3 回合；线 B ≥2 段；存读档）验收 PX0 DoD
|
||||
2. 表字段格级编辑器（当前是黑板 tag 预览级手改）可继续打磨
|
||||
3. 再开 PX2（阅读面 / 副作用 / 多 run）
|
||||
|
||||
**当前**：PX0/PX1 主代码已落地，待你本地用真实 LLM 走一遍确认「能用」。
|
||||
88
docs/references.md
Normal file
88
docs/references.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# 外部项目参考（按层借鉴）
|
||||
|
||||
以下仓库用于架构与实现参考。**只借鉴标明的一层，不把外部项目整体耦合进本仓库实现。**
|
||||
|
||||
本系统运行内核为自研（相位机 + tool loop + 声明驱动 Worker）。Mastra、Next.js、assistant-ui 等**不是**近端迁移目标；若引入，须经适配层，且领域对象不得保存框架内部类型。
|
||||
|
||||
许可证与再分发注意见仓库根 [`THIRD_PARTY_NOTICES.md`](../THIRD_PARTY_NOTICES.md)。
|
||||
|
||||
---
|
||||
|
||||
## 参考原则
|
||||
|
||||
1. 按模块读代码与文档，禁止整仓复制粘贴为业务内核。
|
||||
2. 借鉴交互/产品概念时，数据模型仍用本仓库 Book / Session / 黑板。
|
||||
3. Prompt 拼接、权限、上下文编译由本仓库 Context Compiler 实现，不照搬他站拼接逻辑。
|
||||
4. 依赖使用 lockfile 精确版本；对外部项目的修改放在适配层。
|
||||
|
||||
---
|
||||
|
||||
## 仓库与借鉴层
|
||||
|
||||
### Mastra
|
||||
|
||||
- 仓库：<https://github.com/mastra-ai/mastra>
|
||||
- **可借鉴**：Agent/Tool 声明方式、模型 Provider、结构化输出、Memory/Storage 接口形态、Workflow 适用边界、Observability、TypeScript 组织
|
||||
- **不借鉴为内核**：不把动态调度、上下文权限、Definition/Instance、事件存档交给 Mastra 领域模型；本仓库已有 phase-runtime
|
||||
|
||||
### assistant-ui
|
||||
|
||||
- 仓库：<https://github.com/assistant-ui/assistant-ui>
|
||||
- **可借鉴**：流式聊天、消息组件、Tool 调用展示、会话状态、人工确认、前后端连接方式
|
||||
- **不负责**：Definition、存档、多 Agent 调度模型（仍由本仓库 API + Runtime）
|
||||
|
||||
### LobeChat
|
||||
|
||||
- 仓库：<https://github.com/lobehub/lobe-chat>
|
||||
- **可借鉴**：本地 AI 应用信息架构、会话列表、模型配置 UI、助手/角色配置、插件与知识库管理体验、布局
|
||||
- **不直接采用**：其会话数据模型
|
||||
|
||||
### SillyTavern
|
||||
|
||||
- 仓库：<https://github.com/SillyTavern/SillyTavern>
|
||||
- **可借鉴**：角色卡产品概念、世界书编辑体验、聊天存档与分支心流、角色扮演工作方式、导入导出与兼容性概念
|
||||
- **不照搬**：Prompt 拼接逻辑；世界书检索与权限由 Context Compiler 实现
|
||||
|
||||
### LangGraph.js
|
||||
|
||||
- 仓库：<https://github.com/langchain-ai/langgraphjs>
|
||||
- **可借鉴**：有状态 Runtime、Checkpoint、中断与恢复、Human-in-the-loop、长时间任务可恢复执行
|
||||
- **不采用**：用固定 Graph 表达整场创作流程（本仓库用相位机 + 动态 tool loop）
|
||||
|
||||
### AutoGen
|
||||
|
||||
- 仓库：<https://github.com/microsoft/autogen>
|
||||
- **可借鉴**：多 Agent 消息与生命周期、Agent 选择、事件驱动运行、Tool 执行边界、Runtime 抽象
|
||||
- **不采用**：Agent 间自由转发消息作为权限模型；上下文不得依赖自由转发
|
||||
|
||||
### Letta
|
||||
|
||||
- 仓库：<https://github.com/letta-ai/letta>
|
||||
- **可借鉴**：长期记忆分层、上下文窗口管理、状态与消息历史区分
|
||||
- **仍需自建**：小说、世界书、角色私有状态等领域模型
|
||||
|
||||
### OpenHands
|
||||
|
||||
- 仓库：<https://github.com/All-Hands-AI/OpenHands>
|
||||
- **可借鉴**：运行会话、事件流、Action/Observation、前后端状态同步、暂停恢复与可观测性
|
||||
- **不参考**：软件工程沙箱任务模型
|
||||
|
||||
### CopilotKit
|
||||
|
||||
- 仓库：<https://github.com/CopilotKit/CopilotKit>
|
||||
- **可借鉴**：Agent 与前端状态连接、流式事件、Human-in-the-loop、生成式 UI、动态表与确认交互呈现
|
||||
- **不替代**：本仓库 Book/黑板领域模型
|
||||
|
||||
---
|
||||
|
||||
## 与本仓库模块的映射
|
||||
|
||||
| 本仓库模块 | 主要可参考项目 |
|
||||
|------------|----------------|
|
||||
| Runtime / 调度 / 恢复 | LangGraph.js、AutoGen、OpenHands、Mastra（边界） |
|
||||
| 上下文与记忆 | Letta、Mastra Memory 接口形态 |
|
||||
| 聊天与 HITL UI | assistant-ui、CopilotKit、LobeChat |
|
||||
| 角色卡 / 世界书 / 存档体验 | SillyTavern、LobeChat |
|
||||
| 模型接入与可观测 | Mastra |
|
||||
|
||||
系统架构总览见 [`architecture.md`](./architecture.md)。
|
||||
@@ -2,52 +2,92 @@
|
||||
|
||||
用户手动保存、多档位；与自动续作 `session.json` 分离。
|
||||
|
||||
## 两种 kind（更新语义）
|
||||
**编辑 / 重 roll 的统一做法：恢复到之前的快照，再从该点继续。**
|
||||
创作（design）与运行（play）共用此语义。
|
||||
|
||||
```text
|
||||
存快照 → 继续生成 → 不满意 → 加载 earlier 快照 → 重跑后续 worker / 重出展示
|
||||
```
|
||||
|
||||
## 三种 kind（更新语义）
|
||||
|
||||
| kind | 名称 | 何时存 | 存什么 |
|
||||
|------|------|--------|--------|
|
||||
| **`instance`** | 设计完成 / 资产截面 | design 完成或从 play 剥离设定 | **CardAsset 级** tag（角色卡.确认稿、世界蓝图…）；**不含**轮次、事件流 |
|
||||
| **`run`** | 游玩存档 | play 任意时刻 | instance 层 + `运行.*`、轮次、变量、对话 |
|
||||
| **`instance`** | 创作定稿截面 | Worker 集 accept；可选含 **锁定开局** | `设计.worker集`、静态设定 tag、`运行.初始变量`、`输出.开场白`；**不含**后续轮次、事件流 |
|
||||
| **`opening`** | 开局锁定（可选单独存） | 创作末尾 swipe 选定开场后 | 与 instance 中开局部分相同；便于「同 Worker 集、换开局再开 play 线」 |
|
||||
| **`run`** | 游玩存档 | play 任意时刻 | instance/opening 层 + `运行.*`、轮次、变量当前值、对话 |
|
||||
|
||||
```text
|
||||
CardBook design 完成 → 可存 instance（导出角色卡 / 世界设定）
|
||||
PlayBook 进行中 → 可存 run（第 N 轮续玩）
|
||||
Worker 集 accept → 可存 instance（规格截面）
|
||||
可选开局赋初值 → 可存 instance / opening（非进 play 强制门槛）
|
||||
play 任意时刻 → 可存 多条 run
|
||||
改 Worker 集 → load 旧 instance 再改
|
||||
改某轮输出 → load 该轮前的 run → 重 roll / 重跑
|
||||
```
|
||||
|
||||
**instance** 不再表示「14 步 pipeline 填完」，而是 **agent declare ready 时的可复用资产截面**。详见 `book-storage.md`。
|
||||
**instance** = **Worker 集（+ 可选开局截面）**。进 play 由用户手动决定。见 `book-storage.md`、`design-orchestrator-guide.md`。
|
||||
|
||||
### 同一开局 · 多条存档
|
||||
|
||||
```text
|
||||
opening-generator 锁定 checkpoint = 共用起点
|
||||
├─ run 存档 A（第 5 轮）
|
||||
├─ run 存档 B（第 12 轮，另一分支）
|
||||
└─ 「从同一开局新开一条线」= 清空 run 层、保留 opening/instance 层（见 session-manager startNewPlayLine）
|
||||
```
|
||||
|
||||
多条 **run** 快照共享同一 **opening**（或含 opening 的 **instance**），无需为每条 play 线复制 Worker 集。
|
||||
|
||||
## Swipe 与快照
|
||||
|
||||
创作末尾 **开局** 产出时，可用 message **branch / swipe** 多版本对比（可选）。
|
||||
play 对终稿可用 **重 roll**；用户新输入 = 认可上轮终稿。见 `design-orchestrator-guide.md`。
|
||||
|
||||
## 与三种存储需求
|
||||
|
||||
| 需求 | 用什么 |
|
||||
|------|--------|
|
||||
| 创建角色卡**过程** | CardBook `designTrace` + messages（快照不替代，须 Book 级） |
|
||||
| 创建好的**卡** | CardAsset 或 `instance` 快照 |
|
||||
| 游玩**过程** | PlayBook `playTrace` + `run` 快照 |
|
||||
| 创作过程 | Book `designTrace` + messages |
|
||||
| 实例规格 + 锁定开局 | `instance` / `opening` 快照 |
|
||||
| 游玩过程 | PlayBook `playTrace` + **`run` 快照（同一开局可多条）** |
|
||||
| 改设定 / 重 roll | 加载对应 kind 的 earlier 快照 |
|
||||
|
||||
## 与自动续作
|
||||
|
||||
| | `session.json` | `run-snapshots/` |
|
||||
|--|----------------|------------------|
|
||||
| 触发 | 自动 | 用户手动 |
|
||||
| 触发 | 自动 | 用户手动（关键节点建议提示存档） |
|
||||
| 数量 | 每 Book 1 份 | 多档、可命名 |
|
||||
| 打开作品 | 默认恢复 | 选档 **加载** |
|
||||
| 编辑 | — | **load = 恢复到该档状态** |
|
||||
|
||||
## API
|
||||
|
||||
```text
|
||||
GET /api/books/:bookId/saves
|
||||
POST /api/books/:bookId/saves { label, kind: "instance"|"run", note?, sessionId? }
|
||||
POST /api/books/:bookId/saves { label, kind: "instance"|"opening"|"run", note?, sessionId? }
|
||||
POST /api/books/:bookId/saves/:id/load
|
||||
DELETE /api/books/:bookId/saves/:id
|
||||
```
|
||||
|
||||
（`opening` kind 可在实现中与 `instance` 合并存储，文档层区分语义即可。）
|
||||
|
||||
## 实现
|
||||
|
||||
```text
|
||||
src/types/run-snapshot.ts
|
||||
src/book/run-snapshot-store.ts
|
||||
src/book/snapshot-filters.ts instance 时剥离 运行.* 等
|
||||
src/book/snapshot-filters.ts
|
||||
src/server/session-manager.ts
|
||||
src/server/message-branch.ts swipe / branch checkpoint
|
||||
```
|
||||
|
||||
存储：`books/{bookId}/run-snapshots/{id}.json`
|
||||
|
||||
## 相关
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| `skill-design-guide.md` §0.4 | Worker 集与快照 |
|
||||
| `creation-playbook.md` | 创作流中的开局与存档 |
|
||||
| `context-assembly.md` | 恢复后 worker prompt 仍含 preset + static + dynamic |
|
||||
|
||||
@@ -79,8 +79,7 @@ type WaitingReason =
|
||||
## 6. 典型转移（简化）
|
||||
|
||||
```text
|
||||
idle → skill_selection
|
||||
skill_selected → intake 或 input
|
||||
idle → intake（session_started + initialSkill）
|
||||
intake 完成 / confirm → running → agent burst
|
||||
running → run_worker → approve_step 或 worker 执行
|
||||
worker_completed → review_artifact（user_confirmed）
|
||||
|
||||
@@ -1,184 +1,136 @@
|
||||
# Skill 设计指南
|
||||
# Skill 设计指南（包格式薄层）
|
||||
|
||||
指导 **如何从零设计一个 orchestrator 包**（skill 能力库 + run skill 组合）。
|
||||
格式见 `skill-format.md`、`orchestrator-skill-format.md`、`worker-skill-format.md`；上下文见 `context-assembly.md`。
|
||||
> **文档层级：Skill 包格式薄层（非系统架构）。**
|
||||
> 运行内核见 [`architecture.md`](./architecture.md)；创作方法见下。
|
||||
|
||||
**设计顺序：**
|
||||
**创作方法（三大步、表、自检、正推）** 的权威文档是：
|
||||
|
||||
→ **[`design-orchestrator-guide.md`](./design-orchestrator-guide.md)**
|
||||
|
||||
本文只保留：**如何在仓库里建包、Worker 集弱结构示例、与旧概念对照**。不要在本文重复长方法文。
|
||||
|
||||
格式字段见 `orchestrator-skill-format.md`、`worker-skill-format.md`；上下文见 `context-assembly.md`。
|
||||
|
||||
**设计顺序（概念）：**
|
||||
|
||||
```text
|
||||
1. 用户意图 → run skill 清单（交互范式 skill 产出）
|
||||
2. 每个 run skill 倒推需要哪些 instantiate skill / tag
|
||||
3. 定义各 skill 的 inputTags、outputTags、contextSegments
|
||||
4. 上下文隔离与验收边界
|
||||
5. orchestrator manifest（能力注册，非逐步剧本）
|
||||
1. 用户意图 → design-intake（按 design-orchestrator-guide）→ 设计.worker集 JSON
|
||||
2. 需要时合并 worker-templates 默认契约（仅 design 缺省）
|
||||
3. 用户验收 → 用户手动进 play
|
||||
4. play：按声明调度；表维护/副作用边沿触发
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. 实例化：agent 选 skill，不是填步骤
|
||||
## 0. 设计.worker集
|
||||
|
||||
### 1.1 两层倒推
|
||||
### 0.1 定位
|
||||
|
||||
```text
|
||||
用户意图（长篇 / 短篇 / 思想实验 / 角色卡扮演 …）
|
||||
→ 交互范式 skill：产出 设计.run_skill清单
|
||||
→ 每个 run skill 需要什么输入？
|
||||
→ agent 按需 invoke instantiate skill（能力库中的 SKILL.md）
|
||||
→ declare_instance_ready → play stage
|
||||
旧 **交互范式 / run_skill 清单 / 美学纲领** 合并为单一 tag：**`设计.worker集`（JSON）**。
|
||||
|
||||
| 旧概念 | 新做法 |
|
||||
|--------|--------|
|
||||
| `设计.交互范式` | `interaction`（站位、系统扮演、输出与轮转） |
|
||||
| `设计.run_skill清单` | `workers` + 数据依赖 / 表副作用 |
|
||||
| `设计.美学纲领` | 转述 presentation **或** 常驻上下文；叙事指南 ≠ 文风 |
|
||||
|
||||
Worker 集不是闭集枚举，也不是逐步管道。方法见 `design-orchestrator-guide.md`。
|
||||
|
||||
### 0.2 design-intake
|
||||
|
||||
与用户对话，增量更新草稿，accept 后即实例规格。进 play **由用户手动决定**。
|
||||
|
||||
### 0.3 弱结构示例（JSON）
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"interaction": {
|
||||
"user_stance": "单角代入",
|
||||
"system_role": "世界执行并给出可读叙事",
|
||||
"output": "输出.用户展示 + 可折叠状态表",
|
||||
"turn_shape": "对话回合"
|
||||
},
|
||||
"experience_check": {
|
||||
"user_relation": "…",
|
||||
"focus": "…",
|
||||
"satisfaction_source": "…"
|
||||
},
|
||||
"workers": [
|
||||
{
|
||||
"ref": "world-simulator",
|
||||
"duty": "世界推进与裁决",
|
||||
"rationale": "删掉则无本轮世界结果",
|
||||
"acceptance": "continue"
|
||||
},
|
||||
{
|
||||
"ref": "narrator",
|
||||
"duty": "组装用户可见回复",
|
||||
"rationale": "核心产出干巴，需要可读终稿",
|
||||
"acceptance": "review"
|
||||
}
|
||||
],
|
||||
"resident_context": [
|
||||
{
|
||||
"id": "tone",
|
||||
"position": "static",
|
||||
"content": "文风示例",
|
||||
"mount": ["narrator"]
|
||||
}
|
||||
],
|
||||
"tables": {
|
||||
"schemas": [],
|
||||
"side_effects": [
|
||||
{
|
||||
"id": "affinity-romance",
|
||||
"field": "好感",
|
||||
"op": "gte",
|
||||
"value": 60,
|
||||
"mode": "once",
|
||||
"action": {
|
||||
"type": "write_tag",
|
||||
"tag": "上下文.角色态度",
|
||||
"content": "恋爱模式"
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"narrative_guide": "",
|
||||
"core_premises": [],
|
||||
"input_protocol": {
|
||||
"parens": "() 元要求",
|
||||
"quotes": "\"\" 角色对白",
|
||||
"bare": "无包裹视为事实陈述"
|
||||
},
|
||||
"design_end": {
|
||||
"opening": "optional"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**能力库**（如 world-simulator 包内十几个 instantiate skill）不是 1→N 管道；agent 跳过不需要的 skill，并记录 `设计.跳过.{skillId}`。
|
||||
`presentation` 主要挂转述类；裁决类不挂展示美学。包级共性可写 `shared-context.md`。
|
||||
|
||||
### 1.2 示例：不同意图的 run skill 组合
|
||||
### 0.4 编辑与重 roll
|
||||
|
||||
| 用户意图 | run skill 示例 | 实例化倒推 |
|
||||
|----------|----------------|------------|
|
||||
| 长篇小说 | 变量管理、大纲推荐、转述者、世界机 | 变量目录 skill、叙事指南、世界蓝图… |
|
||||
| 短篇 | 情感流生成器 | 美学纲领、情感曲线约定 |
|
||||
| 思想实验 | 世界模拟器 | 规则、行动格式；**无**转述者 |
|
||||
| 角色卡扮演 | 转述者（+ 可选世界机） | 角色卡确认稿、口吻、回复格式 |
|
||||
|
||||
### 1.3 run 阶段交互形态
|
||||
|
||||
agent 在 play stage 的 burst 内调度 run skill，形态因包而异：
|
||||
|
||||
| 形态 | 适用 | sketch |
|
||||
|------|------|--------|
|
||||
| 单 skill 直出 | 简单大纲 | `outline` |
|
||||
| 行动–反应循环 | 博弈、世界模拟 | 世界机 ↔ 角色决策 ↔ 展示 |
|
||||
| 分叉验收 | 规则怪谈 | `write` → 双 `review` |
|
||||
|
||||
形态写在各 skill 的 **能力说明**里，**不**写进全局编排表逐步剧本。
|
||||
见 `run-snapshot.md`。
|
||||
**创作**：按创作单位验收后删交互留产物。固定上下文相关名称是 **可向用户询问的示例话题**（非填空表）；宜先钉纲领类 tag 再写 worker（挂载复用），见 `design-orchestrator-guide.md` §6。
|
||||
**Run** 验收点（`acceptance: review`）：接受后压缩过程 tag。
|
||||
`acceptance: continue` 的中间 worker 可连跑；面向用户的可读停点由 Worker 集声明。
|
||||
|
||||
---
|
||||
|
||||
## 2. 暂停与用户
|
||||
## 1. 暂停与用户
|
||||
|
||||
### 2.1 边界 tool 即暂停
|
||||
|
||||
agent tool loop 在下列情况 **退出 burst**，进入 `waiting_user`：
|
||||
|
||||
```text
|
||||
ask_user / review_blackboard
|
||||
run_worker + requiresApproval
|
||||
worker 完成 + user_confirmed → review_artifact
|
||||
worker ask_user → worker_questions
|
||||
```
|
||||
|
||||
暂停策略写在 orchestrator manifest 的 **验收策略**，不是「第几步必须停」的管道表。
|
||||
|
||||
### 2.2 user-turn
|
||||
|
||||
用户亲自决策的环节：独立 skill，`用户.最新输入` 写入与 LLM 角色同形 tag，供世界机裁决。见 `worker-skill-format.md`。
|
||||
边界 tool 即暂停（`ask_user`、`review_artifact` 等）。策略写在 manifest **验收策略**，不是「第几步必须停」。
|
||||
Play 默认不对每轮终稿强制 accept。详见 `design-orchestrator-guide.md` §0、§7。
|
||||
|
||||
---
|
||||
|
||||
## 3. 上下文：上半固定、下半动态
|
||||
|
||||
每个 skill（`SKILL.md`）声明：
|
||||
|
||||
```text
|
||||
inputTags / outputTags 黑板接口
|
||||
contextSegments static（上）+ dynamic（下）
|
||||
contextIsolation 谁看不见什么
|
||||
contextProfile variants 实例化时选档位
|
||||
```
|
||||
|
||||
原则：**稳定在上、增量在下**；Runtime 拼接，agent 不改。
|
||||
全文见 `docs/context-assembly.md`。
|
||||
|
||||
### 3.1 分层示例（roleplay-game-theory）
|
||||
|
||||
| tier | 含义 | tag 示例 |
|
||||
|------|------|----------|
|
||||
| static | 前提、实体设定 | `情境.实验.设定`、`角色.{id}.设定` |
|
||||
| dynamic | 历史、本轮 | `运行.事件流`、`可见信息` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 倒推标签
|
||||
|
||||
对每个 skill 填表：
|
||||
|
||||
```text
|
||||
skill id | 职责 | stage(design/play) | inputTags | outputTags | contextSegments | 验收者
|
||||
```
|
||||
|
||||
### 4.1 角色扮演博弈（摘录）
|
||||
|
||||
| skill | 读取 | 写入 | 验收 |
|
||||
|-------|------|------|------|
|
||||
| setup-scenario | `用户.博弈需求` | 情境、规则、角色设定 | 用户 |
|
||||
| world-engine | 情境、规则、事件流、行动 | 可见信息、事件流 | 程序 |
|
||||
| role-decide | 本人设定、事件流、可见信息 | `.思考`、`.行动` | 程序 |
|
||||
| present-round | 本轮产物 | `输出.用户展示` | 用户 |
|
||||
|
||||
展示类 skill 单独存在；agent 调度，不拼长文。
|
||||
|
||||
---
|
||||
|
||||
## 5. 上下文隔离（必查）
|
||||
|
||||
```text
|
||||
□ 哪些 tag 只给用户、不注入生产 skill？
|
||||
□ 盲读 review 不可见哪些 tag？
|
||||
□ 草稿 vs 确认稿：下游何时可当作事实？
|
||||
□ 多角色：role_pov 是否生效？
|
||||
```
|
||||
|
||||
靠 `inputTags` + `contextIsolation` + Runtime 过滤，不靠 prompt 口头禁止。
|
||||
|
||||
---
|
||||
|
||||
## 6. orchestrator manifest（非编排表）
|
||||
|
||||
orchestrator.md 应包含：
|
||||
|
||||
```text
|
||||
□ 启动询问（最小 intake）
|
||||
□ instantiate skill 注册表（id、stage、description）
|
||||
□ run skill 注册表
|
||||
□ 验收策略（哪些 skill 产出需 user_confirmed）
|
||||
□ contextProfile 可选 variant 说明
|
||||
□ declare_instance_ready 最低可行性（按 run_skill清单 动态校验）
|
||||
```
|
||||
|
||||
**不应包含：** 逐步思维链、「第 5 步必须跑 world-engine」类管道脚本。
|
||||
|
||||
---
|
||||
|
||||
## 7. checklist
|
||||
|
||||
```text
|
||||
□ 1. 一句话：本包 play stage 的交互形态
|
||||
□ 2. 交互范式 skill 产出 run_skill清单 的 schema
|
||||
□ 3. 每个 run skill 倒推 instantiate skill 需求
|
||||
□ 4. 各 SKILL.md：input/output、contextSegments、隔离
|
||||
□ 5. shared-context.md（static 上半）
|
||||
□ 6. manifest：注册表 + 验收 + readiness
|
||||
□ 7. skills/README.md 注册
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 示例包
|
||||
|
||||
| 包 | 特点 |
|
||||
|----|------|
|
||||
| `basic` | 单 run skill，最小上下文 |
|
||||
| `weird-rules-short` | 分叉验收 |
|
||||
| `roleplay-game-theory` | 行动–反应循环 |
|
||||
| `world-simulator`（规划） | 大能力库 + agent 实例化 |
|
||||
|
||||
对照时复用 **方法**，不照搬 tag 名或 skill 数量。
|
||||
|
||||
---
|
||||
|
||||
## 9. 相关文档
|
||||
## 2. 相关
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| `context-assembly.md` | 拼接规格 |
|
||||
| `creation-playbook.md` | 概念 |
|
||||
| `orchestrator-skill-format.md` | manifest 写法 |
|
||||
| `book-storage.md` | 过程与资产归档 |
|
||||
| **design-orchestrator-guide.md** | ★ 方法 |
|
||||
| creation-playbook.md | 流程概念 |
|
||||
| orchestrator-skill-format.md | manifest |
|
||||
| worker-skill-format.md | 磁盘 SKILL（声明驱动演进中） |
|
||||
|
||||
@@ -1,5 +1,8 @@
|
||||
# Skill 格式与存储
|
||||
|
||||
> **文档层级：Skill 包格式（非系统架构）。**
|
||||
> 系统级模块与调度边界见 [`architecture.md`](./architecture.md)。
|
||||
|
||||
## 1. 定位：两层 Skill
|
||||
|
||||
本项目有 **两种 Skill 文档**，不要混在一个文件里：
|
||||
@@ -355,72 +358,63 @@ skills:
|
||||
|
||||
---
|
||||
|
||||
## 5. 会话启动：第一个询问是选 Skill
|
||||
## 5. 会话启动：描述需求，而非选包
|
||||
|
||||
Skill 选择发生在**任何创作逻辑之前**。
|
||||
新建作品 **不再** 让用户输入 skill name 或列表编号。Runtime 自动加载默认 orchestrator（`world-simulator`，见 `src/config/default-orchestrator.ts`），直接进入 intake。
|
||||
|
||||
### 5.1 启动转移
|
||||
|
||||
```text
|
||||
idle
|
||||
session_started
|
||||
→ waiting_user(skill_selection)
|
||||
session_started { initialSkill }
|
||||
→ waiting_user(intake)
|
||||
```
|
||||
|
||||
新增 `waitingReason`：
|
||||
`session_started` 携带 `initialSkill` 时跳过 `skill_selection`。
|
||||
registry 中其它包仅供 `startWithOrchestrator` / 旧作品读档兼容。
|
||||
|
||||
**Legacy（旧会话恢复）：**
|
||||
|
||||
```text
|
||||
session_started（无 initialSkill）
|
||||
→ waiting_user(skill_selection) # 仅旧快照可能出现
|
||||
```
|
||||
|
||||
```ts
|
||||
| { kind: "skill_selection"; availableSkills: SkillIndexEntry[] }
|
||||
| { kind: "skill_selection"; availableSkills: SkillIndexEntry[] } // legacy
|
||||
| { kind: "intake"; prompt: string }
|
||||
```
|
||||
|
||||
### 5.2 向用户展示
|
||||
|
||||
来自 orchestrator `## 启动询问`，例如 world-simulator：
|
||||
|
||||
```text
|
||||
请选择创作类型：
|
||||
请用你自己的话描述想做什么，例如：
|
||||
|
||||
【小说】（Book 形态：卷 / 章）
|
||||
1. novel-standard — 标准长篇：大纲 → 事件 → 正文
|
||||
2. weird-rules-short — 短篇规则怪谈：核心 → 规则 → 成章
|
||||
3. basic — 最小演示
|
||||
- 西幻升级、长篇 AI 交互、世界推着走
|
||||
- 部分代入：() 是指令，"" 是角色话，【】 是行动
|
||||
- 或：仿写/扩写、规则怪谈、快节奏爽文……
|
||||
|
||||
【对话】（Book 形态：回合 / 多角色）
|
||||
4. theater-roleplay — 剧场式角色扮演
|
||||
|
||||
也可直接描述你想写什么，我会帮你匹配 skill name。
|
||||
Agent 会根据你的描述推理需要哪些 Worker，并产出 Worker 集。
|
||||
```
|
||||
|
||||
### 5.3 用户回答方式
|
||||
|
||||
```text
|
||||
输入编号或 name：novel-standard
|
||||
输入自然语言：我想写一个剧场扮演
|
||||
输入自定义：用 novel-standard，但是偏悬疑
|
||||
直接描述创作目标（一句话即可）
|
||||
```
|
||||
|
||||
Runtime 解析为 `skill_selected` 事件：
|
||||
Runtime 写入 `用户.需求`（或 skill 指定的 startupTargetKey），确认后进入 design stage。
|
||||
|
||||
```ts
|
||||
{ type: "skill_selected"; payload: { skillId: string; userHint?: string } }
|
||||
```
|
||||
|
||||
然后：
|
||||
### 5.4 两阶段启动（现行）
|
||||
|
||||
```text
|
||||
加载 skills/{skillId}/SKILL.md
|
||||
解析 ## 启动询问 → session.slots.activeSkill
|
||||
→ waiting_user(input)
|
||||
message 来自 SKILL.md「启动询问·向用户展示」
|
||||
必收集项 / 写入目标 同样来自该节
|
||||
阶段 1（系统） 自动绑定默认 orchestrator
|
||||
阶段 2（intake） 启动询问 → 用户描述需求 → confirm → agent burst
|
||||
```
|
||||
|
||||
### 5.4 两阶段启动
|
||||
|
||||
```text
|
||||
询问 1（系统） skill_selection 「用哪个 skill？」→ registry / description
|
||||
询问 2（skill） input 「启动询问」章节 → 每类内容问的不同
|
||||
```
|
||||
|
||||
**只有询问 1 是系统固定的。询问 2 及之后所有创作逻辑，都在 SKILL.md 里。**
|
||||
**Agent 根据需求推理 worker 集**（`design-intake`），不再让用户在 registry 里四选一。
|
||||
|
||||
---
|
||||
|
||||
@@ -495,10 +489,10 @@ Creation Playbook（概念）
|
||||
## 11. 第一版范围
|
||||
|
||||
```text
|
||||
skills/ 目录 + 2 个示例 SKILL.md（novel、theater）
|
||||
启动 → skill_selection → 用户选择 → 加载 skill
|
||||
skills/ 目录 + 示例 orchestrator 包
|
||||
启动 → 自动绑定默认 orchestrator → intake（描述需求）
|
||||
总管 prompt 注入 skill 摘要
|
||||
registry.yaml 可选
|
||||
registry.yaml 可选（legacy 包 / 读档兼容）
|
||||
```
|
||||
|
||||
不做：
|
||||
|
||||
@@ -2,572 +2,67 @@
|
||||
|
||||
## 1. 定位
|
||||
|
||||
本系统用于多 worker 协作式文本生成，覆盖：
|
||||
|
||||
```text
|
||||
简易小说快速撰写（quick-write）
|
||||
规则怪谈 / 短篇结构化创作（weird-rules-short 等）
|
||||
长篇小说 / 交互式写作助手（interactive-novel，TODO）
|
||||
场景扮演模拟（scene-roleplay，TODO）
|
||||
角色扮演 / 角色卡互动（并入 scene-roleplay 的 instantiate + run，见 §2）
|
||||
```
|
||||
|
||||
核心思想：
|
||||
多 worker 协作式文本生成；**默认能力库包名 = `world-simulator`**（创作方法见 `design-orchestrator-guide.md`，不以「世界模拟」为默认总形态）。
|
||||
|
||||
```text
|
||||
黑板 = 标签化数据池
|
||||
标签 = skill 之间的接口
|
||||
skill = SKILL.md 定义的能力；worker = 一次 invoke
|
||||
Agent = tool loop 内调度 invoke 哪个 skill
|
||||
Runtime = 按 skill 契约拼接上下文（上半固定、下半动态）
|
||||
标签 = worker 之间的接口
|
||||
设计.worker集 JSON / 声明 = 读哪些 tag、写哪些 tag、表与常驻上下文
|
||||
Agent = tool loop 内调度 invoke 哪个 id
|
||||
Runtime = 按声明拼接上下文；表字段 rev 合并
|
||||
```
|
||||
|
||||
一句话：**标签驱动 + agent 选 skill + Runtime 拼上下文**——不是固定流水线，也不是 LLM 自由分发上下文。
|
||||
## 2. Skill 包、Worker 声明与 Book
|
||||
|
||||
上下文拼接见 `docs/context-assembly.md`。不要让 agent 临场改 inputTags；分发由 `inputTags` + `contextSegments` 静态声明。
|
||||
```text
|
||||
Skill 包 能力库 + design-intake + 可选 templates
|
||||
设计.worker集（accepted，JSON） 本实例 Worker 声明（play 权威）
|
||||
Session + 黑板 一次运行的实参
|
||||
Book 过程、存档、资产（book-storage.md）
|
||||
```
|
||||
|
||||
### 业务 stage
|
||||
|
||||
```text
|
||||
design（创作：核心→细节交互→细化）→ 用户验收 → 用户手动进 play → done
|
||||
运行相位：idle | running | waiting_user | done | error
|
||||
```
|
||||
|
||||
创作方法权威：`design-orchestrator-guide.md`。
|
||||
|
||||
### 创作
|
||||
|
||||
`design-intake` → accept **`设计.worker集` JSON** → 用户手动进 play（可选开局 · 开场白，非强制锁定）。
|
||||
无独立 instantiate 管道。见 `design-orchestrator-guide.md`。
|
||||
|
||||
### Play
|
||||
|
||||
Agent 只能 `run_worker` **声明中的 ref**；执行契约来自 Worker 集条目（可选合并 `worker-templates/`）。
|
||||
|
||||
---
|
||||
|
||||
## 2. Skill 定义、实例化与 Book
|
||||
|
||||
### 2.1 类比
|
||||
## 3. 核心 tag（world-simulator）
|
||||
|
||||
```text
|
||||
Skill 包（orchestrator manifest + workers） = 能力定义（静态）
|
||||
Session + 黑板 tag = 一次运行的实参
|
||||
Book = 过程、资产、游玩（见 book-storage.md）
|
||||
play stage = agent invoke run skill
|
||||
用户.需求 / 用户.最新输入 / 用户.修订说明
|
||||
设计.worker集 / 设计.worker集.草稿
|
||||
创作.当前单位 / 创作.已验收单位 / 创作.已验收内容 / 创作.对话
|
||||
运行.初始变量 / 运行.事件流 / 运行.本轮.*
|
||||
变量.当前
|
||||
输出.用户展示 / 输出.开场白
|
||||
```
|
||||
|
||||
**写角色卡、收集设定、启动询问** 都不是独立「产品模式」，而是 **实例化阶段** 的不同形态：把 prerequisite tags 写满，然后才进入运行阶段。
|
||||
固定上下文（叙事指南、美学纲领等）在实例规格里落地，play 时经 `resident_context.mount` / `contextSegments` **挂到多个 worker**——这是 tag 化的主收益，不是省掉创作期依赖正文。
|
||||
|
||||
### 2.2 三层阶段（勿混淆）
|
||||
|
||||
```text
|
||||
运行相位（RuntimePhase）
|
||||
idle | running | waiting_user | done | error
|
||||
系统在等什么。见 runtime-state-machine.md
|
||||
|
||||
业务 stage（Book / Session）
|
||||
design（实例化）→ play（运行）→ done
|
||||
|
||||
tag 阶段（黑板条目 tag 名中的段）
|
||||
候选 | 草稿 | 确认稿 | 当前 | 更新
|
||||
单条数据的 lifecycle
|
||||
```
|
||||
|
||||
业务 stage **写在各 skill 的 orchestrator.md**，不扩运行相位 enum。
|
||||
|
||||
### 2.3 实例化（design）
|
||||
|
||||
**职责：** agent 按需 invoke instantiate skill，沉淀 `设计.*` tag；产出 `设计.run_skill清单` 后 declare ready。
|
||||
|
||||
```text
|
||||
选 orchestrator 包
|
||||
→ design stage：启动询问 → agent invoke instantiate skill（能力库）
|
||||
→ declare_instance_ready
|
||||
→ play stage：agent invoke run skill
|
||||
→ done → 归档 Book（过程 + 资产，见 book-storage.md）
|
||||
```
|
||||
|
||||
可从 Book / CardAsset 加载已有 tag，跳过部分 instantiate skill。
|
||||
|
||||
运行相位上，实例化阶段多为 `waiting_user(input)`（启动询问、总管 ask_user）；实例化也可调用 **setup worker**，但仍是 worker（固定 inputTags/outputTags），不是第二个生产总管。
|
||||
|
||||
### 2.4 每个 skill 声明什么
|
||||
|
||||
在 orchestrator.md 中写清（见 orchestrator-skill-format.md）：
|
||||
|
||||
```text
|
||||
## 启动询问 / ## 实例化
|
||||
prerequisiteTags：本 skill 运行前必须有的 tag
|
||||
instanceReadyWhen：何时可进入 run stage（文字条件 + tag 列表）
|
||||
写入目标 tag（可多个；不必再塞进单一 book.brief）
|
||||
|
||||
## 阶段定义
|
||||
instantiate（或沿用 stageId brief）→ run（write / review …）→ done
|
||||
|
||||
## Worker 编排
|
||||
仅 run stage 及之后调度生产 worker；instantiate 阶段只 ask_user 或 run setup worker
|
||||
```
|
||||
|
||||
### 2.5 已有雏形：weird-rules-short
|
||||
|
||||
| 业务 stage | 现 stageId | 含义 |
|
||||
|---|---|---|
|
||||
| 实例化 | `brief` | 启动询问 → `book.brief`（≈ `需求.核心要点`）→ `startupCompleted` |
|
||||
| 运行 | `write` | `write-rules` 产出规则与 core |
|
||||
| 运行 | `review` | 双验收 worker |
|
||||
| 结束 | `done` | finish |
|
||||
|
||||
`basic` 同理：`brief` = 实例化，`outline` worker = 运行。
|
||||
文档与实现迁移时，可将 stageId 改名为 `instantiate`，或保留 `brief` 但在 ## 阶段定义 注明 **brief ≡ instantiate**。
|
||||
|
||||
### 2.6 角色卡
|
||||
|
||||
不再单独维护 `character-card-author` skill 包。角色设定、口吻、行为边界等 tag 在 **扮演类 skill 的 instantiate 段** 收集或生成（可选 setup worker）。
|
||||
若需跨 Session 复用，将 `角色.A.设定`、`角色卡.确认稿` 等 **确认稿** 存入 Book，新 Session **加载 Book** 而非再跑完整实例化。
|
||||
|
||||
### 2.7 Book 与黑板
|
||||
|
||||
```text
|
||||
黑板（Session 内） 运行时 tag 池；worker 读写
|
||||
Book（项目级） 长期实例；accepted 确认稿归档；下一场 Session 可加载
|
||||
```
|
||||
|
||||
详见 `docs/book-storage.md`。Session 是一次运行；Book 是一个创作项目（一本小说、一个扮演项目）。
|
||||
命名与创作单位 id 见 `design-orchestrator-guide.md` §6、`ui-glossary.md`；词表可另补 `docs/tag-vocabulary.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 黑板条目
|
||||
|
||||
### 2.1 最小结构
|
||||
|
||||
```ts
|
||||
type BlackboardItem = {
|
||||
id: string;
|
||||
tag: string;
|
||||
content: string;
|
||||
source: string;
|
||||
metadata?: Record<string, unknown>;
|
||||
};
|
||||
```
|
||||
|
||||
### 2.2 可选增强
|
||||
|
||||
```ts
|
||||
type BlackboardItem = {
|
||||
id: string;
|
||||
tag: string;
|
||||
content: string;
|
||||
source: string;
|
||||
scope?: string;
|
||||
createdAt?: number;
|
||||
updatedAt?: number;
|
||||
dependencies?: string[];
|
||||
metadata?: Record<string, unknown>;
|
||||
};
|
||||
```
|
||||
|
||||
### 2.3 字段含义
|
||||
|
||||
```text
|
||||
id 唯一标识，追踪与依赖
|
||||
tag 标签本体，决定身份与消费路径（核心）
|
||||
content 具体内容（字符串）
|
||||
source 产生该条目的 worker id，调试用
|
||||
scope 作用范围，如当前章节、场景、项目（可选）
|
||||
dependencies 依赖的其他黑板条目 id（可选）
|
||||
metadata 置信度、真实性、控制模式等（不参与基础路由）
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
```text
|
||||
tag 是核心路由依据。
|
||||
source 不是路由依据，只用于调试与溯源。
|
||||
metadata 不参与基础路由，除非某 skill 明确约定。
|
||||
```
|
||||
|
||||
**已废弃：** 旧模型的 `key`、`summary`、`tags[]`、`readableBy`、`writableBy` 作为路由字段。迁移期代码可能仍保留 `BlackboardEntry`，以本文为准逐步替换。
|
||||
|
||||
---
|
||||
|
||||
## 4. 标签原则
|
||||
|
||||
标签不是信息分类学，而是 **工作流接口**。
|
||||
|
||||
### 3.1 设计原则
|
||||
|
||||
```text
|
||||
标签越少越好，但必须能区分不同消费路径。
|
||||
两个信息若永远被同一批 worker 消费，可合并 tag。
|
||||
若在不同阶段被不同 worker 消费，必须拆分 tag。
|
||||
若可能被误当成事实，必须加阶段段。
|
||||
若涉及角色私有认知，tag 里必须体现角色归属。
|
||||
```
|
||||
|
||||
### 3.2 推荐格式
|
||||
|
||||
```text
|
||||
对象.内容
|
||||
对象.内容.阶段
|
||||
领域.对象.内容.阶段
|
||||
```
|
||||
|
||||
不强制四段式；按复杂度逐级增加。
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
大纲.草稿
|
||||
事件.草稿
|
||||
正文.草稿
|
||||
正文.确认稿
|
||||
|
||||
角色.A.行动.候选
|
||||
角色.A.台词.候选
|
||||
角色.A.内心想法.候选
|
||||
角色.A.记忆.当前
|
||||
```
|
||||
|
||||
### 3.3 标签替代的旧字段
|
||||
|
||||
```text
|
||||
角色.A.内心想法.候选
|
||||
```
|
||||
|
||||
已表达：归属 A、类型为内心想法、阶段为候选、消费路径由声明 inputTags 的 worker 决定。
|
||||
|
||||
**不需要** 再写 `owner`、`visibleTo`、`type=action` 等平行字段。
|
||||
|
||||
### 3.4 匹配规则（Runtime）
|
||||
|
||||
Worker frontmatter 声明 `inputTags`：
|
||||
|
||||
```yaml
|
||||
inputTags:
|
||||
- "需求.核心要点" # 精确匹配
|
||||
- "角色.A.*" # 前缀匹配：tag 以「角色.A.」开头
|
||||
- "大纲.*.草稿" # 前缀匹配
|
||||
```
|
||||
|
||||
规则：
|
||||
|
||||
```text
|
||||
无通配 → 精确匹配 tag
|
||||
以 .* 结尾 → 前缀匹配（实现优先于完整正则）
|
||||
多条命中 → 默认按 updatedAt 取最新；或 worker 声明 inputMerge: concat | latest
|
||||
```
|
||||
|
||||
总管调度时也可对 **tag 索引**（不含 content）做存在性判断，例如「是否有 规则.确认稿」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 阶段标签
|
||||
|
||||
阶段表示同一类信息在不同生命周期下的语义。
|
||||
|
||||
```text
|
||||
候选 worker 生成的可能内容，不等于事实
|
||||
草稿 生成中的文本或结构
|
||||
确认稿 用户或流程确认，可进入长期状态
|
||||
当前 当前生效状态
|
||||
更新 状态变化结果
|
||||
```
|
||||
|
||||
重要规则：
|
||||
|
||||
```text
|
||||
候选 ≠ 已发生。
|
||||
草稿 ≠ 确认稿。
|
||||
角色行动候选不能直接写入长期记忆。
|
||||
长期记忆优先从正文.确认稿 与明确 记忆.更新 生成。
|
||||
```
|
||||
|
||||
验收（`user_confirmed` / `programmatic_review`）通过后，Runtime 将对应产物 tag 从 `.草稿` 升级为 `.确认稿`（或写入新的确认稿条目并标记旧草稿 superseded）。
|
||||
|
||||
---
|
||||
|
||||
## 6. Worker
|
||||
|
||||
每个 worker 是固定的标签消费者和生产者。
|
||||
|
||||
### 5.1 类型
|
||||
|
||||
```ts
|
||||
type WorkerDefinition = {
|
||||
id: string;
|
||||
name: string;
|
||||
description: string;
|
||||
inputTags: string[];
|
||||
outputTags: string[];
|
||||
inputMerge?: "latest" | "concat";
|
||||
run: (context: WorkerContext) => Promise<WorkerResult>;
|
||||
};
|
||||
|
||||
type WorkerContext = {
|
||||
taskId: string;
|
||||
workerId: string;
|
||||
items: BlackboardItem[];
|
||||
params?: Record<string, unknown>;
|
||||
};
|
||||
|
||||
type WorkerResult = {
|
||||
items: BlackboardItem[];
|
||||
logs?: string[];
|
||||
askUser?: string[];
|
||||
};
|
||||
```
|
||||
|
||||
### 5.2 规则
|
||||
|
||||
```text
|
||||
worker 只能读取 inputTags 声明的标签（含前缀规则）。
|
||||
worker 只能输出 outputTags 声明的标签。
|
||||
worker 不读取全量黑板。
|
||||
LLM 不决定自己能看什么。
|
||||
Runtime 校验 outputs 的 tag ⊆ outputTags。
|
||||
```
|
||||
|
||||
### 5.3 Worker Skill 落盘
|
||||
|
||||
见 `docs/worker-skill-format.md`。正文写「怎么做」；`inputTags` / `outputTags` 写在 frontmatter。
|
||||
|
||||
### 5.4 ask_user
|
||||
|
||||
提问是 worker **能力**，不是独立 worker。中途提问时 `resumeContext` 保存 workerId，**不**保存 inputTags（恢复时仍从 Worker Skill 读 inputTags）。
|
||||
|
||||
---
|
||||
|
||||
## 7. 总管（Main Agent）
|
||||
|
||||
总管只负责流程推进。
|
||||
|
||||
### 6.1 职责
|
||||
|
||||
```text
|
||||
判断当前任务属于哪种 skill / 业务阶段
|
||||
选择下一个 worker（run_worker）
|
||||
判断是否需要追问用户（ask_user）
|
||||
判断是否需要用户确认下一步（requiresApproval）
|
||||
判断是否 finish
|
||||
```
|
||||
|
||||
### 6.2 不负责
|
||||
|
||||
```text
|
||||
不决定某条信息给谁看
|
||||
不手动拼接 worker 上下文
|
||||
不让 LLM 判断信息权限
|
||||
不把全量黑板交给 worker
|
||||
不在 run_worker 里指定 inputTags / outputTags
|
||||
```
|
||||
|
||||
### 6.3 决策结构
|
||||
|
||||
```ts
|
||||
type MainAgentDecision = {
|
||||
id: string;
|
||||
action: "ask_user" | "run_worker" | "create_temp_worker" | "review_blackboard" | "finish";
|
||||
reason: string;
|
||||
workerId?: string;
|
||||
requiresApproval: boolean;
|
||||
statePatchAllowed: false;
|
||||
};
|
||||
```
|
||||
|
||||
执行链：
|
||||
|
||||
```text
|
||||
总管选择 worker
|
||||
→ Runtime 读取该 worker 的 inputTags
|
||||
→ 从黑板取匹配条目，组装 WorkerContext
|
||||
→ 调用 worker
|
||||
→ worker 输出固定 outputTags
|
||||
→ 写回黑板
|
||||
→ 按 acceptanceMode 验收
|
||||
```
|
||||
|
||||
Tool 合约见 `docs/tool-contracts.md`。
|
||||
|
||||
---
|
||||
|
||||
## 8. Skill 包与 manifest
|
||||
|
||||
Skill 包 = `orchestrator.md`（manifest）+ `workers/*/SKILL.md`。详见 `orchestrator-skill-format.md`。
|
||||
|
||||
manifest 包含：
|
||||
|
||||
```text
|
||||
Skill 注册表（instantiate + run）
|
||||
验收策略
|
||||
Instance Ready 规则
|
||||
```
|
||||
|
||||
**不写** 逐步编排表。inputTags / contextSegments 在 Worker SKILL.md。
|
||||
|
||||
### 8.1 已启用包
|
||||
|
||||
| 包 | 说明 |
|
||||
|---|---|
|
||||
| `novel/basic` | 演示：需求 → 大纲 |
|
||||
| `novel/weird-rules-short` | 规则怪谈：写 + 双验收 |
|
||||
|
||||
### 8.2 规划包（见 `skills/README.md`）
|
||||
|
||||
| 包 | 说明 |
|
||||
|---|---|
|
||||
| `novel/quick-write` | **简易档**：几乎无 tag 路由，上下文全量给 LLM |
|
||||
| `novel/interactive-novel` | 长篇 / 写作助手：instantiate + 多轮 run |
|
||||
| `novel/novel-standard` | 标准流水线（或与 interactive 合并） |
|
||||
| `dialogue/scene-roleplay` | 场景扮演（含角色设定 instantiate + 互动 run） |
|
||||
|
||||
---
|
||||
|
||||
## 9. 各模式核心 tag（参考）
|
||||
|
||||
实现 skill 时从下列词汇出发，不必一次全部实现。
|
||||
|
||||
### 8.1 简易小说（quick-write）
|
||||
|
||||
极简；可大量依赖 session + 全量上下文，tag 仅作交付锚点：
|
||||
|
||||
```text
|
||||
用户.输入
|
||||
需求.摘要
|
||||
正文.草稿
|
||||
正文.确认稿
|
||||
```
|
||||
|
||||
### 8.2 结构化短篇（如 weird-rules-short）
|
||||
|
||||
迁移目标示例（与现 key 对照实施）：
|
||||
|
||||
```text
|
||||
需求.核心要点 ← book.brief
|
||||
核心.危险.隐藏 ← core.danger
|
||||
规则.草稿 ← rules.draft
|
||||
规则.说明.草稿 ← rules.commentary
|
||||
验收.读者视角.记录 ← review.infer.notes
|
||||
验收.作者视角.记录 ← review.author.notes
|
||||
```
|
||||
|
||||
### 8.3 交互式长篇
|
||||
|
||||
```text
|
||||
用户.原始输入 | 用户.意图转述 | 用户.确认结果
|
||||
项目.设定 | 项目.风格要求
|
||||
大纲.当前 | 大纲.候选修改 | 大纲.确认稿
|
||||
事件.当前 | 事件.确认稿
|
||||
正文.原文 | 正文.续写锚点 | 正文.草稿 | 正文.确认稿
|
||||
记忆.长期摘要 | 记忆.确认稿
|
||||
```
|
||||
|
||||
### 8.4 场景扮演
|
||||
|
||||
```text
|
||||
用户.行动输入 | 用户.行动意图
|
||||
世界.规则 | 世界.当前状态 | 世界.隐藏状态
|
||||
场景.可见信息 | 场景.隐藏信息
|
||||
角色.{id}.记忆 | 信念 | 行动.候选 | 台词.候选
|
||||
行动.裁决结果
|
||||
输出.场景反馈
|
||||
更新.世界状态 | 更新.角色状态
|
||||
```
|
||||
|
||||
### 8.5 角色卡
|
||||
|
||||
撰写：`角色卡.草稿` → `角色卡.确认稿`
|
||||
游玩：读 `角色卡.确认稿` + `用户.控制模式` + `NPC.*`
|
||||
|
||||
---
|
||||
|
||||
## 10. 正文 worker 与角色候选
|
||||
|
||||
角色 worker 输出 `角色.*.台词.候选` 等，**不**直接进入正文事实。
|
||||
|
||||
正文 worker 读取候选 + 风格约束，输出 `正文.草稿`；用户确认后为 `正文.确认稿`。
|
||||
|
||||
```text
|
||||
角色候选 → 提供意图
|
||||
正文 worker → 文本化、风格化、叙事化
|
||||
正文.确认稿 → 最终发生与表达
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 可选增强
|
||||
|
||||
### 10.1 采用记录
|
||||
|
||||
```text
|
||||
tag: 采用.记录
|
||||
```
|
||||
|
||||
记录正文采用了哪些候选条目，避免未采用候选污染记忆。早期可省略，记忆 worker 只从 `正文.确认稿` 抽取。
|
||||
|
||||
### 10.2 真实性 / 置信度（metadata）
|
||||
|
||||
```ts
|
||||
type TruthMode =
|
||||
| "truth" | "belief" | "claim" | "lie" | "rumor" | "plan" | "unknown";
|
||||
```
|
||||
|
||||
不参与基础路由。
|
||||
|
||||
### 10.3 RAG
|
||||
|
||||
RAG 不替代黑板。检索结果也应写成 tag，例如 `角色.A.相关记忆摘要`，由 worker 通过 inputTags 读取。
|
||||
|
||||
---
|
||||
|
||||
## 12. 与阶段机的关系
|
||||
|
||||
运行相位、业务 stage、tag 阶段 **三者正交**（详见 §2.2）：
|
||||
|
||||
```text
|
||||
运行相位 系统在等什么（见 runtime-state-machine.md）
|
||||
业务 stage instantiate → run → done（orchestrator.md；brief 即 instantiate）
|
||||
tag 阶段 黑板条目 lifecycle（候选 / 草稿 / 确认稿）
|
||||
```
|
||||
|
||||
实例化阶段在运行相位上通常体现为 `waiting_user(input)`；进入 run stage 后为 `running` + worker 验收循环。
|
||||
阶段机 enum 不增加 `instantiate` 相位——业务 stage 由 orchestrator + tag 索引判断。
|
||||
|
||||
阶段机规则本身不因 tag 迁移而改变。变的是：黑板读写、worker 上下文、总管决策字段。
|
||||
|
||||
---
|
||||
|
||||
## 13. 与 Book 存储
|
||||
|
||||
Book 存长期实例；黑板存 **当前 Session** 的运行时 tag。实例化产物与 run 阶段确认稿可归档到 Book。
|
||||
详见 `docs/book-storage.md` 与 §2.7。
|
||||
|
||||
---
|
||||
|
||||
## 14. 实现原则（必须遵守）
|
||||
|
||||
```text
|
||||
1. worker 不读取全量黑板（quick-write 等显式声明全量 inputTags 的 skill 除外）。
|
||||
2. worker 只能读取 inputTags 声明的标签。
|
||||
3. worker 只能输出 outputTags 声明的标签。
|
||||
4. LLM 不决定上下文分发。
|
||||
5. 总管 run_worker 时不带 inputTags / outputTags。
|
||||
6. 标签是 worker 之间的接口。
|
||||
7. 候选不等于事实；草稿不等于确认稿。
|
||||
8. 正文 worker 可重写角色候选产物。
|
||||
9. 长期记忆优先从正文.确认稿 更新。
|
||||
10. 简单 skill 用简单 tag；复杂 skill 再增加对象与阶段段。
|
||||
11. 角色卡与设定在 instantiate 阶段写入 tag；跨 Session 复用走 Book 加载，不单独 author skill 包。
|
||||
12. 代码与旧文档冲突时，以本文为准改代码。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 15. 代码迁移顺序（参考）
|
||||
|
||||
```text
|
||||
1. src/types/blackboard.ts → BlackboardItem + listByTag / matchPrefix
|
||||
2. src/skills/types.ts + loader → 解析 inputTags / outputTags
|
||||
3. src/worker/executor.ts → 按 tag 组装 context，校验 outputTags
|
||||
4. src/types/runtime.ts + main-agent → 决策去掉 inputKeys / outputKeys
|
||||
5. skills/novel/weird-rules-short → 第一个 tag 化样板
|
||||
6. skills/novel/quick-write → 简易全量 LLM 档
|
||||
```
|
||||
|
||||
当前代码仍为旧 key 模型；实现前以本文为规格。
|
||||
|
||||
---
|
||||
|
||||
## 16. 相关文档
|
||||
|
||||
| 文档 | 内容 |
|
||||
|---|---|
|
||||
| `orchestrator-skill-format.md` | 总管 orchestrator.md 写法 |
|
||||
| `worker-skill-format.md` | Worker SKILL.md 写法 |
|
||||
| `tool-contracts.md` | 总管 / worker tool |
|
||||
| `skill-format.md` | Skill 包存储 |
|
||||
| `runtime-state-machine.md` | 5 相位阶段机 |
|
||||
| `implementation-guide.md` | 写代码顺序 |
|
||||
| `skills/README.md` | Skill 包索引与 TODO |
|
||||
## 4. 相关
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| `creation-playbook.md` | 创作 / 游玩流 |
|
||||
| `worker-skill-format.md` | 声明驱动 |
|
||||
| `context-assembly.md` | 上下文拼接 |
|
||||
| `run-snapshot.md` | 存档 |
|
||||
|
||||
@@ -37,7 +37,7 @@ LLM 通过 **tool call** 表达意图；Runtime 校验后执行 tool 或转为 *
|
||||
| name | 行为 |
|
||||
|------|------|
|
||||
| `run_worker` | 执行 skill；`requiresApproval` → `approve_step` |
|
||||
| `ask_user` | `waiting_user(input)` |
|
||||
| `ask_user` | `waiting_user(input)`；`assessment` → 内容评价（主内容）；`questions` → 挂载询问卡（可 Skip） |
|
||||
| `review_blackboard` | 向用户展示概况 → `input` |
|
||||
| `finish` | `done` |
|
||||
|
||||
@@ -72,7 +72,7 @@ running 内每轮 LLM+tool 使 burst+1；超过 maxBurst（默认 12，可配置
|
||||
|
||||
| name | 行为 |
|
||||
|------|------|
|
||||
| `ask_user` | `worker_questions` + resumeContext |
|
||||
| `ask_user` | 无产物 → `worker_questions`；有产物 → 仍 `worker_completed`，追问挂到 `review_artifact.questions`（可直接 Accept） |
|
||||
| `submit` | 校验 tag ⊆ outputTags → 写黑板 → `worker_completed` |
|
||||
|
||||
Phase A 仍用 JSON `outputs` + `askUser`，语义等价。
|
||||
@@ -83,11 +83,11 @@ Phase A 仍用 JSON `outputs` + `askUser`，语义等价。
|
||||
|
||||
| waitingReason | 用户动作 |
|
||||
|---------------|----------|
|
||||
| `skill_selection` | 选包 |
|
||||
| `skill_selection` | 选包（**legacy**，新作品不再进入） |
|
||||
| `intake` / `input` | 输入 |
|
||||
| `approve_step` | approve / reject |
|
||||
| `review_artifact` | accept / reject |
|
||||
| `worker_questions` | 输入 |
|
||||
| `review_artifact` | accept / reject；可选 `questions` 随 Accept 一并收起（表示无需再完善） |
|
||||
| `worker_questions` | 作答 / Skip（无产物时的阻塞追问） |
|
||||
| `revision` | 输入修改说明 |
|
||||
|
||||
---
|
||||
|
||||
452
docs/ui-design.md
Normal file
452
docs/ui-design.md
Normal file
@@ -0,0 +1,452 @@
|
||||
# Web UI 心流设计
|
||||
|
||||
## 1. 定位
|
||||
|
||||
Writing Agent 的 Web 界面是 **全屏创作工作台**，不是即时通讯客户端。
|
||||
|
||||
**用户可见文案**（阶段名、Worker 名、气泡标题）须服从 **`ui-glossary.md`**：内部仍用 `design` / `design-core` 等 id，界面映射为「创作」「创作 · 核心」等中文。实现见 `src/server/display-labels.ts` 与 `web/display-labels.js`。
|
||||
|
||||
| 层 | 角色 |
|
||||
|----|------|
|
||||
| **工作面（working surface）** | 主舞台：用户此刻要看、要改、要验收的对象 |
|
||||
| **协调层（coordination）** | 对话与确认：说明意图、回答问题、触发下一步 |
|
||||
| **项目轨（project rail）** | 低频：作品切换、快照、模式切换 |
|
||||
| **系统态（ambient）** | 后台：Agent 执行、调度日志，默认不抢视线 |
|
||||
|
||||
**对话是手段，产物与叙事是目的。** 聊天气泡适合承载协调叙事，不适合承载长规格全文或沉浸式阅读。
|
||||
|
||||
主场景是 **全屏浏览器、长会话（1–2 小时）**，布局应稳定、可预期，而非频繁切 Tab 或在三块等权面板间跳视线。
|
||||
|
||||
相关代码：`web/index.html`、`web/app.js`、`web/agent-ui.js`、`web/styles.css`；视图模型 `src/server/agent-view.ts`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 两种业务阶段 = 两种主布局
|
||||
|
||||
`lifecycleStage`（`design` / `play`）切换时，**主舞台内容应变形**，壳子（顶栏、底栏、左轨）保持同一套肌肉记忆。
|
||||
|
||||
### 2.1 创作 `design` — 规格工作台
|
||||
|
||||
用户在定义世界、验收 Worker 集、选定开局；核心是 **结构化产物**（JSON 规格、表格、规格卡）。
|
||||
|
||||
```text
|
||||
主视线：正在成形 / 正在审阅的产物
|
||||
辅视线：协调对话（窄列或底栏上方的摘要条）
|
||||
冷信息：项目轨、快照、设计进度
|
||||
```
|
||||
|
||||
典型路径：
|
||||
|
||||
```text
|
||||
描述意图 → 主区草稿成形 → 回答追问（表单） → 验收全文 → Accept
|
||||
↑ 主舞台 ↑ 检查器 ↑ 绑在产物上
|
||||
```
|
||||
|
||||
**心流标杆（组合参考）**：Notion（结构化编辑）+ GitHub PR（版本验收）+ NotebookLM（零散想法 → 结构化草稿）。
|
||||
|
||||
### 2.2 游玩 `play` — 叙事驾驶舱
|
||||
|
||||
用户代入角色、推进回合；核心是 **叙事流 + 世界状态**。
|
||||
|
||||
```text
|
||||
主视线：回合输出（阅读优先，视野占比 70%+）
|
||||
辅视线：底部命令输入（短、快、位置固定）
|
||||
冷信息：角色/世界状态抽屉、多 run 存档
|
||||
```
|
||||
|
||||
典型路径：
|
||||
|
||||
```text
|
||||
读回合输出 → 输入行动 → 等生成 → 继续读
|
||||
↑ 主舞台 ↑ 固定底栏
|
||||
```
|
||||
|
||||
**心流标杆**：SillyTavern / 视觉小说阅读器（沉浸叙事）+ Roguelike 存档抽屉（同一开局多条 run）。
|
||||
|
||||
`world-simulator` 包说明见 `skills/dialogue/world-simulator/README.md`；流程概念见 `creation-playbook.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 全屏网页约束
|
||||
|
||||
与手机 IM（如 QQ）不同，全屏 Web 有以下硬约束：
|
||||
|
||||
| 约束 | 设计含义 |
|
||||
|------|----------|
|
||||
| **视口宽** | 可横向分栏：工作面 55–65% + 协调区 35–45%，不必单列堆叠 |
|
||||
| **会话长** | 底栏输入/确认位置永远不变；减少布局跳动 |
|
||||
| **产物大** | Worker 集、开场白等长文进工作面，不进聊天气泡 |
|
||||
| **双模式** | 同一壳子、两种主画布，不靠一套气泡布局打天下 |
|
||||
|
||||
QQ 等 IM 仅保留一条可借鉴点：**底栏作为唯一行动锚点**。其余按工作台设计。
|
||||
|
||||
---
|
||||
|
||||
## 4. 壳子布局（Figma 式分区）
|
||||
|
||||
全屏下的推荐骨架：
|
||||
|
||||
```text
|
||||
┌────┬──────────────────────────────┬────────────┐
|
||||
│项目│ 主画布（随 stage 变） │ 检查器 │
|
||||
│轨 │ │（按需展开） │
|
||||
│窄 │ design: 规格 / 表格 / 验收 │ │
|
||||
│ │ play: 叙事流 │ │
|
||||
└────┴──────────────────────────────┴────────────┘
|
||||
│ 命令栏（composer，固定） │
|
||||
└──────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
| 区域 | 职责 | 频率 |
|
||||
|------|------|------|
|
||||
| **左轨** | 作品列表、路径、快照入口 | 低 |
|
||||
| **顶栏** | 作品名、创作/游玩切换、状态 pill、`waitingReason` 摘要 | 常瞥 |
|
||||
| **主画布** | 当前任务的工作面 | 主视线 |
|
||||
| **检查器** | 产物元数据、验收按钮、进度、可编辑表格 | 按需 |
|
||||
| **命令栏** | 输入、发送、主确认（与检查器不重复） | 手常驻 |
|
||||
|
||||
检查器默认 **收起**；有产物验收、结构化填空、开局 swipe 等任务时 **滑出**（推开主画布，窄屏用全屏 drawer）。不是常驻 300px Agent 监控台。
|
||||
|
||||
---
|
||||
|
||||
## 5. 参考产品（按心流相似度）
|
||||
|
||||
| 产品 | 借鉴什么 | 对应本项目的阶段 |
|
||||
|------|----------|------------------|
|
||||
| **Cursor `AskQuestion`** | 独立询问卡、字母点选、分页、Skip/Continue、键盘捷径；聊天只留索引 | `worker_questions`（§8；选项可编辑为我们的增强） |
|
||||
| **ChatGPT 澄清问法** | 题干短、选项 = 完整可采纳句；一次收齐再继续 | 发问侧文案与批大小 |
|
||||
| **Claude Artifacts / ChatGPT Canvas** | 产物占主视区，对话收窄为协调 | `review_artifact`、Worker 集验收；询问卡放置 |
|
||||
| **GitHub Pull Request** | 被审对象为主舞台；讨论为时间线；Merge/Request changes 绑在对象上 | Accept、variant 切换、重 roll |
|
||||
| **Notion / Coda** | 文档/数据库是「家」；AI 辅助不抢主位 | `intake`、变量 schema、Worker 分工 |
|
||||
| **Figma** | 主画布 + 窄轨 + 按需检查器 | 全屏壳子结构 |
|
||||
| **SillyTavern / AI Dungeon** | 叙事占满视野；侧栏可收 | `play` 回合阅读 |
|
||||
| **NotebookLM** | 多源 → 中间协调 → 右侧成型笔记 | 创作开头 intake、草稿预览 |
|
||||
| **Linear** | 状态一眼可见、操作路径短、装饰极少 | 顶栏状态、长按效率 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 四条统一原则
|
||||
|
||||
跨 `design` / `play` 均遵守：
|
||||
|
||||
| 原则 | 含义 | 反面 |
|
||||
|------|------|------|
|
||||
| **一屏一事** | 同一时刻只有一个主任务（审产物 / 答提问 / 读叙事） | 右侧同时堆历史 + 验收 + 进度 + Agent focus |
|
||||
| **行动点唯一** | Accept、发送、swipe 只在一处出现 | composer 与检查器各放一套接受按钮 |
|
||||
| **对话是索引** | 气泡放摘要 + 跳转；全文在工作面 | Worker 长产出塞进中间气泡 |
|
||||
| **底栏锚定** | 输入/确认永远在底部同一区域 | 底栏在纯按钮与 textarea 间大幅换位 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 消息与面板的职责切分
|
||||
|
||||
### 7.1 中间协调区（当前 `message-feed`）
|
||||
|
||||
**应展示：**
|
||||
|
||||
- 用户输入
|
||||
- Worker 提问的 **一行索引**（「提问中 · 1/3」）；题干与选项在询问卡（§8）
|
||||
- 简短结论、错误提示
|
||||
- 流式 pending（执行中摘要）
|
||||
- 长产物的 **摘要 +「已在检查器打开」** 链接
|
||||
|
||||
**不应展示：**
|
||||
|
||||
- `agent_tool`、`orchestrator_decision`、`worker_running`（已在 `FEED_HIDDEN_KINDS`）
|
||||
- 验收中的产物全文（`review_artifact` 时隐藏 `worker_output`）
|
||||
- intake 完整表格（仅进度摘要）
|
||||
- `worker_questions` 的完整选项列表（进 §8 询问卡）
|
||||
|
||||
实现：`web/agent-ui.js` 中 `shouldShowInFeed`、`FEED_HIDDEN_KINDS`。
|
||||
|
||||
### 7.2 检查器（目标态；当前部分在 `panel-agent`）
|
||||
|
||||
**应承载：**
|
||||
|
||||
- 产物预览 / 编辑 / diff
|
||||
- intake 结构化表单
|
||||
- `worker_questions` 的备选容器（主路径见 §8 询问卡）
|
||||
- 开局 swipe 卡片栈
|
||||
- 设计进度（Worker 集卡片、步骤）
|
||||
- **固定上下文（独立区）**：纲领 / 常驻 / 黑板 tag 与 Worker 解耦；每张卡标明 **塞进哪些 Worker**（注入正文 / 常驻挂载 / 读入黑板）
|
||||
- **上下文 / 黑板**（终产物 tag、定稿摘要、归档计数）
|
||||
- 验收主按钮（接受 / 不接受；创作：删本单位交互消息只留产物；run：压缩过程 tag）
|
||||
|
||||
Worker 卡不再嵌套完整 tag 列表，只显示「上下文」摘要；完整挂载关系见上方固定上下文区。
|
||||
|
||||
**应降级折叠：**
|
||||
|
||||
- Agent focus、tool trace
|
||||
- 调度时间线（现「历史」Tab）→ 高级 / 调试模式
|
||||
|
||||
### 7.3 命令栏（`composer`）
|
||||
|
||||
由 `resolveComposer`（`web/app.js`）按 `phase` + `waitingReason` 变形，但位置不变：
|
||||
|
||||
| 态 | 表现 |
|
||||
|----|------|
|
||||
| `running` | 轻量状态 + 允许预输入草稿 |
|
||||
| `approve` / `accept` | 主按钮在底栏；hint 一行 |
|
||||
| `review_artifact` | 底栏：输入并发送＝改产物；旁挂「接受目前产物」。产物卡上不放接受钮 |
|
||||
| `intake` / `input` | textarea + 发送 |
|
||||
| `worker_questions` | **不抢主交互**；主回答在询问卡内（见 §8） |
|
||||
|
||||
---
|
||||
|
||||
## 8. 结构化询问卡（Questions Card）
|
||||
|
||||
`worker_questions` / `ask_user` 的 **首选交互**。壳子与键盘心流对齐 **Cursor `AskQuestion`**；选项语义与文案改写对齐 **ChatGPT / Claude 的「选项 = 可执行草稿」**；放置原则对齐 **Artifacts / Canvas「决策面 ≠ 聊天气泡」**。
|
||||
|
||||
### 8.0 业内标杆：借鉴什么、刻意改进什么
|
||||
|
||||
| 产品 / 模式 | 借鉴（照抄心流） | 不照抄 / 我们的改进 |
|
||||
|-------------|------------------|---------------------|
|
||||
| **Cursor `AskQuestion`** | 独立询问卡（非气泡堆选项）；`A/B/C` 字母点选；`n of N` 分页；底部 **Skip + Continue**；Enter / Esc；聊天流只留「在答」索引 | Cursor 选项多为**只读**，改细节只能塞底部通用备注 → 我们默认**选项文案可改写**，点文案编辑、点字母选中（社区对 Cursor 的高频诉求，见 AskQuestion inline-edit 讨论） |
|
||||
| **ChatGPT** | 澄清问法：题干短、选项是完整可采纳句；多题一次收齐再继续；自由补充不抢主路径 | 不用纯聊天气泡做多选题主交互；长选项不进 feed |
|
||||
| **Claude Artifacts / ChatGPT Canvas** | 「结构化决策 / 产物」与对话分离：卡/面板是工作面，聊天是协调 | 询问卡不是 Artifact 全文，而是短决策面；验收长产物仍走检查器 |
|
||||
| **Linear / GitHub PR 决策** | 一屏一事、主按钮唯一、状态一眼可见 | 不引入 Issue 式侧栏评论串 |
|
||||
|
||||
**产品结论（写死）：**
|
||||
|
||||
1. **主路径 = Cursor 式询问卡**（字母选中 + Continue），不是 QQ/ChatGPT 气泡里的长问答。
|
||||
2. **选项 = 可编辑草稿**（相对 Cursor 默认只读的增强）：多数一点即答；不满意就改文案再选，不必另开 Other。
|
||||
3. **对话流只索引**：「提问中 · 1/3」；题干与选项只在卡上。
|
||||
4. **命令栏降级**：本态不当主输入；可选「自由补充」兜底，语义从属于卡上 Continue。
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ ? Questions ▲ ▼ 1 of 3 │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ 1. Q1: 问题正文…… │
|
||||
│ [A] 选项文案（可编辑） ← 点文案 = 改写 │
|
||||
│ [B] 选项文案… ← 点字母 = 选中 │
|
||||
│ [C] 选项文案… │
|
||||
│ [+] Other… [_________] │
|
||||
│ │
|
||||
│ 2. Q2: …… │
|
||||
│ … │
|
||||
├─────────────────────────────────────────────┤
|
||||
│ Skip Esc [ Continue ↵ ]│
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**最关键交互：选项默认可改写；点选项文案是编辑，点字母按钮才是选中。**
|
||||
Agent 给的选项是「可编辑草稿」，不是只读单选列表。
|
||||
|
||||
### 8.1 为什么适合本产品
|
||||
|
||||
| 特质 | 对用户心流的作用 | 业内对应 |
|
||||
|------|------------------|----------|
|
||||
| **点选优先，改写兜底** | 多数情况一点字母即答；不满意就改文案再选，不必另开 Other | Cursor 点选 + ChatGPT「改一句再说」 |
|
||||
| **选项即可执行语义** | 提交的是用户确认（或改写后）的完整句子，可直接喂给 worker | ChatGPT / Claude 澄清选项写法 |
|
||||
| **编辑与选中分离** | 避免「想改一下措辞」却误触提交路径；符合「一屏一事」 | 相对 Cursor 只读选项的增强 |
|
||||
| **分页批次** | 「1 of 3」管理预期；单屏别堆太多题 | Cursor `AskQuestion` |
|
||||
| **键盘捷径** | Enter = Continue，Esc = Skip；字母键可选中（可选增强） | Cursor / IDE 习惯 |
|
||||
| **模态焦点** | 当前这一批问清了再 Continue | Cursor 卡内提交；非边聊边答 |
|
||||
|
||||
适用：`design` 里 intake 追问、规格确认；`play` 里「局面 + 可选行动」；凡原先要用户在 composer 里写长段回答的提问，优先改成卡。
|
||||
|
||||
### 8.2 放置
|
||||
|
||||
| 区域 | 职责 | 业内对应 |
|
||||
|------|------|----------|
|
||||
| **主画布消息流下方（推荐）** | 询问卡嵌在协调列底部（composer 之上），宽度随列自适应，不遮盖历史消息 | 决策面与对话分离，但占文档流而非浮层 |
|
||||
| **检查器** | 备选：与产物并排时，卡可嵌在检查器顶部；长产物场景优先主画布居中卡 | Canvas / 侧栏表单 |
|
||||
| **中间气泡** | 只留一行索引：「Worker 提问中 · 1/3」；点开回到卡 | Cursor：聊天不堆完整选项列表 |
|
||||
| **命令栏** | 降级：本态不当主输入；仅作兜底自由补充（可选） | Cursor 底部「optional details」——我们刻意弱化，主语义在选项改写 |
|
||||
|
||||
Continue 提交后：卡收起 → 系统 `running` → 回复摘要进对话流（摘要用**用户最终确认的文案**，含改写）。
|
||||
|
||||
### 8.3 卡片结构与命中区
|
||||
|
||||
| 元件 | 规则 | 对齐 |
|
||||
|------|------|------|
|
||||
| **Header** | 标题「Questions」+ 批次 `n of N` + 上下翻批 | Cursor |
|
||||
| **题干** | 编号 `1.`；一句说清决策点；避免在选项里复述背景 | ChatGPT 澄清问法 |
|
||||
| **字母按钮 `[A]`…** | **唯一「选中」命中区**；选中后该行高亮；同题单选 | Cursor |
|
||||
| **选项文案区** | **默认可编辑**；点击文案（或已聚焦时）进入改写，**不触发选中** | 相对 Cursor 的增强（社区诉求） |
|
||||
| **Other…** | 每题末可选；短输入；与改写选项二选一语义相同——都是「自拟答案」 | Cursor Other + ChatGPT 自由答 |
|
||||
| **Skip** | 本批可跳过（Esc）；下游需能处理「未答」 | Cursor |
|
||||
| **Continue** | 主按钮（Enter）；校验必选题已有选中项（提交的是该选项当前文案） | Cursor |
|
||||
|
||||
#### 8.3.1 编辑 vs 选中（强制）
|
||||
|
||||
```text
|
||||
一行选项 = [字母按钮] + [文案区域]
|
||||
|
||||
点 [A] → 选中 A（提交候选变为 A 的当前文案）
|
||||
点 文案区 → 进入编辑；改写本地草稿；不改变选中态
|
||||
（若尚未选中，可编辑完再点字母选中；
|
||||
若已选中 A 又改了文案，提交仍用改写后的 A）
|
||||
```
|
||||
|
||||
细则：
|
||||
|
||||
1. **默认所有选项文案可改**（含 Agent 预填的 A/B/C）；不是「只能选、想改去 Other」（Cursor 现状的痛点，我们默认解掉）。
|
||||
2. **点文案 ≠ 选中**。禁止「点整行即选中」的常见单选实现。
|
||||
3. **只有字母按钮（或等价：键盘 A/B/C）负责选中**。
|
||||
4. 编辑中：Enter 可结束编辑并保持焦点在卡内；勿与 Continue 的 Enter 冲突（编辑态下 Enter = 收起编辑）。
|
||||
5. 提交 payload 必须带上 **最终文案**（`label` / `text`），不能只交 `optionId`——否则改写丢失（ChatGPT/Cursor 都要求「用户说了什么」完整回传）。
|
||||
6. Other 与「改写某选项」并存：Other 是空槽自拟；改写是在 Agent 草稿上微调。二者都合法。
|
||||
|
||||
多批：Continue 先推进当前页，再进下一批；**全部页完成后再**统一提交并解除 `waiting_user`（对齐 Cursor 一批问清再继续）。
|
||||
|
||||
### 8.4 与 runtime 的契约
|
||||
|
||||
`askUser` / `ask_user` 已支持结构化 `QuestionItem[]`（兼容旧 `string[]`）。提交走 `POST /api/sessions/:id/answers`：
|
||||
|
||||
```ts
|
||||
{
|
||||
answers: [
|
||||
{ questionId: "q1", optionId: "A", text: "（用户看到的/改写后的完整句）" },
|
||||
{ questionId: "q2", optionId: "other", text: "…" },
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
前端：主画布消息流下方询问卡（点字母选中、点文案编辑、分页 Continue）；气泡可只显示答句，发给 AI 仍含问+答。
|
||||
|
||||
Worker / Agent 发问侧（对齐 Cursor AskQuestion：询问不阻断主产出）：
|
||||
|
||||
- 总管 `ask_user`：**assessment 是主内容**；`questions` 挂在其下，用户可 Skip 并请总管基于现有信息继续。
|
||||
- Worker：优先 `outputs` + `askUser` 同时给出；有产物时追问挂在验收态下，用户可直接「接受目前产物」而不作答。仅完全无法产出时才阻塞提问。
|
||||
- 能推断选项时 **必须** 给 `options`；每项写成用户可直接采用或微调的**建议示范**（可含短场景钩子），禁止空泛「是 / 否」。
|
||||
- `editable` 默认 `true`；挂载题 `required` 默认 `false`。
|
||||
- 单批题量控制在 Cursor 舒适区：**默认每页 1 题（左右切换），整批不宜超过 5 题**；更细的拆到下一轮 `ask_user`。
|
||||
|
||||
过渡期：仅有 `string[]` 时，UI 将每题渲染为题干 + Other。询问卡首屏可展示 `waitingReason.message` 中的内容评价。
|
||||
|
||||
实现：`web/questions-ui.js`、`web/styles.css`（`.qcard*`）、`web/agent-ui.js` 索引气泡。
|
||||
|
||||
### 8.5 反模式
|
||||
|
||||
- 点整行 / 点文案就选中（应点字母才选中）— 违反 Cursor 式命中区
|
||||
- 选项只读、想改只能走 Other 或底栏备注（Cursor 痛点，禁止照抄）
|
||||
- 提交只带 `optionId`、丢掉用户改写后的 `text`（业内答案回传完整性要求）
|
||||
- 把 5+ 道长选项塞进一条聊天气泡（ChatGPT/Cursor 都已证明劣于独立卡）
|
||||
- 选项写「是 / 否」却题干含糊
|
||||
- Continue 与底栏「发送」并存且语义不同
|
||||
- 无 Skip/必答标记，用户卡死无法继续
|
||||
- 编辑态下 Enter 误触 Continue 整卡提交
|
||||
|
||||
---
|
||||
|
||||
## 9. `waitingReason` × `lifecycleStage` 显示规格
|
||||
|
||||
目标态 UI 分配表（实现时对照 `agent-view` 的 `buildFocus` 与 `actions`）。
|
||||
|
||||
| waitingReason / phase | design 主画布 | play 主画布 | 检查器 | 命令栏 | 顶栏状态 |
|
||||
|------------------------|---------------|-------------|--------|--------|----------|
|
||||
| `idle` / 未打开作品 | 空状态引导 | — | 关 | 禁用 | — |
|
||||
| `intake` | 空或首条引导文案 | — | intake 表单（有字段时展开） | 描述需求 + 发送；必要项满则确认 | 描述创作需求 |
|
||||
| `input`（首句） | 协调摘要 | 叙事历史 | 关 | 发送 | 描述 / 补充 |
|
||||
| `input`（补充） | 协调摘要 | 叙事历史 | 关 | 发送 | 补充说明 |
|
||||
| `running` | 流式 pending | 流式 pending | 关 | 等待态（可预输入） | Agent/Skill 执行中 |
|
||||
| `worker_questions` | **询问卡（§8）** + 一行索引气泡 | 同左；行动题尤其用选项 | 可选副展示 | 降级；可 Skip | 回答提问 |
|
||||
| `approve_step` | 决策摘要 | 决策摘要 | 可选：待 invoke 说明 | 确认 / 暂不 / 说明意见 | 建议 invoke |
|
||||
| `review_artifact` | 「请验收」摘要；若有挂载题则询问卡可选（**Accept 即收起**） | 同左 | **产物全文 + 接受/不接受** | 修改意见（可选）；接受 = 无需再完善 | 验收产物 |
|
||||
| `revision` | 修改说明上下文 | 同左 | 相关产物 | 按 instruction 输入 | 修订中 |
|
||||
| opening swipe（业务） | 卡片栈主舞台 | — | 版本 nav + 锁定 | 选定 / 换一版 | 选定开局 |
|
||||
| `done` | 阶段结束摘要 | 会话结束 | 关 | 空闲提示 | 已完成 |
|
||||
|
||||
`skill_selection` 为遗留恢复态，UI 引导用户发消息继续即可。
|
||||
|
||||
---
|
||||
|
||||
## 10. 阶段心流图
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph shell [固定壳子]
|
||||
Rail[左轨 · 作品]
|
||||
Top[顶栏 · 模式与状态]
|
||||
Cmd[底栏 · 命令栏]
|
||||
end
|
||||
|
||||
subgraph design [design 主画布]
|
||||
Spec[规格 / 表格 / 验收]
|
||||
CoordD[协调摘要]
|
||||
QCardD[询问卡 · worker_questions]
|
||||
end
|
||||
|
||||
subgraph play [play 主画布]
|
||||
Narr[叙事流]
|
||||
CoordP[回合摘要]
|
||||
QCardP[询问卡 · 行动选择]
|
||||
end
|
||||
|
||||
subgraph inspector [检查器 · 按需]
|
||||
Artifact[产物 / 表单]
|
||||
Progress[设计进度]
|
||||
Debug[调度日志 · 折叠]
|
||||
end
|
||||
|
||||
Rail --> Spec
|
||||
Rail --> Narr
|
||||
Top --> Spec
|
||||
Top --> Narr
|
||||
Spec --> Cmd
|
||||
Narr --> Cmd
|
||||
Spec -.-> Artifact
|
||||
Narr -.-> Artifact
|
||||
CoordD --> Cmd
|
||||
CoordP --> Cmd
|
||||
QCardD -->|Continue| Cmd
|
||||
QCardP -->|Continue| Cmd
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 现状与目标差距
|
||||
|
||||
| 现状（`web/`） | 心流问题 | 目标 |
|
||||
|----------------|----------|------|
|
||||
| 右侧常驻 `panel-agent`（约 300px） | 空跑时也占视线 | 按需检查器，默认收起 |
|
||||
| focus / tool-trace 在右侧顶部 | 像 IDE 调试台 | 并入折叠日志或顶栏小状态 |
|
||||
| intake 可在 feed 与 composer 两处 | 信息重复 | 表格进检查器，feed 仅摘要 |
|
||||
| `worker_questions` = 文本列表 + composer | 用户写长段、选项语义易丢 | **§8 询问卡**：文案可改、点字母选中 |
|
||||
| `askUser: string[]` | 无 options / Other / 分页 | 升级 `QuestionItem` 协议 |
|
||||
| 验收时 composer 与「验收」Tab 均可操作 | 行动点分散 | 主按钮只在检查器 |
|
||||
| 移动端隐藏整个 `panel-agent` | 无产物面 | 全屏 drawer |
|
||||
| 主区标题写「agent-first」 | 与产品定位不符 | 创作 = 产物优先；游玩 = 叙事优先 |
|
||||
|
||||
已有正确方向（保持并强化）：
|
||||
|
||||
- SillyTavern 式气泡与左右对齐（`play` 适用）
|
||||
- `FEED_HIDDEN_KINDS` 分流内部消息
|
||||
- `review_artifact` 时产物不进 feed、自动切验收视图
|
||||
- 底栏 `composer` 按 `waitingReason` 变形
|
||||
|
||||
---
|
||||
|
||||
## 12. 实现备注
|
||||
|
||||
- 视图数据：`SessionView` / `buildAgentView`（`src/server/agent-view.ts`）已区分 `messages`、`reviewArtifact`、`waitingReason`、`actions`、`intake`；询问卡需扩展 questions 结构，见 §8.4。
|
||||
- 消息分类：`classifyAgentMessage`、`EnrichedMessage.kind` 驱动 feed 过滤；`worker_questions` 在 feed 仅留索引。
|
||||
- 生命周期：`inferLifecycleStage`、`body[data-lifecycle]`（`web/agent-ui.js`）控制 accent；可扩展为 **主画布布局切换**。
|
||||
- 验收：`renderReviewPanel` → 迁移为检查器主内容，与 composer 去重。
|
||||
- 设计进度：`renderSkillGuide` / `worker-set-user-panel` → 检查器内按需 Tab，非默认主视图。
|
||||
- 发问侧：`src/worker/executor.ts` 的 `askUser`、docs/`worker-skill-format.md` §ask_user → 支持带 `options` 的结构化问题。
|
||||
|
||||
改版时建议顺序：
|
||||
|
||||
1. 检查器按需展开 + 验收动作收敛
|
||||
2. **§8 询问卡 UI**（先兼容现有 `string[]`，再补 options 协议）
|
||||
3. design 主画布产物优先（收窄协调列）
|
||||
4. play 叙事区拉满 + 状态抽屉
|
||||
5. 调度日志降级为高级折叠
|
||||
6. 窄屏 drawer 与 opening swipe 专屏
|
||||
|
||||
---
|
||||
|
||||
## 13. 相关文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| `architecture.md` | 总览；UI 为 Session 的人机界面 |
|
||||
| `creation-playbook.md` | design → play 业务流程 |
|
||||
| `runtime-state-machine.md` | `waitingReason` 定义 |
|
||||
| `worker-skill-format.md` | `ask_user` / 提问侧契约 |
|
||||
| `run-snapshot.md` | 快照与分支；左轨/检查器入口 |
|
||||
| `implementation-guide.md` | `web/*` 文件职责 |
|
||||
| `book-storage.md` | 作品、存档、资产形态 |
|
||||
171
docs/ui-glossary.md
Normal file
171
docs/ui-glossary.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# 用户可见文案与术语对照（UI Glossary）
|
||||
|
||||
**用途**：凡出现在 Web 界面、导出 Markdown、状态 pill、气泡标题、询问卡、检查器上的文案，**禁止直接暴露**内部英文 id（如 `design-core`、`design`、`play`）。内部协议、SKILL 路径、黑板 tag、API 字段仍用英文 id。
|
||||
|
||||
**实现**：`src/server/display-labels.ts`（权威映射）；`web/display-labels.js` 须与本文及该文件保持一致。新增高频 id 时：**先改本文 → 再改代码**。
|
||||
|
||||
**产品隐喻**：用户侧统一用**拍摄**用语——**导演 / 剧本 / 演员 / 能力**。旧称「总管 / 能力包 / 配方 / Worker」仅作内部或过渡别称。
|
||||
|
||||
---
|
||||
|
||||
## 0. 拍摄术语（首选）
|
||||
|
||||
| 拍摄术语 | 用户可见含义 | 内部对应 | 勿再对用户说 |
|
||||
|----------|--------------|----------|--------------|
|
||||
| **导演** | ① 新建时**手动选一次**的方法起点（如世界模拟器、扩写助手），可按现场「调味」；② 会话里负责调度的 Agent | `recipes/` 选型 → 黑板 `创作.选用配方`；Main Agent / orchestrator | 配方、能力包（作第二层选项）、总管 |
|
||||
| **剧本** | 本局谈成的流程与规格（活的，不是死选单） | `设计.创作流程`、`设计.worker集` | 「剧本 Skill 菜单」、死板流程卡 |
|
||||
| **演员** | 上场执行的单元（一次 `run_worker`） | Worker / design-* / play workers | 对用户堆「Worker · id」；标题用中文名 |
|
||||
| **能力** | 共用工序模块（美学纲领与交互范式…）；导演从中选型编排 | `modules/` 组件池 | 组件池、模块（可作作者文档用词） |
|
||||
|
||||
```text
|
||||
用户选【导演】（世界模拟器 / 扩写助手 …）
|
||||
│
|
||||
▼
|
||||
【导演】调度 → 从【能力】里编排 → 谈成【剧本】
|
||||
│
|
||||
▼
|
||||
【演员】按剧本上场执行 → 游玩 / 成稿
|
||||
```
|
||||
|
||||
**一层选型**：新建作品只选**导演**，不要再叠「能力包 + 配方」两层。
|
||||
|
||||
**调味**：导演给出的建议步骤是**近期起点**；编排时可增量追加、可反复调用标了可反复的能力（像现场改戏），验收的是本局【剧本】，不是磁盘上的静态菜谱。
|
||||
|
||||
---
|
||||
|
||||
## 1. 原则
|
||||
|
||||
1. **内外分离**：id 给机器；中文给用户。
|
||||
2. **拍摄词优先**：对用户优先用 §0；技术文档可写「导演（Main Agent / recipe）」对照。
|
||||
3. **阶段用产品词**：lifecycle 的 `design` / `play` 用户侧统一为 **创作** / **游玩**（勿译成「设计模式 / 播放」）。
|
||||
4. **与 SKILL `name` 对齐**：磁盘 worker 若已有中文 `name`，展示优先用 name；本表是缺省与高频兜底。
|
||||
5. **气泡标题形态**：`{中文名}` 或 `{中文名} · {动作}`，例如「创作 · 流程编排 · 产出」，不要「Worker · design-flow 产出」。
|
||||
|
||||
---
|
||||
|
||||
## 2. 生命周期 / 阶段
|
||||
|
||||
| 内部 id / 词 | 用户可见 | 业界对照与选用说明 |
|
||||
|--------------|----------|-------------------|
|
||||
| `design` | **创作** | 谈【剧本】的工作台。不用「设计」作顶栏主词。 |
|
||||
| `play` | **游玩** | 【演员】按剧本上场。不用「播放」。 |
|
||||
| `done` | **已完成** | — |
|
||||
| `idle` | **待命** | — |
|
||||
| `running` | **执行中** | — |
|
||||
| `waiting_user` | **等待你** | — |
|
||||
|
||||
---
|
||||
|
||||
## 3. 角色与系统概念（对照表）
|
||||
|
||||
| 内部词 | 用户可见（首选） | 过渡别称 | 说明 |
|
||||
|--------|------------------|----------|------|
|
||||
| Agent / Main Agent / orchestrator | **导演** | 总管（旧） | 调度【演员】、推进【剧本】；气泡可用「导演 · 思考」。 |
|
||||
| Worker | **演员** | Worker / 执行单元 | UI 标题用中文名；检查器可写演员（Worker）。 |
|
||||
| Tool | **工具** | Tool | 导演 tool call；气泡可用「工具 · 读黑板」。 |
|
||||
| Skill pack / recipe（用户选型） | **导演**（选项名） | 能力包 / 配方（旧） | 新建下拉只出现导演选项（世界模拟器、扩写助手…）。 |
|
||||
| Module / modules pool | **能力** | 组件池（作者文档） | 美学纲领与交互范式等；见 `world-simulator-modules.md`。 |
|
||||
| Creation flow + Worker 集 | **剧本** | — | 动态谈成；非死选单。 |
|
||||
| Blackboard | **黑板** | 上下文板 | — |
|
||||
| Artifact | **产物** | — | 待验收输出。 |
|
||||
| Accept / Review | **验收** / **接受** | — | 按钮用「接受」；阶段说明用「验收」。 |
|
||||
| Intake | **需求描述** | 启动填空 | — |
|
||||
| Burst | **本轮调度** | — | 少对用户说 burst。 |
|
||||
| Questions card | **询问卡** | Questions | 详见 `ui-design.md` §8。 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 创作期磁盘 Worker（高频）
|
||||
|
||||
| 内部 id | 用户可见 | 备注 |
|
||||
|---------|----------|------|
|
||||
| `design-flow` | **创作 · 流程编排** | 以已选【导演】为起点，编排/增量修订可变 DAG → 写入剧本（创作流程） |
|
||||
| `design-step` | **创作 · 执行步骤** | 按剧本执行当前【能力】 |
|
||||
| `opening-generator` | **开局 · 开场白** | 创作末尾可选 |
|
||||
| `design-core` 等 | （已废弃） | 旧分步 skill；勿再调度 |
|
||||
|
||||
标题动作后缀（拼在中文名后）：
|
||||
|
||||
| 动作 | 后缀 |
|
||||
|------|------|
|
||||
| 运行中 | （可省略或「执行中」） |
|
||||
| 产出 / 已完成 | **· 产出** |
|
||||
| 提问 | **· 提问** |
|
||||
| 占位 | **· 占位** |
|
||||
|
||||
---
|
||||
|
||||
## 5. 游玩期常用演员（缺省）
|
||||
|
||||
声明里可覆盖；无中文名时用下表：
|
||||
|
||||
| 内部 id | 用户可见 |
|
||||
|---------|----------|
|
||||
| `narrator` | **叙事转述** |
|
||||
| `role-decide` | **角色决策** |
|
||||
| `world-simulator` | **世界推演** |
|
||||
| `round-present` | **回合呈现** |
|
||||
|
||||
导演选项展示名示例：`world-simulator`（recipe）→ **世界模拟器**；`expand-assistant` → **扩写助手**。
|
||||
|
||||
**创造演员时**：规格里另写 `name`（中文展示名）。`ref` 仍用英文 kebab；UI 优先 `name`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 创作单位 id（检查器 / 进度）
|
||||
|
||||
| 内部 id 形态 | 用户可见规则 | 示例 |
|
||||
|--------------|--------------|------|
|
||||
| `phase:core` | **单位 · 核心** | — |
|
||||
| `phase:refine` | **单位 · 细化** | — |
|
||||
| `worker:{ref}` | **演员 · {中文名或 ref}** | `worker:narrator` → 演员 · 叙事转述 |
|
||||
| `fixed:{topic}` | **能力 · {话题中文}** | `fixed:aesthetics-interaction` → 能力 · 美学纲领与交互范式 |
|
||||
| `resident:{id}` | **常驻 · {id 或名}** | — |
|
||||
|
||||
能力话题建议译名：
|
||||
|
||||
| topic | 用户可见 |
|
||||
|-------|----------|
|
||||
| `aesthetics-interaction` | 美学纲领与交互范式 |
|
||||
| `interaction` | 交互范式（旧；已并入上一行） |
|
||||
| `narrative_guide` | 叙事指南 |
|
||||
| `input_protocol` | 输入协议 |
|
||||
| `core_premise` | 核心前提 |
|
||||
| `aesthetics` | 美学纲领（旧；已并入美学纲领与交互范式） |
|
||||
|
||||
---
|
||||
|
||||
## 7. 等待态 / 焦点（对用户）
|
||||
|
||||
| `waitingReason.kind` | 状态摘要（短） | 焦点动作 |
|
||||
|----------------------|----------------|----------|
|
||||
| `intake` | 描述需求 | 描述创作需求 |
|
||||
| `input` | 补充说明 | 补充说明 / 回答追问 |
|
||||
| `worker_questions` | 回答提问 | 回答 · {中文演员名} |
|
||||
| `approve_step` | 确认执行 | 建议调用 {中文名} |
|
||||
| `review_artifact` | 验收产物 | 验收产物 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 禁止出现在用户主路径上的写法
|
||||
|
||||
- `Worker · design-core`、`run_worker(design-core)`
|
||||
- 顶栏 / pill 写 `design` / `play` 英文
|
||||
- 「总管会调度 design-core」（应写「导演会先谈剧本」或「将开始：创作 · 流程编排」）
|
||||
- 新建作品同时出现「导演 + 配方」两层选择
|
||||
- 询问卡标题直接写 `design-core`
|
||||
|
||||
技术日志、导出里的「调试附录」、开发者文档不受本条限制，但默认导出给用户的 Markdown 应走同一套映射。
|
||||
|
||||
---
|
||||
|
||||
## 9. 相关文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| `ui-design.md` | 布局与心流；文案须服从本文 |
|
||||
| `architecture.md` | 内部术语；用户侧以本文为准 |
|
||||
| `daily-use-p0.md` | 导演 / 剧本产品定义 |
|
||||
| `world-simulator-modules.md` | 【能力】与导演（recipes）作者清单 |
|
||||
| `creation-playbook.md` | 创作/游玩流程概念 |
|
||||
| `design-orchestrator-guide.md` | 创作方法（可继续写英文 id，面向作者） |
|
||||
@@ -1,279 +1,106 @@
|
||||
# Worker Skill 格式
|
||||
|
||||
## 1. 定位
|
||||
> **文档层级：Worker / 声明契约格式（非系统架构）。**
|
||||
> 上下文编译原则见 [`architecture.md`](./architecture.md)、[`context-assembly.md`](./context-assembly.md)。
|
||||
|
||||
**Worker Skill** 服务 **Worker Agent**：规定 **读哪些 tag、写哪些 tag、怎么做** 本阶段产出。
|
||||
## 1. 定位（现行：声明驱动）
|
||||
|
||||
Worker **从属于某一个总管 Skill 包**，不与其它 skill 共享。
|
||||
**默认包 `world-simulator`：**
|
||||
|
||||
```text
|
||||
总管：run_worker(write-rules)
|
||||
→ Runtime 读 workers/write-rules/SKILL.md 的 inputTags / outputTags
|
||||
→ 从黑板取匹配条目 → Worker 执行 → 写回 outputTags
|
||||
play 时执行契约 = accept 后的 设计.worker集 某条 workers[]（实例 Worker 声明）
|
||||
可选模板 = worker-templates/{ref}.yaml（design-intake 合并默认值）
|
||||
磁盘 SKILL.md = 仅创建阶段必要 worker（现：design-intake）
|
||||
```
|
||||
|
||||
规格背景见 `docs/tag-blackboard.md`、`docs/context-assembly.md`。
|
||||
总管 `run_worker(id)` → Runtime 校验 id ∈ Worker 声明 → 从 **Worker 集条目**（+ 可选模板合并）拼 prompt → 写声明的 `outputs`。
|
||||
|
||||
**不要**为每个 play ref 预置 `workers/narrator/SKILL.md`；实例差异写在 Worker 集里。
|
||||
|
||||
规格见 `docs/tag-blackboard.md`、`docs/context-assembly.md`、`skills/dialogue/world-simulator/worker-templates/`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 存储位置
|
||||
## 2. 创作阶段 Worker（磁盘 SKILL.md）
|
||||
|
||||
仅包内 **design 专用** worker 用磁盘文件：
|
||||
|
||||
```text
|
||||
skills/novel/weird-rules-short/
|
||||
skills/dialogue/world-simulator/
|
||||
├── orchestrator.md
|
||||
├── worker-templates/ # 可选模板，非执行文件
|
||||
└── workers/
|
||||
├── write-rules/SKILL.md
|
||||
└── review-infer/SKILL.md
|
||||
└── design-intake/SKILL.md
|
||||
```
|
||||
|
||||
- 目录名 = 包内 **worker id**。
|
||||
- 文件统一 **`SKILL.md`**。
|
||||
- **没有** 全局共享 worker 目录。
|
||||
- 目录名 = worker id。
|
||||
- 文件名固定 **`SKILL.md`**。
|
||||
|
||||
---
|
||||
|
||||
## 3. Frontmatter
|
||||
## 3. Design Worker Frontmatter（示例）
|
||||
|
||||
```yaml
|
||||
---
|
||||
id: write-rules
|
||||
skill: weird-rules-short
|
||||
name: 规则与解析创作
|
||||
description: >-
|
||||
从 需求.核心要点 推演内部核心，产出规则与说明。
|
||||
version: 1
|
||||
id: design-intake
|
||||
skill: world-simulator
|
||||
name: 实例设计 · Worker 集
|
||||
stage: design
|
||||
inputTags:
|
||||
- "需求.核心要点"
|
||||
- "验收.读者视角.记录"
|
||||
- "验收.作者视角.记录"
|
||||
- "用户.修改说明"
|
||||
- "用户.需求"
|
||||
outputTags:
|
||||
- "核心.危险.隐藏"
|
||||
- "规则.草稿"
|
||||
- "规则.说明.草稿"
|
||||
- "设计.worker集"
|
||||
- "设计.worker集.草稿"
|
||||
inputMerge: latest
|
||||
---
|
||||
```
|
||||
|
||||
| 字段 | 用途 |
|
||||
|------|------|
|
||||
| `id` | 包内 skill id，与 manifest 注册表一致 |
|
||||
| `skill` | 所属 orchestrator 包 name |
|
||||
| `inputTags` | Runtime 从黑板取数的 tag（精确或 `前缀.*`） |
|
||||
| `outputTags` | 允许写回的 tag；Runtime 校验 |
|
||||
| `inputMerge` | 可选，`latest`（默认）或 `concat` |
|
||||
| `contextSegments` | 可选，上下文拼接：上半 static、下半 dynamic（见 §3.1） |
|
||||
| `contextIsolation` | 可选：`none` \| `role_pov` \| `blind_review` |
|
||||
| `id` | worker id |
|
||||
| `skill` | 所属包 name |
|
||||
| `inputTags` / `outputTags` | 黑板读写白名单 |
|
||||
| `contextSegments` | 可选；上下拼接 |
|
||||
|
||||
### 3.1 contextSegments（上下文拼接）
|
||||
### 3.1 contextSegments
|
||||
|
||||
见 `docs/context-assembly.md`。示例：
|
||||
|
||||
```yaml
|
||||
contextSegments:
|
||||
- id: brief
|
||||
tier: static
|
||||
tags: ["book.brief"]
|
||||
label: "## 创作需求"
|
||||
- id: history
|
||||
tier: dynamic
|
||||
tags: ["运行.事件流"]
|
||||
policy: tail_lines_80
|
||||
- id: turn
|
||||
tier: dynamic
|
||||
tags: ["可见信息", "用户.最新输入"]
|
||||
label: "## 本轮"
|
||||
```
|
||||
|
||||
未声明时 Runtime 回退为 JSON `inputs`（当前实现）。
|
||||
|
||||
**review-infer 示例**（不得读隐藏核心）：
|
||||
|
||||
```yaml
|
||||
inputTags:
|
||||
- "需求.核心要点"
|
||||
- "规则.草稿"
|
||||
- "规则.说明.草稿"
|
||||
outputTags:
|
||||
- "验收.读者视角.记录"
|
||||
```
|
||||
|
||||
**review-author 示例**（可读隐藏核心）：
|
||||
|
||||
```yaml
|
||||
inputTags:
|
||||
- "需求.核心要点"
|
||||
- "核心.危险.隐藏"
|
||||
- "规则.草稿"
|
||||
- "规则.说明.草稿"
|
||||
outputTags:
|
||||
- "验收.作者视角.记录"
|
||||
```
|
||||
见 `docs/context-assembly.md`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 正文章节
|
||||
## 4. 实例声明字段（写入 `设计.worker集`）
|
||||
|
||||
```markdown
|
||||
# 标题
|
||||
|
||||
## 角色与口吻
|
||||
## 能力范围 # 能做什么 / 不能做什么
|
||||
## 思维链与自检
|
||||
## 上下文用法 # 各 inputTag 如何使用（不重复 frontmatter 列表）
|
||||
## 输出格式 # 各 outputTag 的 content 格式
|
||||
## 示例 # 可选
|
||||
```
|
||||
|
||||
正文中用 **tag 名** 指代上下文，例如「读 `需求.核心要点`」而非旧 key `book.brief`。
|
||||
|
||||
### 评估类 Worker
|
||||
|
||||
总管 orchestrator 只写：`rules 确认后 → run review-infer`。
|
||||
|
||||
本 SKILL 写 **评估怎么做**、verdict 写入 `验收.*.记录` 的 JSON 形状等。
|
||||
|
||||
### 用户回合 worker（user-turn）
|
||||
|
||||
**用途：** 该环节 **完全由用户输入** 组成，LLM 不替用户选行动（21 点玩家、线下人类一方等）。
|
||||
|
||||
**与 role-decide 的区别：**
|
||||
|
||||
| | role-decide | user-turn |
|
||||
|--|-------------|-----------|
|
||||
| 决策 | LLM 产出 `.思考` + `.行动` | 用户经 ask_user 提供；worker **只**写 `.行动` |
|
||||
| LLM | 需要 | 仅需展示/校验/格式化（可无生成模型） |
|
||||
|
||||
**frontmatter 示例：**
|
||||
design-intake 产出的每条 worker：
|
||||
|
||||
```yaml
|
||||
id: user-turn
|
||||
skill: blackjack-roleplay
|
||||
name: 用户回合
|
||||
description: 展示局面，收集用户合法行动，写入角色.用户.行动
|
||||
inputTags:
|
||||
- "角色.用户.可见信息"
|
||||
- "场景.公开叙述"
|
||||
outputTags:
|
||||
- "角色.用户.行动"
|
||||
```
|
||||
|
||||
**SKILL 正文要点：**
|
||||
|
||||
```markdown
|
||||
## 角色
|
||||
你是 **用户操作的采集器**，不是玩家 AI。禁止替用户选择行动。
|
||||
|
||||
## 执行
|
||||
1. 读可见信息与合法行动集
|
||||
2. ask_user：简短展示局面 + 列出可选行动
|
||||
3. 校验用户输入是否在合法集内；不合法则再问
|
||||
4. 写 `角色.用户.行动`（行动选择 + 可选说话）
|
||||
|
||||
## 禁止
|
||||
- 调用 LLM 模拟用户策略
|
||||
- 写入 `.思考`（用户无内心 tag，或仅 UI 留空）
|
||||
```
|
||||
|
||||
编排：总管在轮到用户时 `run_worker(user-turn)`；world-engine 与 role-decide **同一套** 读 `.行动` 规则。
|
||||
|
||||
---
|
||||
|
||||
## 5. 运行时输出协议
|
||||
|
||||
Worker LLM 返回 JSON（Phase A）；Phase B 改为 tool call。语义不变：
|
||||
|
||||
```json
|
||||
{
|
||||
"outputs": {
|
||||
"规则.草稿": "...",
|
||||
"规则.说明.草稿": "..."
|
||||
},
|
||||
"summary": "50字以内摘要",
|
||||
"askUser": null
|
||||
}
|
||||
```
|
||||
|
||||
- `outputs` 的 key 必须是 **outputTags 中的 tag**（或与 tag 一一映射的别名，由 Runtime 归一化）。
|
||||
- 缺信息时 `askUser` 提问，不臆造。
|
||||
|
||||
Runtime 写黑板：
|
||||
|
||||
```ts
|
||||
{
|
||||
id: "...",
|
||||
tag: "规则.草稿",
|
||||
content: "...",
|
||||
source: "write-rules",
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. ask_user
|
||||
|
||||
任何 worker 可中途提问。Runtime 暂停并保存 `resumeContext`（workerId 等）；恢复时 **重新** 从 SKILL 读 inputTags，不依赖总管。
|
||||
|
||||
---
|
||||
|
||||
## 7. 命名原则
|
||||
|
||||
Worker id 按 **本包流程职责** 命名，包内唯一：
|
||||
|
||||
| 包 | worker id | 职责 |
|
||||
|----|-----------|------|
|
||||
| weird-rules-short | write-rules | 写规则 |
|
||||
| weird-rules-short | review-infer | 读者视角验收 |
|
||||
| novel-standard | outline | 大纲 |
|
||||
|
||||
不要设计全局共享 worker id。
|
||||
|
||||
---
|
||||
|
||||
## 8. 与代码的关系
|
||||
|
||||
| 文档 | 代码 |
|
||||
|------|------|
|
||||
| frontmatter inputTags / outputTags | `src/skills/loader.ts` → `ParsedWorkerSkill` |
|
||||
| 运行时取数 | `src/worker/executor.ts` |
|
||||
| 角色 worker 独立 LLM | `llmProfileId` / `llm-bindings.yaml` | `src/skills/worker-llm.ts` |
|
||||
|
||||
当前代码仍为旧 `inputKeys` / `outputKeys` 模型；迁移以 `tag-blackboard.md` 为准。
|
||||
|
||||
---
|
||||
|
||||
## 9. Worker 独立 LLM（可选，预留多 AI 博弈）
|
||||
|
||||
默认：worker 与会话 **同一 ApiProfile**（设置页当前选中的 profile）。
|
||||
|
||||
### 9.1 Worker SKILL frontmatter
|
||||
|
||||
```yaml
|
||||
llmProfileId: "<profiles.json 中的 ApiProfile.id>"
|
||||
```
|
||||
|
||||
省略 = 走 skill 包 `llm-bindings.yaml` 或会话默认。
|
||||
|
||||
### 9.2 Skill 包 llm-bindings.yaml
|
||||
|
||||
```yaml
|
||||
defaultProfileId: null # null = 会话默认
|
||||
|
||||
workers:
|
||||
world-engine: {}
|
||||
role-decide:
|
||||
byRole:
|
||||
A: "<profile-id-1>"
|
||||
B: "<profile-id-2>"
|
||||
- ref: narrator # 能力库 id；null = gap
|
||||
role: transcription
|
||||
duty: …
|
||||
when: …
|
||||
rationale: …
|
||||
context:
|
||||
static: [设计.worker集]
|
||||
dynamic: [运行.本轮.裁决]
|
||||
outputs: [输出.用户展示]
|
||||
presentation:
|
||||
tone: …
|
||||
```
|
||||
|
||||
Runtime 解析顺序见 `src/skills/worker-llm.ts`。
|
||||
`role-decide` 按 `slots.世界.当前角色.id` 匹配 `byRole`。
|
||||
|
||||
### 9.3 设计意图
|
||||
|
||||
- 配置仍在 **profiles.json**（或 .env），不在 SKILL 里写密钥
|
||||
- 同一 skill 可让不同角色用不同模型/API，实现真实多 agent 博弈
|
||||
- 总管 LLM 不受 worker 绑定影响（始终会话默认）
|
||||
未写全的 `context`/`outputs` 可由 `worker-templates/{ref}.yaml` 合并。
|
||||
|
||||
---
|
||||
|
||||
## 5. 执行要点
|
||||
|
||||
- Agent **不**指定 inputTags；读 Worker 声明 / 模板。
|
||||
- `ref: null` + `gap`：声明了职责但无模板 / SKILL，需补声明或 temp worker。
|
||||
- 验收：`design-intake` 默认 `user_confirmed`；play 中间 worker 可 `no_confirmation`。
|
||||
|
||||
## 相关
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| `creation-playbook.md` | 创作流 |
|
||||
| `worker-declaration.ts` | Runtime 声明校验 |
|
||||
| `worker-templates/README.md` | 可选模板 |
|
||||
|
||||
139
docs/world-simulator-modules.md
Normal file
139
docs/world-simulator-modules.md
Normal file
@@ -0,0 +1,139 @@
|
||||
# 世界模拟器 · 导演与能力撰写清单
|
||||
|
||||
> 给作者用。用户侧术语：**`docs/ui-glossary.md` §0**。
|
||||
> 运行：选导演 → 编排**增量**剧本 DAG → `design-step` 执行能力；可再扩步反复调用。
|
||||
> **标准范例**：`modules/aesthetics-interaction/prompt.md`。
|
||||
> **给外部 AI 的完整泛用规范**：**`docs/briefs/capability-authoring-brief.md`**（项目概述 + 称呼 + 格式契约）。
|
||||
|
||||
## 两层
|
||||
|
||||
```text
|
||||
【导演】recipes/ 【能力】modules/
|
||||
└─ 编排增量 DAG → design-step 注入能力块 →（open 则再编排）→ 演员上场
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 能力文档格式（程序可切割）
|
||||
|
||||
每个能力 = `modules/{id}/prompt.md` + `catalog.yaml` 一行。
|
||||
|
||||
程序**只认 fence 语言标签**切割，不认散文/`##` alone：
|
||||
|
||||
| 块 id | 必填 | 用途 |
|
||||
|-------|------|------|
|
||||
| `meta` | 建议 | YAML：name / id / artifact / declaration / when / when_not / boundary |
|
||||
| `opening` | 可选 | **默认问题**正文；程序发给用户，不经 LLM |
|
||||
| `task` | 是 | 本步任务与验收边界 |
|
||||
| `principles` | 建议 | 原则 |
|
||||
| `probe` | 建议 | 追问策略 |
|
||||
| `output` | 是 | 产物形状（多为 JSON） |
|
||||
| `checklist` | 建议 | 自检 |
|
||||
| `examples` | 可选 | 好/坏对照 |
|
||||
|
||||
````markdown
|
||||
# 能力中文名
|
||||
|
||||
## meta
|
||||
```meta
|
||||
name: …
|
||||
id: …
|
||||
artifact: 设计.…
|
||||
declaration: …
|
||||
```
|
||||
|
||||
## opening
|
||||
```opening
|
||||
（用户看到的开场白；可省略整块 = 本步直接调 LLM）
|
||||
```
|
||||
|
||||
## task
|
||||
```task
|
||||
…
|
||||
```
|
||||
|
||||
## principles
|
||||
```principles
|
||||
…
|
||||
```
|
||||
|
||||
## probe
|
||||
```probe
|
||||
…
|
||||
```
|
||||
|
||||
## output
|
||||
```output
|
||||
{ … }
|
||||
```
|
||||
|
||||
## checklist
|
||||
```checklist
|
||||
- [ ] …
|
||||
```
|
||||
````
|
||||
|
||||
切割实现：`parseModulePromptSections` / `extractModuleOpening` / `formatModulePromptForLlm`（`src/skills/creation-flow.ts`）。
|
||||
注入 LLM 时按块顺序拼接，**不含** `opening`（开场已由程序发出）。
|
||||
|
||||
### catalog 一行（插入导演提示词）
|
||||
|
||||
| 字段 | 作用 |
|
||||
|------|------|
|
||||
| `id` / `name` / `declaration` / `artifact` | 选型与产物映射 |
|
||||
| `repeatable` | 可选；`true` = 允许同能力多次编入增量 DAG |
|
||||
| `opening` | 可选覆盖；一般只写在 prompt 的 `opening` 块 |
|
||||
|
||||
### 默认问题节奏（通用）
|
||||
|
||||
```text
|
||||
程序发 opening → 用户首答 → LLM（opening + 首答 + 切割后的方法块 + 依赖）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 目录与清单
|
||||
|
||||
```text
|
||||
modules/catalog.yaml
|
||||
modules/{id}/prompt.md
|
||||
recipes/world-simulator|expand-assistant/recipe.yaml
|
||||
```
|
||||
|
||||
世界模拟器**可能用到**的能力（编排按需选用，勿默认全选）：
|
||||
|
||||
| 能力 | id | 状态 |
|
||||
|------|-----|------|
|
||||
| 美学纲领与交互范式 | `aesthetics-interaction` | **范例已写** |
|
||||
| 实现机制 | `mechanism` | **已写** |
|
||||
| 世界蓝图与人文地理 | `world-blueprint` | **已写** |
|
||||
| 生成规则 | `generation-rules` | 骨架，**可反复** |
|
||||
| 具体实例 | `concrete-instances` | 骨架，**可反复** |
|
||||
| 拓扑图谱 | `topology` | 骨架，待细写 |
|
||||
| 设计状态栏 | `status-bar` | 骨架，待细写 |
|
||||
| 叙事指南 | `narrative` | 骨架，待细写 |
|
||||
| 变量设计与更新规则 | `variable-design` | 骨架，待细写 |
|
||||
| 变量控制上下文 | `variable-context` | 骨架，待细写 |
|
||||
| 设计回复格式 | `reply-format` | 骨架，待细写 |
|
||||
|
||||
共用收成（池内保留，按需）：
|
||||
|
||||
| 能力 | id | 状态 |
|
||||
|------|-----|------|
|
||||
| Worker 规格 | `worker-spec` | 骨架，**可反复** |
|
||||
| 细化终稿 | `refine` | 骨架，待细写 |
|
||||
|
||||
| 导演 | 状态 |
|
||||
|------|------|
|
||||
| 世界模拟器 | 建议第一步：美学纲领与交互范式 |
|
||||
| 扩写助手 | 待完善 |
|
||||
|
||||
---
|
||||
|
||||
## 验收
|
||||
|
||||
1. 只选导演 → 出**近期**创作流程（`status=open`）
|
||||
2. design-step 能切割出 `opening`/`task`/…
|
||||
3. 有 `opening` 时先程序开场再 LLM
|
||||
4. 可追加同能力多次（不同 step.id）；收成前 `status=closed`
|
||||
5. UI 用拍摄术语
|
||||
Reference in New Issue
Block a user