@mebular/service 0.0.0-stage → 0.1.0

package/dist/units.d.ts

@@ -0,0 +1,50 @@
+export type ServicePlatform = 'darwin' | 'linux' | 'win32';
+/** 三个常驻组件（服务单元名 = 角色名）。 */
+export type ServiceKind = 'fleet-node' | 'fleet-worker' | 'mebular-serve';
+export declare const SERVICE_KINDS: readonly ServiceKind[];
+/** 默认服务名前缀（标签/任务名由它派生；测试可用 labelPrefix 覆盖）。 */
+export declare const DEFAULT_LABEL_PREFIX = "com.mebular";
+export interface UnitSpec {
+    kind: ServiceKind;
+    /** launchd Label / systemd 单元名 / Windows 任务名（派生后的完整名） */
+    label: string;
+    /** 解释器（通常 process.execPath） */
+    execPath: string;
+    /** 解释器参数（通常 [cli.js, 'node'|'worker', ...]） */
+    args: readonly string[];
+    workingDir?: string;
+    env?: Readonly<Record<string, string>>;
+    /** 服务日志（stdout/stderr）绝对路径 */
+    stdoutLog: string;
+    stderrLog: string;
+    /** 当前构建 SHA（钉死版本，供 `service status` 输出） */
+    sha: string;
+    /** 是否登录/开机自启（false = 仅安装、不自启） */
+    autostart: boolean;
+    /** 崩溃自拉节流（秒），默认 10 */
+    throttleSeconds?: number;
+}
+/** systemd ExecStart / Environment 的引号规则：含空白或特殊字符时用双引号包裹并转义。 */
+export declare function systemdQuote(value: string): string;
+/** 单元内的审计注释（`service status` 与人工排查都从这里/state manifest 读 SHA）。 */
+export declare const auditComment: (spec: UnitSpec) => string;
+/** macOS launchd 用户级 LaunchAgent plist。 */
+export declare function launchdPlist(spec: UnitSpec): string;
+/** Linux systemd --user 单元。 */
+export declare function systemdUnit(spec: UnitSpec): string;
+/** Windows Task Scheduler 任务 XML（onlogon，无需管理员；InteractiveToken + LeastPrivilege）。 */
+export declare function windowsTaskXml(spec: UnitSpec): string;
+/** 按平台生成单元文本。 */
+export declare function unitText(platform: ServicePlatform, spec: UnitSpec): string;
+/** 旧标签/单元名（**无 home 维度**）：`com.mebular.<kind>`。仅用于迁移期识别与清理。 */
+export declare function legacyLabel(kind: ServiceKind, labelPrefix?: string): string;
+/** home 派生键（纯函数）：同 home → 同键、不同 home → 不同键（12 位十六进制）。 */
+export declare function homeKey(home: string): string;
+/**
+ * 默认标签/单元名：`<prefix>.<kind>.<homeKey>` —— **含 home 维度**，使不同 home 的服务身份彻底隔离、
+ * 互不顶替（F-SVC-1）。省略 `home` 时退回旧的无维度标签（仅供显示/迁移识别；install 恒传 home）。
+ */
+export declare function defaultLabel(kind: ServiceKind, labelPrefix?: string, home?: string): string;
+/** systemd 单元文件名（`mebular-<kind>.service`）。 */
+export declare function systemdUnitFileName(kind: ServiceKind): string;
+//# sourceMappingURL=units.d.ts.map

package/dist/units.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../src/units.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAE3D,2BAA2B;AAC3B,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,eAAe,CAAC;AAE1E,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAAoD,CAAC;AAErG,+CAA+C;AAC/C,eAAO,MAAM,oBAAoB,gBAAgB,CAAC;AAElD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,WAAW,CAAC;IAClB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvC,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,sBAAsB;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAKD,gEAAgE;AAChE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED,iEAAiE;AACjE,eAAO,MAAM,YAAY,GAAI,MAAM,QAAQ,KAAG,MAA8D,CAAC;AAE7G,2CAA2C;AAC3C,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CA0CnD;AAED,+BAA+B;AAC/B,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAuBlD;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CA2CrD;AAED,iBAAiB;AACjB,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAa1E;AAED,+DAA+D;AAC/D,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,SAAuB,GAAG,MAAM,CAEzF;AAED,yDAAyD;AACzD,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG5C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,EAAE,WAAW,SAAuB,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzG;AAED,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,MAAM,CAE7D"}

package/dist/units.js

@@ -0,0 +1,173 @@
+// 平台服务单元生成（**纯函数**）：输入 spec，输出单元文本。无 IO、无时钟、无平台副作用，
+// 因此可对三种平台做 golden 测试，也可被 macOS/Linux/Windows 之外的环境安全调用。
+//
+// 角色命名（D2）：fleet-node（任务板/发起端）· fleet-worker（执行端）· mebular-serve（记忆/同步/MCP 底座）。
+import { createHash } from 'node:crypto';
+import { resolve } from 'node:path';
+export const SERVICE_KINDS = ['fleet-node', 'fleet-worker', 'mebular-serve'];
+/** 默认服务名前缀（标签/任务名由它派生；测试可用 labelPrefix 覆盖）。 */
+export const DEFAULT_LABEL_PREFIX = 'com.mebular';
+const escapeXml = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** systemd ExecStart / Environment 的引号规则：含空白或特殊字符时用双引号包裹并转义。 */
+export function systemdQuote(value) {
+    if (value.length > 0 && !/[\s"'\\$]/.test(value))
+        return value;
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** 单元内的审计注释（`service status` 与人工排查都从这里/state manifest 读 SHA）。 */
+export const auditComment = (spec) => `mebular-service: kind=${spec.kind} sha=${spec.sha}`;
+/** macOS launchd 用户级 LaunchAgent plist。 */
+export function launchdPlist(spec) {
+    const throttle = spec.throttleSeconds ?? 10;
+    const envKeys = Object.keys(spec.env ?? {});
+    const lines = [];
+    lines.push('<?xml version="1.0" encoding="UTF-8"?>');
+    lines.push('<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">');
+    lines.push('<plist version="1.0">');
+    lines.push('<dict>');
+    lines.push('  <!-- ' + auditComment(spec) + ' -->');
+    lines.push('  <key>Label</key>');
+    lines.push(`  <string>${escapeXml(spec.label)}</string>`);
+    lines.push('  <key>ProgramArguments</key>');
+    lines.push('  <array>');
+    lines.push(`    <string>${escapeXml(spec.execPath)}</string>`);
+    for (const arg of spec.args)
+        lines.push(`    <string>${escapeXml(arg)}</string>`);
+    lines.push('  </array>');
+    lines.push('  <key>RunAtLoad</key>');
+    lines.push(spec.autostart ? '  <true/>' : '  <false/>');
+    lines.push('  <key>KeepAlive</key>');
+    lines.push('  <true/>');
+    lines.push('  <key>ThrottleInterval</key>');
+    lines.push(`  <integer>${throttle}</integer>`);
+    lines.push('  <key>StandardOutPath</key>');
+    lines.push(`  <string>${escapeXml(spec.stdoutLog)}</string>`);
+    lines.push('  <key>StandardErrorPath</key>');
+    lines.push(`  <string>${escapeXml(spec.stderrLog)}</string>`);
+    if (spec.workingDir !== undefined) {
+        lines.push('  <key>WorkingDirectory</key>');
+        lines.push(`  <string>${escapeXml(spec.workingDir)}</string>`);
+    }
+    if (envKeys.length > 0) {
+        lines.push('  <key>EnvironmentVariables</key>');
+        lines.push('  <dict>');
+        for (const key of envKeys) {
+            lines.push(`    <key>${escapeXml(key)}</key>`);
+            lines.push(`    <string>${escapeXml(spec.env[key])}</string>`);
+        }
+        lines.push('  </dict>');
+    }
+    lines.push('</dict>');
+    lines.push('</plist>');
+    return `${lines.join('\n')}\n`;
+}
+/** Linux systemd --user 单元。 */
+export function systemdUnit(spec) {
+    const throttle = spec.throttleSeconds ?? 10;
+    const lines = [];
+    lines.push(`# ${auditComment(spec)}`);
+    lines.push('[Unit]');
+    lines.push(`Description=Mebular ${spec.kind}`);
+    lines.push('After=network.target');
+    lines.push('');
+    lines.push('[Service]');
+    lines.push('Type=simple');
+    lines.push(`ExecStart=${[spec.execPath, ...spec.args].map(systemdQuote).join(' ')}`);
+    lines.push('Restart=on-failure');
+    lines.push(`RestartSec=${throttle}`);
+    if (spec.workingDir !== undefined)
+        lines.push(`WorkingDirectory=${systemdQuote(spec.workingDir)}`);
+    for (const [key, value] of Object.entries(spec.env ?? {}))
+        lines.push(`Environment=${systemdQuote(`${key}=${value}`)}`);
+    lines.push(`StandardOutput=append:${systemdQuote(spec.stdoutLog)}`);
+    lines.push(`StandardError=append:${systemdQuote(spec.stderrLog)}`);
+    if (spec.autostart) {
+        lines.push('');
+        lines.push('[Install]');
+        lines.push('WantedBy=default.target');
+    }
+    return `${lines.join('\n')}\n`;
+}
+/** Windows Task Scheduler 任务 XML（onlogon，无需管理员；InteractiveToken + LeastPrivilege）。 */
+export function windowsTaskXml(spec) {
+    const throttle = spec.throttleSeconds ?? 10;
+    const args = [spec.execPath, ...spec.args].map((a) => (a === '' || /[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a)).join(' ');
+    const lines = [];
+    lines.push('<?xml version="1.0" encoding="UTF-16"?>');
+    lines.push('<!-- ' + auditComment(spec) + ' -->');
+    lines.push('<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">');
+    lines.push('  <RegistrationInfo>');
+    lines.push(`    <Description>Mebular ${spec.kind}</Description>`);
+    lines.push('  </RegistrationInfo>');
+    lines.push('  <Triggers>');
+    if (spec.autostart) {
+        lines.push('    <LogonTrigger>');
+        lines.push('      <Enabled>true</Enabled>');
+        lines.push('    </LogonTrigger>');
+    }
+    lines.push('  </Triggers>');
+    lines.push('  <Principals>');
+    lines.push('    <Principal id="Author">');
+    lines.push('      <LogonType>InteractiveToken</LogonType>');
+    lines.push('      <RunLevel>LeastPrivilege</RunLevel>');
+    lines.push('    </Principal>');
+    lines.push('  </Principals>');
+    lines.push('  <Settings>');
+    lines.push('    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>');
+    lines.push('    <AllowHardTerminate>true</AllowHardTerminate>');
+    lines.push('    <StartWhenAvailable>true</StartWhenAvailable>');
+    lines.push('    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>');
+    lines.push('    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>');
+    lines.push('    <RestartOnFailure>');
+    lines.push('      <Interval>PT' + throttle + 'S</Interval>');
+    lines.push('      <Count>3</Count>');
+    lines.push('    </RestartOnFailure>');
+    lines.push('  </Settings>');
+    lines.push('  <Actions Context="Author">');
+    lines.push('    <Exec>');
+    lines.push(`      <Command>${escapeXml(spec.execPath)}</Command>`);
+    lines.push(`      <Arguments>${escapeXml(args.slice(spec.execPath.length + 1))}</Arguments>`);
+    if (spec.workingDir !== undefined)
+        lines.push(`      <WorkingDirectory>${escapeXml(spec.workingDir)}</WorkingDirectory>`);
+    lines.push('    </Exec>');
+    lines.push('  </Actions>');
+    lines.push('</Task>');
+    return `${lines.join('\n')}\n`;
+}
+/** 按平台生成单元文本。 */
+export function unitText(platform, spec) {
+    switch (platform) {
+        case 'darwin':
+            return launchdPlist(spec);
+        case 'linux':
+            return systemdUnit(spec);
+        case 'win32':
+            return windowsTaskXml(spec);
+        default: {
+            const never = platform;
+            throw new Error(`unsupported platform: ${String(never)}`);
+        }
+    }
+}
+/** 旧标签/单元名（**无 home 维度**）：`com.mebular.<kind>`。仅用于迁移期识别与清理。 */
+export function legacyLabel(kind, labelPrefix = DEFAULT_LABEL_PREFIX) {
+    return `${labelPrefix}.${kind}`;
+}
+/** home 派生键（纯函数）：同 home → 同键、不同 home → 不同键（12 位十六进制）。 */
+export function homeKey(home) {
+    const normalized = resolve(home).replace(/[/\\]+$/, '') || resolve(home);
+    return createHash('sha256').update(normalized).digest('hex').slice(0, 12);
+}
+/**
+ * 默认标签/单元名：`<prefix>.<kind>.<homeKey>` —— **含 home 维度**，使不同 home 的服务身份彻底隔离、
+ * 互不顶替（F-SVC-1）。省略 `home` 时退回旧的无维度标签（仅供显示/迁移识别；install 恒传 home）。
+ */
+export function defaultLabel(kind, labelPrefix = DEFAULT_LABEL_PREFIX, home) {
+    const base = `${labelPrefix}.${kind}`;
+    return home === undefined || home.length === 0 ? base : `${base}.${homeKey(home)}`;
+}
+/** systemd 单元文件名（`mebular-<kind>.service`）。 */
+export function systemdUnitFileName(kind) {
+    return `mebular-${kind}.service`;
+}
+//# sourceMappingURL=units.js.map

package/dist/units.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"units.js","sourceRoot":"","sources":["../src/units.ts"],"names":[],"mappings":"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"}

package/dist/version.json

@@ -0,0 +1,6 @@
+{
+  "name": "@mebular/service",
+  "version": "0.1.0",
+  "sha": "38b7e436f79fe93d429d5fccc9a966c41b0a1f3d",
+  "builtAt": "2026-10-24T10:53:17.083Z"
+}

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "@mebular/service",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Mebular 常驻组件服务化：平台单元生成（launchd/systemd/Task Scheduler）+ install/uninstall/status/logs + 进程心跳",
+  "license": "MIT",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/publish-manifest.mjs set",
+    "postpack": "node ../../scripts/publish-manifest.mjs restore"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,139 @@
+// 共用 `service` 子命令（fleet / mebular 两个 CLI 复用同一 UX 与语义）。
+//
+//   install <name> [--no-autostart] [--label L] [--sha S]
+//   uninstall <name>
+//   status [name]
+//   logs <name> [--tail N]
+
+import type { RunCommand, ServiceDescriptor, ServiceOptions } from './manager.js';
+import { installService, resolveBuildSha, restartService, serviceLogs, serviceStatus, uninstallService } from './manager.js';
+import type { ServiceKind, ServicePlatform } from './units.js';
+import { appendFileSync } from 'node:fs';
+
+/**
+ * 仪器化（F-INSTALL-1）：`MEBULAR_SERVICE_TRACE=<path>` 时，install 的每条外部命令
+ * （launchctl/systemctl/…）以 JSONL 追加落盘（at/cmd/args/rc/stdout/stderr/durationMs），
+ * 供 launchd 收尾竞态等「命令级时序」诊断。
+ */
+function fileTracerFromEnv(): ServiceOptions['trace'] {
+  const target = process.env.MEBULAR_SERVICE_TRACE;
+  if (target === undefined || target.length === 0) return undefined;
+  return (entry) => {
+    try {
+      appendFileSync(target, `${JSON.stringify(entry)}\n`, 'utf-8');
+    } catch {
+      // 留痕失败绝不阻塞安装主路径
+    }
+  };
+}
+
+export interface ServiceCliOptions {
+  descriptors: readonly ServiceDescriptor[];
+  argv: readonly string[];
+  home?: string;
+  platform?: ServicePlatform;
+  run?: RunCommand;
+  out?: (line: string) => void;
+  /** 入口边界解析好的构建 SHA（F-INSTALL-1：与 cwd 解耦）；缺省回落 resolveBuildSha()。 */
+  sha?: string;
+}
+
+function parseFlags(list: readonly string[]): { positional: string[]; flags: Record<string, string | boolean> } {
+  const positional: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+  for (let i = 0; i < list.length; i++) {
+    const token = list[i]!;
+    if (token.startsWith('--')) {
+      const key = token.slice(2);
+      const next = list[i + 1];
+      // `--extra` 的值本身以 `--` 开头（透传给服务的 CLI 参数），必须按值消费。
+      if (key === 'extra' && next !== undefined) {
+        flags[key] = next;
+        i++;
+      } else if (next === undefined || next.startsWith('--')) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i++;
+      }
+    } else {
+      positional.push(token);
+    }
+  }
+  return { positional, flags };
+}
+
+const findDescriptor = (descriptors: readonly ServiceDescriptor[], name: string): ServiceDescriptor | undefined =>
+  descriptors.find((d) => d.kind === name);
+
+export const SERVICE_USAGE =
+  '用法：<cli> service install <name> [--no-autostart] [--label L] [--sha S] | uninstall <name> | restart <name> | status [name] | logs <name> [--tail N]';
+
+/** 返回退出码；输出为单行 JSON。 */
+export function runServiceCli(opts: ServiceCliOptions): number {
+  const out = opts.out ?? ((line: string) => process.stdout.write(`${line}\n`));
+  const [sub, ...rest] = [...opts.argv];
+  const { positional, flags } = parseFlags(rest);
+  const base: ServiceOptions = {
+    ...(opts.home !== undefined ? { home: opts.home } : {}),
+    ...(opts.platform !== undefined ? { platform: opts.platform } : {}),
+    ...(opts.run !== undefined ? { run: opts.run } : {}),
+  };
+  const emit = (value: unknown, code = 0): number => {
+    out(JSON.stringify(value, null, 2));
+    return code;
+  };
+
+  if (sub === 'status') {
+    const names = positional.length > 0 ? positional : opts.descriptors.map((d) => d.kind);
+    const services = names.map((name) => {
+      const descriptor = findDescriptor(opts.descriptors, name);
+      if (!descriptor) throw new Error(`未知服务：${name}`);
+      return serviceStatus(descriptor, base);
+    });
+    return emit({ ok: true, action: 'status', services });
+  }
+
+  const name = positional[0] ?? (opts.descriptors.length === 1 ? opts.descriptors[0]!.kind : undefined);
+  if (name === undefined) {
+    out(SERVICE_USAGE);
+    return 2;
+  }
+  const found = findDescriptor(opts.descriptors, name);
+  if (!found) {
+    out(SERVICE_USAGE);
+    return 2;
+  }
+  // `--extra "a b c"`：把宿主透传的额外 CLI 参数追加到服务启动命令（如 `--submit 3`）。
+  const extra = typeof flags.extra === 'string' ? flags.extra.split(/\s+/).filter((s) => s.length > 0) : [];
+  const descriptor: ServiceDescriptor = extra.length > 0 ? { ...found, args: [...found.args, ...extra] } : found;
+
+  if (sub === 'install') {
+    const autostart = flags['no-autostart'] !== true;
+    const sha = typeof flags.sha === 'string' ? flags.sha : (opts.sha ?? resolveBuildSha());
+    const trace = fileTracerFromEnv();
+    const result = installService(descriptor, {
+      ...base,
+      autostart,
+      sha,
+      ...(typeof flags.label === 'string' ? { label: flags.label } : {}),
+      ...(trace !== undefined ? { trace } : {}),
+    });
+    return emit(result);
+  }
+  if (sub === 'uninstall') {
+    return emit(uninstallService(descriptor, base));
+  }
+  if (sub === 'restart') {
+    const result = restartService(descriptor, base);
+    return emit(result, result.ok ? 0 : 1);
+  }
+  if (sub === 'logs') {
+    const tail = typeof flags.tail === 'string' ? Number(flags.tail) : undefined;
+    return emit(serviceLogs(descriptor, { ...base, ...(tail !== undefined && Number.isFinite(tail) ? { tail } : {}) }));
+  }
+  out(SERVICE_USAGE);
+  return 2;
+}
+
+export type { ServiceKind };

package/src/heartbeat.ts

@@ -0,0 +1,89 @@
+// 进程心跳（D4）：常驻组件周期性写 `<configDir>/service.heartbeat`，供 `service status` 与 doctor 判定
+// 「是否在跑且新鲜」。原子写、0600（权限语义同现约定；Windows 走 ACL，由 doctor 说明差异）。
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface Heartbeat {
+  pid: number;
+  /** epoch ms */
+  ts: number;
+  role: string;
+  sha: string;
+}
+
+export const HEARTBEAT_FILE = 'service.heartbeat';
+export const HEARTBEAT_DEFAULT_MAX_AGE_MS = 15_000;
+
+export const heartbeatPath = (dir: string): string => path.join(dir, HEARTBEAT_FILE);
+
+export function writeHeartbeat(
+  dir: string,
+  input: { role: string; sha: string; pid?: number; now?: number },
+): Heartbeat {
+  const record: Heartbeat = {
+    pid: input.pid ?? process.pid,
+    ts: input.now ?? Date.now(),
+    role: input.role,
+    sha: input.sha,
+  };
+  fs.mkdirSync(dir, { recursive: true });
+  const target = heartbeatPath(dir);
+  const tmp = `${target}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(record), { mode: 0o600 });
+  try {
+    fs.chmodSync(tmp, 0o600);
+  } catch {
+    // Windows 无 POSIX mode；由 ACL 兜底。
+  }
+  fs.renameSync(tmp, target);
+  return record;
+}
+
+export function readHeartbeat(dir: string): Heartbeat | null {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(heartbeatPath(dir), 'utf-8')) as unknown;
+    if (typeof parsed !== 'object' || parsed === null) return null;
+    const rec = parsed as Record<string, unknown>;
+    if (typeof rec.pid !== 'number' || typeof rec.ts !== 'number') return null;
+    return { pid: rec.pid, ts: rec.ts, role: String(rec.role ?? ''), sha: String(rec.sha ?? '') };
+  } catch {
+    return null;
+  }
+}
+
+export function heartbeatAgeMs(dir: string, now: number = Date.now()): number | null {
+  const hb = readHeartbeat(dir);
+  return hb === null ? null : Math.max(0, now - hb.ts);
+}
+
+export function isHeartbeatFresh(
+  dir: string,
+  maxAgeMs: number = HEARTBEAT_DEFAULT_MAX_AGE_MS,
+  now: number = Date.now(),
+): boolean {
+  const age = heartbeatAgeMs(dir, now);
+  return age !== null && age <= maxAgeMs;
+}
+
+/**
+ * 常驻进程心跳：立即写一次，之后每 `intervalMs` 刷新；返回停止函数（只停刷新，不删文件——
+ * 进程死亡后文件停留在最后 ts，`status`/doctor 据此报告「陈旧」）。
+ */
+export function startHeartbeat(
+  dir: string,
+  input: { role: string; sha: string; intervalMs?: number; pid?: number },
+): () => void {
+  const intervalMs = input.intervalMs ?? 5_000;
+  const beat = (): void => {
+    try {
+      writeHeartbeat(dir, { role: input.role, sha: input.sha, ...(input.pid !== undefined ? { pid: input.pid } : {}) });
+    } catch {
+      // 心跳失败不应让服务崩溃。
+    }
+  };
+  beat();
+  const timer = setInterval(beat, intervalMs);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// @mebular/service —— 常驻组件服务化（平台单元生成 + 生命周期 + 心跳）。零 core 依赖。
+
+export * from './units.js';
+export * from './paths.js';
+export * from './launchd.js';
+export * from './heartbeat.js';
+export * from './manager.js';
+export * from './cli.js';

package/src/launchd.ts

@@ -0,0 +1,111 @@
+// macOS launchd 作业的**纯解析与归属判定**（无 IO、无平台副作用），供 `service status/install`
+// 校验「加载中的作业是否属于本 home」——这是 F-SVC-1 的核心不变量：
+// **跨 home 的作业绝不算 running，也绝不 bootout 他人**。
+//
+// 背景（真机事故）：旧方案 label 无 home 维度（`com.mebular.<kind>`），任意 home 的 install 都会
+// 顶掉同 label 的既有作业；`launchctl print gui/<uid>/<label>` 只要 label 存在就返回 0 → 别的 home
+// 的作业被本 home 误报 running（假阳性）。故 running 判定必须回到「作业内容」：
+// ProgramArguments / MEBULAR_HOME / WorkingDirectory / plist 路径与本 home 是否一致。
+
+import { resolve, sep } from 'node:path';
+
+/** `launchctl print gui/<uid>/<label>` 里我们关心的事实。 */
+export interface LaunchdJob {
+  label: string | null;
+  /** 作业来源 plist 路径（`path = …`） */
+  path: string | null;
+  /** `program = …` */
+  program: string | null;
+  /** `arguments = { … }`（去掉可执行文件名之外的逐项） */
+  arguments: string[];
+  /** `environment = { K => V }`（`=>` 与 `=` 两种写法都接受） */
+  environment: Record<string, string>;
+  /** `working directory = …` */
+  workingDirectory: string | null;
+}
+
+const strip = (value: string): string => value.trim().replace(/^["']|["']$/g, '').trim();
+
+/** 归属比较用的路径规范化（绝对化 + 去尾部分隔符）。纯字符串运算，不做 realpath（免 IO）。 */
+export function normalizeServicePath(value: string): string {
+  const absolute = resolve(value);
+  return absolute.length > 1 ? absolute.replace(/[/\\]+$/, '') : absolute;
+}
+
+function readScalar(lines: readonly string[], key: string): string | null {
+  const re = new RegExp(`^\\s*${key}\\s*=\\s*(.+?)\\s*$`);
+  for (const line of lines) {
+    const match = re.exec(line);
+    if (match) return strip(match[1]!);
+  }
+  return null;
+}
+
+/** 读 `key = { … }` 或 `key = ( … )` 块内容（去缩进、去行尾逗号）。 */
+function readBlock(lines: readonly string[], key: string): string[] {
+  const open = new RegExp(`^\\s*${key}\\s*=\\s*[({]\\s*$`);
+  const start = lines.findIndex((line) => open.test(line));
+  if (start < 0) return [];
+  const out: string[] = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i]!;
+    if (/^\s*[)}]\s*$/.test(line)) break;
+    const trimmed = line.replace(/^\s+/, '').replace(/,\s*$/, '');
+    if (trimmed.length > 0) out.push(trimmed);
+  }
+  return out;
+}
+
+/**
+ * 解析 `launchctl print gui/<uid>/<label>` 输出。**容错**：缺块/空输出返回全 null，
+ * 调用方据此判定「不归属」（保守 → 绝不当成 running）。
+ */
+export function parseLaunchdPrint(output: string): LaunchdJob {
+  const lines = String(output ?? '').split('\n');
+  const argumentsList = readBlock(lines, 'arguments').map(strip).filter((s) => s.length > 0);
+  const environment: Record<string, string> = {};
+  for (const entry of readBlock(lines, 'environment')) {
+    const match = /^(.+?)\s*(?:=>|=)\s*(.*)$/.exec(entry);
+    if (match && match[1] !== undefined) environment[strip(match[1])] = strip(match[2] ?? '');
+  }
+  return {
+    label: readScalar(lines, 'label'),
+    path: readScalar(lines, 'path'),
+    program: readScalar(lines, 'program'),
+    arguments: argumentsList,
+    environment,
+    workingDirectory: readScalar(lines, 'working directory'),
+  };
+}
+
+/**
+ * 加载中的作业是否属于本 home。**任一**事实匹配即视为本 home：
+ *   - 环境 `MEBULAR_HOME` / `MEBULAR_SERVICE_HOME` == home；
+ *   - `working directory` == home；
+ *   - plist 路径位于 `<home>/` 之下。
+ * 无法判定（解析不到任何事实）→ **false**（保守：宁可说不是本 home，也不误报 running）。
+ */
+export function jobBelongsToHome(job: LaunchdJob | null, home: string): boolean {
+  if (!job) return false;
+  const target = normalizeServicePath(home);
+  for (const key of ['MEBULAR_HOME', 'MEBULAR_SERVICE_HOME'] as const) {
+    const value = job.environment[key];
+    if (typeof value === 'string' && value.length > 0 && normalizeServicePath(value) === target) return true;
+  }
+  if (job.workingDirectory && normalizeServicePath(job.workingDirectory) === target) return true;
+  if (job.path) {
+    const p = normalizeServicePath(job.path);
+    if (p === target || p.startsWith(target + sep)) return true;
+  }
+  return false;
+}
+
+/** 人类可读的「占用者」描述（用于警告文案；无法识别时给 null）。 */
+export function describeJobOwner(job: LaunchdJob | null): string | null {
+  if (!job) return null;
+  const fromEnv = job.environment.MEBULAR_HOME ?? job.environment.MEBULAR_SERVICE_HOME;
+  if (typeof fromEnv === 'string' && fromEnv.length > 0) return fromEnv;
+  if (job.workingDirectory) return job.workingDirectory;
+  if (job.path) return job.path;
+  return null;
+}