upulse-engine/docs/engine-spec.md

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>