chenmoranzhi/writing-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

完善配方驱动的创作编排

Browse Source 
为可重复技能补充参数校验与展示，统一配方、编排器和执行单元术语。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
moran
2026-07-30 17:59:20 +08:00
parent e670a5129c
commit 6392af54b4
49 changed files with 1671 additions and 626 deletions
Download Patch File Download Diff File Expand all files Collapse all files

46
docs/implementation-guide.md
View File

@@ -20,7 +20,7 @@
|---|---|---|
| **系统架构** | **`architecture.md`** | 模块边界、定义/实例、调度、上下文、持久化原则、风险 |
| 运行内核 | `runtime-state-machine.md` | 5 相位、tool 边界、burst |
| 运行内核 | `tool-contracts.md` | 总管 / worker tool |
| 运行内核 | `tool-contracts.md` | 编排器 / worker tool |
| 运行内核 | `context-assembly.md` | 上下文拼接：上半固定、下半动态 |
| 运行内核 | `tag-blackboard.md` | 标签黑板 |
| 持久化 | `book-storage.md` | Book、CardAsset、PlayBook、过程存储 |
@@ -33,11 +33,13 @@
| **日常 → P0** | **`daily-use-p0.md`** | 日常场景、功能映射、P0 详细工作包 |
| **剧本 / 方法（非系统架构）** | `design-orchestrator-guide.md` | 创作三大步、表/副作用、自检 |
| **剧本 / 方法（非系统架构）** | `creation-playbook.md` | 创作流程概念（指向指导） |
| **剧本 / 方法（非系统架构）** | `world-simulator-modules.md` | 编排器/能力清单与现行包布局 |
| **Skill 格式（非系统架构）** | `orchestrator-skill-format.md` | manifest 写法（非编排表） |
| **Skill 格式（非系统架构）** | `worker-skill-format.md` | SKILL.md、contextSegments |
| **Skill 格式（非系统架构）** | `skill-format.md` | 包存储、registry |
| **Skill 格式（非系统架构）** | `skill-format.md` | 包存储、registry（示例以 world-simulator 为准） |
| **Skill 格式（非系统架构）** | `skill-design-guide.md` | 包格式薄层 |
| **Skill 格式（非系统架构）** | `preset-format.md` | 预设导入 |
| **能力撰写** | `briefs/capability-authoring-brief.md` | 外部 AI 写 modules 交接 |
许可证占位：仓库根 `THIRD_PARTY_NOTICES.md`。
@@ -53,14 +55,16 @@
| 路线阶段 | 目标 | 备注 |
|----------|------|------|
| **PX0（当前）** | 导演 UI + 双线主路径 + 存档硬稳定 | 详见 `daily-use-p0.md` / `px-roadmap.md` |
| **PX0（当前）** | 编排器 UI + 双线主路径 + 存档硬稳定 | 详见 `daily-use-p0.md` / `px-roadmap.md` |
| PX1–PX2 | 创作/游玩体验打磨；副作用 | UI 仍可抄 |
| PX3 | Trace、预算、规格版本、E2E | — |
| PX4 | 长文加深（P0 已含最小闭环） | — |
| PX5 | 隔离 + 调试；必要时新导演包 | — |
| PX5 | 隔离 + 调试；必要时新配方包 | — |
| 延后 | SQLite / 事件溯源 / Mastra·Next | — |
历史分期 A0–E 见下节（多数已 done，作文件职责索引，不再当作「当前从零启动」路线）。
历史分期 A0–E 见下节（**多数已 done，仅作文件职责索引**；进度与验收以 [`px-roadmap.md`](./px-roadmap.md) 为准，勿再按 §9「未开始」判断现状）。
> §3b / §9 中仍可能出现 `design-intake`、`skills/novel/`、缺失文件路径等**历史表述**；磁盘真相见 `skills/dialogue/world-simulator/README.md`。
---
@@ -85,7 +89,7 @@ npm run phase-demo # 交互，手动 /decide /approve /worker-ask
npm run phase-demo -- --auto # worker 自动占位完成
```
### Phase A1 — 总管 LLM 接入（阶段机之上）
### Phase A1 — 编排器 LLM 接入（阶段机之上）
目标：在 PhaseRuntime 之上接 Main Agent，不改动 phase-machine 规则。
@@ -96,7 +100,7 @@ npm run phase-demo -- --auto # worker 自动占位完成
### Phase A2 — Skill 层（创作指南）
目标：`skills/` 批量存储 SKILL.md；启动第一个询问是选 skill；总管读 activeSkill。
目标：`skills/` 批量存储 SKILL.md；启动第一个询问是选 skill；编排器读 activeSkill。
| # | 文件 | 状态 | 干嘛的 |
|---|---|---|---|
@@ -107,7 +111,7 @@ npm run phase-demo -- --auto # worker 自动占位完成
| S04 | `src/skills/loader.ts` | todo | 解析 SKILL.md |
| S05 | `src/skills/registry.ts` | todo | listSkills() |
| S06 | `src/skills/resolver.ts` | todo | 推断当前 stage |
| S07 | `src/main-agent/skill-context.ts` | todo | 注入总管 prompt |
| S07 | `src/main-agent/skill-context.ts` | todo | 注入编排器 prompt |
| S08 | `src/runtime/phase-machine.ts` | todo | 增加 skill_selection / skill_selected |
| S09 | `src/cli/phase-demo.ts` | todo | 启动时 /select-skill |
@@ -115,7 +119,7 @@ npm run phase-demo -- --auto # worker 自动占位完成
### Phase B — Tool Call 化
目标：总管 / worker 从 JSON 决策改为 tool call；Runtime 做 tool 校验与事件转换。
目标：编排器 / worker 从 JSON 决策改为 tool call；Runtime 做 tool 校验与事件转换。
### Phase C — 真实 Worker
@@ -167,7 +171,7 @@ npm run phase-demo -- --auto # worker 自动占位完成
|---|---|---|---|---|
| A06 | `src/types/runtime.ts` | done | 相位、事件、会话、产物、ResumeContext | `runtime-state-machine.md` §2–5 |
| A07 | `src/types/blackboard.ts` | done | BlackboardItem、TagIndex | `tag-blackboard.md` §2 |
| A08 | `src/types/tools.ts` | todo | 总管 tool、worker tool 的参数与结果类型 | `tool-contracts.md` |
| A08 | `src/types/tools.ts` | todo | 编排器 tool、worker tool 的参数与结果类型 | `tool-contracts.md` |
**A06 职责：**
- 定义 `RuntimePhase`（5 种）
@@ -178,7 +182,7 @@ npm run phase-demo -- --auto # worker 自动占位完成
**A07 职责（Phase E 迁移后）：**
- 定义 `BlackboardItem`（id、tag、content、source、metadata）
- 定义 `BlackboardTagIndex`（给总管：tag + source，无 content）
- 定义 `BlackboardTagIndex`（给编排器：tag + source，无 content）
- 定义 `BlackboardWrite`（worker 写回）
**A08 职责（Phase B 再写）：**
@@ -218,7 +222,7 @@ npm run phase-demo -- --auto # worker 自动占位完成
| A11 | `src/blackboard/blackboard.ts` | done | listTagIndex、queryByPatterns、write | `tag-blackboard.md` §2 |
**A11 职责：**
- `listTagIndex()` — 给总管
- `listTagIndex()` — 给编排器
- `queryByPatterns()` — 给 worker 注入
- `write()` — 按 tag 写回
- `getContentByTag()` / `getLatestByTag()`
@@ -244,12 +248,12 @@ npm run phase-demo -- --auto # worker 自动占位完成
---
### 4.6 总管 LLM
### 4.6 编排器 LLM
| # | 文件 | 状态 | 干嘛的 | 对应文档 |
|---|---|---|---|---|
| A14 | `src/main-agent/main-agent.ts` | done | 总管：只选 worker，读 tag 索引 | `tag-blackboard.md` §6 |
| A15 | `src/main-agent/prompts.ts` | todo | 总管 prompt 拆分 | `tag-blackboard.md` §6 |
| A14 | `src/main-agent/main-agent.ts` | done | 编排器：只选 worker，读 tag 索引 | `tag-blackboard.md` §6 |
| A15 | `src/main-agent/prompts.ts` | todo | 编排器 prompt 拆分 | `tag-blackboard.md` §6 |
**A14 职责：**
- `MainAgent.decide(context)` — 调 LLM，返回 `MainAgentDecision`
@@ -258,8 +262,8 @@ npm run phase-demo -- --auto # worker 自动占位完成
- `DEFAULT_WORKERS` — 第一版可用 worker 列表
**约束：**
- 总管不读黑板 value
- 总管不直接改 phase
- 编排器不读黑板 value
- 编排器不直接改 phase
- 不含 question-worker（提问是 worker 能力）
**A15 职责（可选拆分）：** 把 prompt 从 main-agent.ts 抽出来，方便迭代。
@@ -275,12 +279,12 @@ npm run phase-demo -- --auto # worker 自动占位完成
**A16 职责：**
- `RuntimeOrchestrator` — 对外 API：start、submitUserInput、approve、accept 等
- `dispatch(event)` — 调 `applyEvent`，处理 `PhaseEffect`
- `runMainAgent()` — phase=running 时调总管
- `runMainAgent()` — phase=running 时调编排器
- `runStubWorker()` — 第一版占位 worker（Phase C 替换）
- `resumeStubWorker()` — worker 中途提问后恢复
**约束：**
- 唯一调用阶段机和总管的地方
- 唯一调用阶段机和编排器的地方
- user 事件（approve / accept）只从 CLI / API 进入，不从 LLM 进入
---
@@ -307,7 +311,7 @@ npm run phase-demo -- --auto # worker 自动占位完成
| B01 | `src/types/tools.ts` | tool 类型定义 |
| B02 | `src/runtime/tool-registry.ts` | 注册 tool、校验参数、tool → event |
| B03 | `src/main-agent/main-agent.ts` | 改为 tool calling 模式 |
| B04 | `src/runtime/tool-handlers/main-agent.ts` | 总管 tool 处理器 |
| B04 | `src/runtime/tool-handlers/main-agent.ts` | 编排器 tool 处理器 |
| B05 | `src/runtime/tool-handlers/worker.ts` | worker tool 处理器（ask_user / submit） |
**B02 职责：**
@@ -372,7 +376,7 @@ type WorkerRunOutcome =
Phase A0（可运行阶段机） ✅ 完成
phase-machine + phase-runtime + phase-demo + 测试
Phase A1（总管 LLM） ✅ 有初版（orchestrator + run.ts）
Phase A1（编排器 LLM） ✅ 有初版（orchestrator + run.ts）
下一步：orchestrator 应基于 PhaseRuntime 重构
Phase B（tool call） 未开始