整体架构

1. 方向

标签驱动黑板 + agent tool loop + 5 相位阶段机 + skill 能力库。

Skill 包（orchestrator manifest + workers/*/SKILL.md）  静态能力定义
Session + 黑板 tag                                     一次运行的实参
Book                                                     跨 Session 的项目与资产

Agent（总管）   running 相位内 tool loop，调度 invoke 哪个 skill
Runtime         拼接上下文、校验 tool、写黑板、驱动阶段机边界
阶段机          谁可动、何时等用户、产物生命周期——不是流水线剧本

核心文档：

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    代码文件职责

2. 术语

词	含义
skill	`SKILL.md` 定义的能力（设计期能力库中的一条）
worker	某 skill 被 invoke 的一次执行
stage	业务阶段：`design`（实例化）→ `play`（运行）→ `done`
phase	运行相位：`idle` \| `running` \| `waiting_user` \| `done` \| `error`

不使用 step 指代设计步骤编号，避免与管道混淆。

3. Agent tool loop

用户硬事件（输入 / 确认 / 验收）
  → 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。

4. 阶段机做什么

阶段机不是编排表执行器，而是：

1. Actor 门禁     此刻用户 / agent / worker 谁在场
2. Tool 边界      当前态允许哪些 tool
3. 事实生命周期   draft → accepted；用户才能 accept
4. 等待原因       waitingReason 细分等什么

业务「先跑哪个 skill」由 agent 在 tool loop 里决定，不由 orchestrator 逐步剧本写死。

5. 实例化：skill 能力库

实例化 = agent 在 design stage 按需 invoke instantiate skill（原「设计步骤」），不是固定 1→14 管道。

交互范式 skill → 产出 设计.run_skill清单（run 阶段需要哪些 skill）
每个 run skill 倒推 → 缺什么 instantiate skill → agent invoke
declare_instance_ready → 进入 play stage

orchestrator.md = manifest（有哪些 skill、约束、验收策略），不是逐步思维链。

6. 上下文拼接

上半固定、下半动态。规则在 skill 定义 + 实例 contextProfile；Runtime 执行。
见 docs/context-assembly.md。

7. 模块

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. 数据流（目标态）

选 orchestrator 包
  → design：agent burst → invoke instantiate skills → 设计.* tag
  → declare ready → play
  → play：用户输入 → agent burst → invoke run skills → 运行.* tag
  → 过程/资产/游玩 归档 Book（见 book-storage.md）

9. 边界

Agent        调度 skill；read_blackboard；不传 inputTags；不写黑板（边界 tool 除外）
Runtime      拼接上下文；校验 tool；写黑板；执行 worker
Worker LLM   在拼接后的 prompt 内产出；submit 写 declared outputTags
用户         approve、accept、输入
阶段机       只响应 event，不调 LLM

10. 实现进度（摘要）

✅ phase-machine、phase-runtime、skills loader
✅ 总管 tool loop（read_blackboard、run_worker、…）
⬜ toolLoopBurst 按用户事件归零
⬜ assembleWorkerContext（contextSegments）
⬜ worker tool loop
⬜ Book：designTrace / CardAsset / PlayBook
⬜ orchestrator 从编排表迁为 manifest

4.8 KiB Raw Blame History Unescape Escape