Initial commit

docs/architecture.md

@@ -0,0 +1,150 @@
+# 整体架构
+
+## 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
+```