LifeOS Pulse Observability 模块以 Bun 为默认运行时的开发约定与内置 API 实战指南【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS本文基于 LifeOS 仓库中 Pulse Observability 模块的 CLAUDE.md 展开系统讲解该模块默认使用 Bun 而非 Node.js的完整开发约定命令替换映射、内置 API 选型Bun.serve、bun:sqlite、Bun.file等、bun test测试约定与 HTML 直导的前端方案。读完本文你可以直接按这套约定为 LifeOS Pulse 及其 Observability 面板编写可运行的 TypeScript 代码并理解这些约定在 Pulse 守护进程源码中的真实落地方式。这份约定文件在 LifeOS 中的位置与作用CLAUDE.md 位于LifeOS/install/LIFEOS/PULSE/Observability/目录下是一份带 YAML frontmatter 的编码代理上下文文件description: Use Bun instead of Node.js, npm, pnpm, or vite.—— 一句话概括其意图globs: *.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json—— 声明该约定在编辑这些文件类型时生效alwaysApply: false—— 按 glob 触发而非全局强制。也就是说当你在 Pulse 的 Observability 目录下或匹配上述文件类型的任意位置让 AI 编码代理或开发者协作改动.ts、.tsx、.html、.css、package.json等文件时应默认遵循Bun 优先的原则。这份约定并非空谈仓库中 Pulse 组件本身就是构建在 Bun 之上的后文会逐一给出源码级证据。命令替换约定从 Node 生态到 Bun 的完整映射约定文件给出的核心映射关系如下这是整个模块日常开发的操作基准原 Node 生态用法LifeOS Observability 约定用法node file/ts-node filebun filejest/vitestbun testwebpack/esbuildbun build file.html\|file.ts\|file.cssnpm install/yarn install/pnpm installbun installnpm run script/yarn run script/pnpm run scriptbun run scriptnpx package commandbunx package commanddotenv手动加载 .env无需引入Bun 自动加载.env仓库中的实际用法与这张表完全一致Observability/README.md 中给出的标准操作就是bun install安装依赖、bun run index.ts运行入口Pulse 顶层 package.json 的start脚本直接写作start: bun run pulse.ts安装/管理脚本 manage.sh 的status分支甚至用内联执行的方式读取状态文件bun -e const state JSON.parse(...)见 manage.sh说明bun -e已融入运维脚本两个目录下的bun.lockPULSE/bun.lock、Observability/bun.lock表明依赖解析统一由bun install维护而非 npm/yarn 锁文件。内置 API 选型约定及其在 Pulse 源码中的落地约定文件的 APIs 小节给出了一张用内置 API 替代第三方包的选型表。下表在每条约定旁补充了仓库内可直接核对的源码位置约定来自 CLAUDE.md仓库内的实现证据Bun.serve()支持 WebSocket、HTTPS、路由不用expresspulse.ts 中const server Bun.serve({...})是 Pulse 守护进程唯一的 HTTP 入口在单个fetch处理器内分派/api/pulse/health、/notify、/hooks/*等全部路由bun:sqlite访问 SQLite不用better-sqlite3lib/messages-db.ts 直接import { Database } from bun:sqlite以readonly: true打开 macOS 的~/Library/Messages/chat.db实现零第三方依赖的消息库读取Bun.file优先于node:fs的 readFile/writeFile全代码库高频出现Observability/observability.ts 用Bun.file(filePath)读取文件lib.ts 用Bun.file(...).text()读取PULSE.toml与用户配置modules/bunker.ts 甚至把Bun.file(path)直接作为Response返回并附加Cache-Control头modules/local-intelligence.ts 使用Bun.file(logPath).writer()追加写日志Bun.redis替代ioredisBun.sql替代pg/postgres.js约定文件中的选型建议当前 Pulse 源码中未见启用属于若需要则用内置 API的规范WebSocket内置不用ws同上Bun.serve的websocket选项见下文前端示例即为内置实现Bun.$\ls 替代 execa约定中的 shell 子进程写法建议Bun 自动加载.env不用 dotenvpulse.ts 中LIFEOS_PULSE_BIND_ALL开关读取process.env代码注释明确通过 env 或 .env 文件配置依赖的正是 Bun 的自动.env加载其中Bun.serve的落地值得展开。Pulse 守护进程的服务端并不引入任何 Web 框架而是在 pulse.ts 中用一个Bun.serve实例承载全部路由默认绑定127.0.0.1hostname: bindAll ? 0.0.0.0 : 127.0.0.1并在fetch入口先做反 DNS-rebinding 的 Host 头校验非回环 Host 直接 403再分派健康检查、语音/notify、Hook/hooks/*等模块路由。这正是约定中Bun.serve()支持路由不要用 express这一条在生产代码里的样子。测试约定bun test 与 bun:test约定文件规定使用bun test运行测试并给出标准用例模板// index.test.ts import { test, expect } from bun:test; test(hello world, () { expect(1).toBe(1); });要点在于测试运行时与断言库都来自运行时本身bun:test模块无需额外安装 jest/vitest 及其配置。这与 Observability/README.md 声明的Bun v1.3.6 创建的项目背景一致——凡是用bun init起步的目录测试链路天然走bun test。前端约定HTML 直导 Bun.serve 的完整示例约定文件的 Frontend 小节给出了不依赖vite的前端写法HTML 文件直接 import.tsx/.jsx/.js由 Bun 的打包器自动转译打包link指向的样式表由 Bun 的 CSS 打包器处理。原文档给出的完整三件套示例如下建议原样保留以便复用。服务器入口// index.ts import index from ./index.html Bun.serve({ routes: { /: index, /api/users/:id: { GET: (req) { return new Response(JSON.stringify({ id: req.params.id })); }, }, }, // optional websocket support websocket: { open: (ws) { ws.send(Hello, world!); }, message: (ws, message) { ws.send(message); }, close: (ws) { // handle close } }, development: { hmr: true, console: true, } })HTML 入口可直接引用.tsx模块脚本!-- index.html -- html body h1Hello, world!/h1 script typemodule src./frontend.tsx/script /body /html前端组件可直接importCSS 文件// frontend.tsx import React from react; import { createRoot } from react-dom/client; // import .css files directly and it works import ./index.css; const root createRoot(document.body); export default function Frontend() { return h1Hello, world!/h1; } root.render(Frontend /);开发时以热更新模式运行bun --hot ./index.ts约定文件最后还提示更多细节可查阅本机安装后node_modules/bun-types/docs/**.mdx中的 Bun API 文档。对照 Observability 目录的实际形态值得注意的是Observability 目录当前同时存在两类产物理解这一点有助于判断上述约定的适用范围bun init脚手架入口Observability/index.ts 目前只有一行console.log(Hello via Bun!)即约定中运行bun run index.ts所指的最小入口Next.js 仪表盘应用Observability/package.json包名pai-ideation声明了next dev --port 3333脚本依赖 React 19、Next 15、Tailwind、Radix、recharts/d3 等配套next.config.ts、tailwind.config.ts、tsconfig.json。也就是说该模块的静态面板走的是 Next.js 工程其dev/build脚本仍可用bun run dev方式执行符合脚本用bun run跑的约定而约定文件中Bun.serve HTML 直导的方案主要服务于需要快速起一个轻量服务/预览页的场景例如 observability.ts 这类在 Pulse 内生成观测数据的脚本链路。两者不冲突约定约束的是运行时与工具链选 Bun而非强制所有 UI 都用Bun.serve承载。运维侧的佐证bun 二进制路径为何如此重要Bun 优先不仅影响开发命令也深入了 Pulse 的部署链。manage.sh 在安装 launchd/systemd 服务前会显式解析 bun 的真实路径并特意避开command -v bun可能命中的/private/tmp/bun-node-*/bun临时 shim该路径在bun install子进程中有效、重启后即失效解析顺序为~/.bun/bin/buncurl 安装器/opt/homebrew/bin/bunHomebrew/usr/local/bin/bun回退到command -v bun解析结果会替换 plist/service 模板中的__BUN_PATH__占位符manage.sh最终由 start-pulse.sh 以bun run pulse.ts启动守护进程stderr 落到logs/pulse-stderr.loginstall分支还会在 10 秒内轮询http://localhost:31337/notify确认端口真正绑定后才宣布安装成功manage.sh。这条链路说明一旦偏离Bun 为唯一运行时的约定例如把bun run换成node或给模板指错 bun 路径开机自启与端口健康验证都会直接失败。适用前提与限制本约定针对使用 Bun 的目录与文件类型frontmatter 中globs所列项目整体仍是 TypeScriptREADME 标注的起步环境为Bun v1.3.6Bun.redis、Bun.sql等条目是选型规范当前 Pulse 源码尚未启用对应功能涉及 Redis/Postgres 的场景请以实际引入时的运行时版本能力为准Observability 目录下的 Next.js 仪表盘next dev --port 3333与Bun.serve方案是并存的两种形态引用具体文件时请以其所在子目录的实际package.json为准本文所有源码路径均位于仓库只读副本中读者可据路径自行核对行号与实现。【免费下载链接】LifeOS⛰️ The Life Operating System — an intent engineering platform that moves you from your current state to your ideal state, in life and work.项目地址: https://gitcode.com/GitHub_Trending/pe/LifeOS创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考