Archived

This repository has been archived on 2026-06-01. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

T

xiaomo 0b32eef3c7 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

2026-04-14 13:52:20 +00:00

7.3 KiB

Raw Blame History

Contributing to Pulse

开发指南。

前置要求

Bun >= 1.0（运行时 + 包管理 + 测试）
Git
Cursor Agent CLI (可选，用于 AI 辅助编码)

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 内容寻址存储	自动去重，不可变

开发工作流

跑测试

# 核心引擎测试
cd packages/pulse && bun test

# 全部测试（含 E2E）
bun test

Lint & 格式化

# 检查
bun run lint

# 自动修复
bun run lint:fix

项目使用 Biome 做 lint 和格式化。CI 会检查。

分支约定

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。

关键设计原则

Moore 机 — 不逐事件响应，只看两次快照间的 diff。Effects 由新状态决定。
保命零依赖 — 保命层不依赖 LLM、不依赖外部网络。全部确定性本地命令。
Agent 不可改植物神经 — watchers/保命 rules/executors 硬编码在核心包。
幂等性靠 snapshot — Rule 只看 (prev, curr)，不查 events 历史。rebuildSnapshot 预重建所有需要的状态。
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 作为主要编码工具：

# 分析（只读，不改文件）
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`	架构改动、多文件重构

7.3 KiB Raw Blame History