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

小橘 🍊 e457f631c7 refactor: extract cursor-agent executor to @uncaged/pulse-cursor package

Made-with: Cursor

Co-authored-by: 小橘 <xiaoju@shazhou.work>

2026-04-14 23:52:24 +08:00

8.1 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   # also installs pre-push hook

Git Hooks

bun install 自动安装 pre-push hook（via scripts/install-hooks.mjs），push 前自动跑 lint + tests。

手动跑检查：bun run precheck 删除 .git/hooks/pre-push 可禁用。

代码结构

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 可扩展）
│   │       └── index.ts
│   │
│   ├── pulse-cursor/src/          ← Cursor Agent 适配器（@uncaged/pulse-cursor）
│   │   ├── index.ts                re-export
│   │   └── cursor-agent.ts         Cursor Agent Executor
│   │
│   └── 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

架构

核心三原语：Percept → Understand → Execute

Percept（感知）→ Understand（认知）→ Execute（行动）

层	英文	组件	输出	佛教映射
感知	Percept	Watchers（六处）	Events（六入，按 sense 分类）	六处触尘
认知	Understand	Rules	Effects（序列化的行动参数）	受想行
行动	Execute	Executors	Events（执行结果）	身口意业

一切皆业：Percept / Tick / Execute 都写 events。Events 是不可变的业的记录。

Effects 不是行动本身，是行动的描述——序列化的参数，由 Executor 解释执行。

双层驱动

Percept 层（vitals.db）
  Watchers 每 5s 感知 → 写 vitals → 唤醒判定 → wakeTick()
                                                    ↓
Understand + Execute 层（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`	架构改动、多文件重构

8.1 KiB Raw Blame History