151 lines
4.8 KiB
Markdown
151 lines
4.8 KiB
Markdown
# 整体架构
|
||
|
||
## 1. 方向
|
||
|
||
**标签驱动黑板** + **agent tool loop** + **5 相位阶段机** + **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 代码文件职责
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 术语
|
||
|
||
| 词 | 含义 |
|
||
|----|------|
|
||
| **skill** | `SKILL.md` 定义的能力（设计期能力库中的一条） |
|
||
| **worker** | 某 skill 被 invoke 的一次执行 |
|
||
| **stage** | 业务阶段：`design`（实例化）→ `play`（运行）→ `done` |
|
||
| **phase** | 运行相位：`idle` \| `running` \| `waiting_user` \| `done` \| `error` |
|
||
|
||
不使用 **step** 指代设计步骤编号，避免与管道混淆。
|
||
|
||
---
|
||
|
||
## 3. Agent tool loop
|
||
|
||
```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`。
|
||
|
||
---
|
||
|
||
## 4. 阶段机做什么
|
||
|
||
阶段机 **不是** 编排表执行器，而是：
|
||
|
||
```text
|
||
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 管道。
|
||
|
||
```text
|
||
交互范式 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. 模块
|
||
|
||
```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. 实现进度（摘要）
|
||
|
||
```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
|
||
```
|