86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
# Pulse Engine 目录规范
|
|
|
|
> `~/.upulse/engine/` — Pulse 的"用户态"代码空间，独立 git 仓库。
|
|
|
|
## 架构
|
|
|
|
```
|
|
~/.upulse/engine/ # 独立 git repo
|
|
├── package.json # @upulse/engine, 依赖 @uncaged/pulse
|
|
├── tsconfig.json
|
|
├── templates/ # Scaffold 模板（meta coder 参考）
|
|
│ ├── workflow.ts.tmpl
|
|
│ └── workflow.test.ts.tmpl
|
|
├── src/
|
|
│ └── workflows/
|
|
│ ├── ping-pong.ts # 示例 workflow
|
|
│ ├── ping-pong.test.ts
|
|
│ ├── werewolf.ts # 业务 workflow
|
|
│ ├── werewolf.test.ts
|
|
│ └── roles/
|
|
│ ├── meta-gate.ts # Gate: 准入检查（无 LLM）
|
|
│ ├── meta-gate.test.ts
|
|
│ ├── meta-coder-cursor.ts # Coder: Cursor Agent 写代码
|
|
│ ├── meta-checker.ts # Checker: 验证 scope + build + unit test
|
|
│ ├── meta-tester.ts # Tester: E2E lifecycle 验证
|
|
│ └── meta-promoter.ts # Promoter: commit + push + code_rev
|
|
└── docs/
|
|
```
|
|
|
|
## 核心概念
|
|
|
|
### Engine vs 核心包
|
|
|
|
| | Engine (`~/.upulse/engine/`) | 核心包 (`packages/pulse/`) |
|
|
|---|---|---|
|
|
| 谁改 | Meta workflow（agent 自主改） | 人工 / subagent |
|
|
| 内容 | 业务 workflow + meta roles | 框架代码 |
|
|
| 版本控制 | engine repo git hash = `code_rev` | pulse repo |
|
|
| 部署 | promote event → daemon 热加载 | npm publish |
|
|
|
|
### code_rev
|
|
|
|
Engine repo 的 **git commit hash** 就是 `code_rev`。
|
|
|
|
- 每次 promoter commit 后，commit hash 成为新的 `code_rev`
|
|
- Guard state 按 `code_rev` 隔离（同一 guard + 同一 key，不同版本有独立 state）
|
|
- 回滚 = 切回旧 `code_rev`，旧 state 还在
|
|
|
|
### Meta Workflow 流程
|
|
|
|
```
|
|
START → gate → coder → checker → tester → promoter → END
|
|
↑ | |
|
|
└── fail ──┘── fail ──┘
|
|
```
|
|
|
|
| Role | 职责 | LLM |
|
|
|------|------|-----|
|
|
| **gate** | 准入检查：任务描述够不够详细、是否在 engine scope | ❌ |
|
|
| **coder** | 用 Cursor Agent 写代码，参考 templates/ | ✅ Agent |
|
|
| **checker** | 验证文件 scope + `bun run build` + `bun test` | ❌ |
|
|
| **tester** | E2E lifecycle 验证：import → temp store → tick → quiescence | ❌ |
|
|
| **promoter** | `git commit` + `git push` + 输出 `codeRev` | ❌ |
|
|
|
|
### Daemon 加载机制
|
|
|
|
1. Daemon 启动时 `tryLoadFromEngine`，优先加载 engine 目录下的 workflow/role
|
|
2. Engine 文件 import 用 `@uncaged/pulse`（npm link 到核心包）
|
|
3. Promote event 触发 daemon 重新加载
|
|
|
|
## 开发新 Workflow
|
|
|
|
1. 参考 `templates/workflow.ts.tmpl` 创建 `src/workflows/{name}.ts`
|
|
2. 参考 `templates/workflow.test.ts.tmpl` 创建配套测试
|
|
3. `bun test` 确认通过
|
|
4. Git commit + push
|
|
|
|
或者通过 meta workflow 自动生成：向 daemon 提交任务 → gate → coder → checker → tester → promoter → 自动完成。
|
|
|
|
## 约束
|
|
|
|
- Workflow 文件只放 `src/workflows/` 下
|
|
- Meta role 文件只放 `src/workflows/roles/` 下
|
|
- Import 用 `@uncaged/pulse`，不用相对路径到核心包
|
|
- Commit author: `小橘 <xiaoju@shazhou.work>`
|