docs: rewrite README + add CONTRIBUTING guide
- README: update Rule signature to onion middleware, add architecture diagram, document watchers/survival/storage, link all RFCs - CONTRIBUTING: code structure, architecture, dev workflow, testing conventions, Cursor Agent usage guide, design principles
This commit is contained in:
+199
@@ -0,0 +1,199 @@
|
||||
# Contributing to Pulse
|
||||
|
||||
开发指南。
|
||||
|
||||
## 前置要求
|
||||
|
||||
- [Bun](https://bun.sh) >= 1.0（运行时 + 包管理 + 测试）
|
||||
- Git
|
||||
- [Cursor Agent CLI](https://docs.cursor.com/agent) (可选，用于 AI 辅助编码)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/oc-xiaoju/pulse.git
|
||||
cd pulse
|
||||
bun install
|
||||
```
|
||||
|
||||
## 代码结构
|
||||
|
||||
```
|
||||
pulse/
|
||||
├── packages/
|
||||
│ ├── pulse/src/ ← 核心引擎（@uncaged/pulse）
|
||||
│ │ ├── index.ts ← Rule 类型、composeRules、runPulse、rebuildSnapshot
|
||||
│ │ ├── rules.ts ← 内置 rules：clampTick、errorBackoff、adaptiveInterval、dedup
|
||||
│ │ ├── store.ts ← 存储层：events.db + vitals.db + objects/ CAS
|
||||
│ │ ├── watcher.ts ← Watcher 框架：startWatcher、wakeTick、WatcherDef
|
||||
│ │ ├── watchers/ ← P0 内置 watchers（植物神经，agent 不可改）
|
||||
│ │ │ ├── system-resource.ts CPU/内存/磁盘/swap
|
||||
│ │ │ ├── process-alive.ts 关键进程存活检测
|
||||
│ │ │ ├── network.ts DNS + HTTP 连通性
|
||||
│ │ │ ├── error-log.ts 日志关键词匹配
|
||||
│ │ │ ├── llm-health.ts LLM 双层探针（轻量 + 深度）
|
||||
│ │ │ └── index.ts
|
||||
│ │ ├── survival/ ← P0 保命层（植物神经，agent 不可改）
|
||||
│ │ │ ├── constants.ts ESSENTIAL_PROCESSES 白名单、阈值常量
|
||||
│ │ │ ├── health.ts HealthSnapshot 类型 + rebuildHealth
|
||||
│ │ │ ├── rules.ts 7 个保命 rules（洋葱最外层）
|
||||
│ │ │ ├── executors.ts 保命 executors（确定性本地命令）
|
||||
│ │ │ └── index.ts
|
||||
│ │ └── executors/ ← 业务 executors（agent 可扩展）
|
||||
│ │ ├── coding-agent.ts Coding Agent Executor
|
||||
│ │ └── index.ts
|
||||
│ │
|
||||
│ └── upulse/src/ ← CLI 工具（@uncaged/upulse）
|
||||
│ ├── cli.ts 命令路由
|
||||
│ ├── daemon.ts daemon 进程管理
|
||||
│ ├── init.ts upulse init
|
||||
│ ├── git.ts git 操作封装
|
||||
│ ├── store.ts CLI 层存储辅助
|
||||
│ ├── config.ts 配置管理
|
||||
│ └── commands/
|
||||
│ ├── daemon.ts upulse daemon start/stop
|
||||
│ ├── deploy.ts upulse deploy（staging → promote）
|
||||
│ ├── dev.ts upulse dev（热重载）
|
||||
│ ├── gc.ts upulse gc（vitals 清理）
|
||||
│ ├── init.ts upulse init
|
||||
│ ├── inspect.ts upulse inspect（查看 events/vitals）
|
||||
│ ├── list.ts upulse list（列出实例）
|
||||
│ └── tick.ts upulse tick（手动触发一次 tick）
|
||||
│
|
||||
├── biome.json ← Biome linter 配置
|
||||
├── package.json ← monorepo root
|
||||
└── bun.lock
|
||||
```
|
||||
|
||||
## 架构
|
||||
|
||||
### 核心三原语
|
||||
|
||||
```
|
||||
Collector（感知）→ Rule（认知）→ Executor（行动）
|
||||
```
|
||||
|
||||
- **Collector = Watcher**：持续采集外部状态，写 vitals
|
||||
- **Rule = 洋葱中间件**：`(prev, curr, inner) => [effects, tickMs]`
|
||||
- **Executor = Effect handler**：执行 effects 产生的动作
|
||||
|
||||
### 双层驱动
|
||||
|
||||
```
|
||||
Autonomic 层（vitals.db）
|
||||
Watchers 每 5s 采集 → 写 vitals → 唤醒判定 → wakeTick()
|
||||
↓
|
||||
Tick 层（events.db） 中断 sleep
|
||||
rebuildSnapshot → Rule Chain（洋葱）→ Executors
|
||||
└── 被 timer 或 wakeTick 唤醒
|
||||
```
|
||||
|
||||
- Tick 串行不并发（加锁）
|
||||
- wakeTick 可中断 sleep，tick 执行中的 wake 设 pendingWake flag
|
||||
|
||||
### 洋葱 Rule 模型
|
||||
|
||||
```
|
||||
[panicRollback, processWatchdog, resourceGuard, ...survivalRules, ...agentRules]
|
||||
└────────── 核心包硬编码，最外层 ──────────┘ └── agent engine/ ──┘
|
||||
```
|
||||
|
||||
最外层的保命 rules 由核心包注入，agent 看不到也改不了。
|
||||
|
||||
### 存储模型
|
||||
|
||||
一切皆事件。三个存储：
|
||||
|
||||
| 存储 | 内容 | 生命周期 |
|
||||
|---|---|---|
|
||||
| `events.db` | promote/rollback/effect/error/collect/tick | 永不压缩 |
|
||||
| `vitals.db` | 高频采样数据（系统资源/进程/网络/LLM） | 可 gc（archive + downsample） |
|
||||
| `objects/` | CAS 内容寻址存储 | 自动去重，不可变 |
|
||||
|
||||
## 开发工作流
|
||||
|
||||
### 跑测试
|
||||
|
||||
```bash
|
||||
# 核心引擎测试
|
||||
cd packages/pulse && bun test
|
||||
|
||||
# 全部测试（含 E2E）
|
||||
bun test
|
||||
```
|
||||
|
||||
### Lint & 格式化
|
||||
|
||||
```bash
|
||||
# 检查
|
||||
bun run lint
|
||||
|
||||
# 自动修复
|
||||
bun run lint:fix
|
||||
```
|
||||
|
||||
项目使用 [Biome](https://biomejs.dev/) 做 lint 和格式化。CI 会检查。
|
||||
|
||||
### 分支约定
|
||||
|
||||
```bash
|
||||
git checkout -b feat/descriptive-name # 新功能
|
||||
git checkout -b fix/descriptive-name # 修复
|
||||
git checkout -b chore/descriptive-name # 工具链/配置
|
||||
```
|
||||
|
||||
### Commit 格式
|
||||
|
||||
```
|
||||
type: short description (closes #N)
|
||||
```
|
||||
|
||||
Types: `feat:` `fix:` `docs:` `refactor:` `chore:`
|
||||
|
||||
### Issue 驱动
|
||||
|
||||
每个改动都有 GitHub Issue。先开 issue，再写代码，commit 带 `closes #N`。
|
||||
|
||||
## 关键设计原则
|
||||
|
||||
1. **Moore 机** — 不逐事件响应，只看两次快照间的 diff。Effects 由新状态决定。
|
||||
2. **保命零依赖** — 保命层不依赖 LLM、不依赖外部网络。全部确定性本地命令。
|
||||
3. **Agent 不可改植物神经** — watchers/保命 rules/executors 硬编码在核心包。
|
||||
4. **幂等性靠 snapshot** — Rule 只看 `(prev, curr)`，不查 events 历史。rebuildSnapshot 预重建所有需要的状态。
|
||||
5. **Bypass = 短路** — 保命 rule 不调 `inner()` 时，内层业务 rules 全部跳过。
|
||||
|
||||
## 测试约定
|
||||
|
||||
- 单测文件和源码同目录：`foo.ts` → `foo.test.ts`
|
||||
- E2E 在 `packages/upulse/src/e2e/`
|
||||
- Mock 使用 `bun:test` 的 `jest.fn()` / `jest.spyOn()`
|
||||
- 网络/进程相关测试用依赖注入（如 `fetchFn` 参数），不做真实 IO
|
||||
- Watcher 测试构造 mock store + mock wakeTick
|
||||
- Rule 测试构造 mock snapshot + mock inner
|
||||
|
||||
## 使用 Cursor Agent 编码
|
||||
|
||||
项目使用 [Cursor Agent CLI](https://docs.cursor.com/agent) 作为主要编码工具：
|
||||
|
||||
```bash
|
||||
# 分析（只读，不改文件）
|
||||
agent -p "分析 watchers/ 目录的结构和数据流" \
|
||||
--model claude-4.6-sonnet-medium --mode=ask --output-format text --trust
|
||||
|
||||
# 执行（改文件）
|
||||
agent -p "实现 xxx 功能" \
|
||||
--model claude-4.6-sonnet-medium --force --output-format text --trust
|
||||
```
|
||||
|
||||
### 模型选择
|
||||
|
||||
| 难度 | 模型 | 场景 |
|
||||
|---|---|---|
|
||||
| 🟢 简单 | `gpt-5.4-mini-medium` | 单文件小改、格式化 |
|
||||
| 🟡 标准 | `claude-4.6-sonnet-medium` | bug fix、新功能、重构 |
|
||||
| 🔴 复杂 | `claude-4.6-opus-high-thinking` | 架构改动、多文件重构 |
|
||||
|
||||
## 相关资源
|
||||
|
||||
- [RFC #1: Pulse — Agent 的自主神经系统](https://github.com/oc-xiaoju/pulse/issues/1)
|
||||
- [RFC #23: Autonomic Layer + Rule Middleware](https://github.com/oc-xiaoju/pulse/issues/23)
|
||||
- [Design #27: P0 保命层](https://github.com/oc-xiaoju/pulse/issues/27)
|
||||
- [Wiki: Pulse 架构](https://shazhou-ww.github.io/oc-wiki/shared/pulse-agent-architecture/)
|
||||
Reference in New Issue
Block a user