@weiping/wingline-core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 weiping liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/audit.d.ts

@@ -0,0 +1,37 @@
+import type { CommandDeps } from './commands/deps.js';
+/** 命令执行后的可见上下文：团队名有的要查注册表（任务 id、gate id），有的只能从结果里取（up）。 */
+export interface AuditCtx {
+    deps: CommandDeps;
+    result?: unknown;
+    failed: boolean;
+}
+export interface AuditEntry<A> {
+    /** 审计 command 列里记的名字，用 CLI 风格（如 `task done`、`dispatcher freeze`）。 */
+    command: string;
+    team: (a: A, ctx: AuditCtx) => string;
+    /** 任务创建这类只有结果里才有 id 的命令，从 ctx.result 取。 */
+    target?: (a: A, ctx: AuditCtx) => string | null;
+    /** 只放位置参数与开关；正文类字段会在写入前统一 clip。ctx.result 可取结果侧的字段。 */
+    summary?: (a: A, ctx: AuditCtx) => Record<string, unknown>;
+    /** 返回 true 就不写这一行（如 restore --dry-run）。 */
+    skip?: (a: A) => boolean;
+}
+export type AuditTable<C> = {
+    [K in keyof C]?: AuditEntry<Parameters<Extract<C[K], (...x: any) => any>>[1]>;
+};
+/** CLI Commands 里属于写命令的字段：每一条都要在审计表里登记。 */
+export declare const WRITE_COMMANDS: readonly string[];
+export declare function clip(s: string, n?: number): string;
+/** 命令一律吃 deps 打头；后面的参数不限于一个（follow 类的命令还要 emit 与信号）。 */
+type Command = (deps: CommandDeps, ...a: any[]) => Promise<unknown>;
+export interface AuditOptions {
+    /** command 列的前缀，给包在更大界面里的调用方（3B）区分来源用。 */
+    prefix?: string;
+    /** 命令参数里没有 `--as` 时的执行者。 */
+    actor?: string;
+}
+/** 表里有的命令包一层审计；表里没有的原样返回。 */
+export declare function auditedCommands<C extends {
+    [K in keyof C]: Command;
+}>(c: C, table: AuditTable<C>, o?: AuditOptions): C;
+export {};

package/dist/audit.js

@@ -0,0 +1,80 @@
+import { WinglineError } from './errors.js';
+import { actorOf, resolveActor } from './commands/task/identity.js';
+/** CLI Commands 里属于写命令的字段：每一条都要在审计表里登记。 */
+export const WRITE_COMMANDS = [
+    'up', 'down', 'restore', 'send', 'createTask', 'claimTask', 'releaseTask', 'reassignTask', 'startTask', 'planTask',
+    'doneTask', 'escalateTask', 'resolveGate', 'recoverTask', 'dispatcherUp', 'dispatcherDown', 'freezePostCmd',
+    'unfreezePostCmd', 'hushCmd', 'unhushCmd', 'dispatcherReply',
+];
+/** 换行与控制字符换成空格（一一对应，长度不变），超长截断并标明原长。 */
+const CONTROL = /[\x00-\x1f\x7f]/g;
+export function clip(s, n = 60) {
+    const flat = s.replace(CONTROL, ' ');
+    return flat.length <= n ? flat : `${flat.slice(0, n)}…（共 ${flat.length} 字）`;
+}
+/** 摘要里的字符串统一截断；未填的开关不记。 */
+function summaryOf(s) {
+    const out = {};
+    for (const [k, v] of Object.entries(s)) {
+        if (v === undefined || v === null)
+            continue;
+        out[k] = typeof v === 'string' ? clip(v) : v;
+    }
+    return out;
+}
+/**
+ * 写一行审计。任何一步出错都只 warn 一次：命令的结果与退出码不因此改变。
+ * 执行者在命令执行之后才解析，解析不出来记 `unknown`、不重试（Orca 不可达时不该再多一次失败调用）。
+ */
+async function write(deps, entry, a, outcome, o, result) {
+    try {
+        const as = a?.as ?? o.actor;
+        let actor = 'unknown';
+        try {
+            // 复审 I-1a：actor 是用户可控的 --as 值，压平控制字符，别让 wl log 里的行被伪造
+            actor = clip(actorOf(await resolveActor(deps, as)).actor);
+        }
+        catch {
+            // Orca 不可达：记 unknown
+        }
+        const ctx = { deps, result, failed: outcome !== 'ok' };
+        const detail = entry.summary ? summaryOf(entry.summary(a, ctx)) : undefined;
+        deps.registry.appendAudit({
+            team: entry.team(a, ctx),
+            actor,
+            command: o.prefix ? `${o.prefix} ${entry.command}` : entry.command,
+            target: entry.target?.(a, ctx) ?? null,
+            outcome,
+            ...(detail !== undefined ? { detail } : {}),
+        });
+    }
+    catch (err) {
+        deps.warn(`审计写入失败：${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** 表里有的命令包一层审计；表里没有的原样返回。 */
+export function auditedCommands(c, table, o = {}) {
+    const out = {};
+    for (const name of Object.keys(c)) {
+        const fn = c[name];
+        const entry = table[name];
+        if (!entry) {
+            out[name] = fn;
+            continue;
+        }
+        out[name] = async (deps, a) => {
+            if (entry.skip?.(a))
+                return fn(deps, a);
+            try {
+                const result = await fn(deps, a);
+                await write(deps, entry, a, 'ok', o, result);
+                return result;
+            }
+            catch (err) {
+                await write(deps, entry, a, err instanceof WinglineError ? `${err.kind}:${err.code}` : 'internal:unknown', o);
+                throw err;
+            }
+        };
+    }
+    return out;
+}

package/dist/brief/render.d.ts

@@ -0,0 +1,5 @@
+import type { TeamSpec } from '../spec/load.js';
+export declare const BRIEFING_LIMIT = 12000;
+export declare function renderBriefing(spec: TeamSpec, postId: string, readFile?: (p: string) => string): string;
+/** 上限检查在加了会话标记行之后做（spec：标记行计入启动包），任何 Orca 调用之前完成。 */
+export declare function checkBriefingLimit(text: string, address: string): void;

package/dist/brief/render.js

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import { WinglineError } from '../errors.js';
+export const BRIEFING_LIMIT = 12_000;
+export function renderBriefing(spec, postId, readFile = (p) => fs.readFileSync(p, 'utf8')) {
+    const post = spec.posts.find((p) => p.id === postId);
+    if (!post)
+        throw new WinglineError('input', 'post_unknown', `团队 ${spec.name} 没有岗位 ${postId}`);
+    const roster = spec.posts
+        .map((p) => `- ${p.id}@${spec.name}${p.id === spec.lead ? '（牵头）' : ''} · ${p.agent}`)
+        .join('\n');
+    const sections = [
+        `你是 ${postId}@${spec.name}，你的职责见下方岗位说明。`,
+        `## 团队名册\n${roster}`,
+        `## 团队规范\n${readFile(spec.normsPath).trim()}`,
+        ...post.briefPaths.map((p) => `## 岗位说明\n${readFile(p).trim()}`),
+        `## 沟通方式\n用 \`wl send <地址> "<消息>"\` 联系其他岗位，例如 \`wl send ${spec.lead}@${spec.name} "..."\`。`,
+    ];
+    const text = sections.join('\n\n');
+    return text;
+}
+/** 上限检查在加了会话标记行之后做（spec：标记行计入启动包），任何 Orca 调用之前完成。 */
+export function checkBriefingLimit(text, address) {
+    if (text.length > BRIEFING_LIMIT) {
+        throw new WinglineError('input', 'briefing_too_long', `岗位 ${address} 的启动包 ${text.length} 字符，超过 ${BRIEFING_LIMIT}`, {
+            hint: '请精简 NORMS 或 brief 文件，雁阵不会截断启动包',
+        });
+    }
+}

package/dist/commands/about.d.ts

@@ -0,0 +1,25 @@
+import type { ConsoleFile } from '../server/control.js';
+import type { CommandDeps } from './deps.js';
+import { type DispatcherHealth } from './dispatcher/lifecycle.js';
+export interface AboutItem {
+    key: string;
+    value: string | number | boolean | null;
+    source: 'env' | 'default' | 'registry' | 'file' | 'orca';
+    note?: string;
+}
+export interface AboutTeam {
+    name: string;
+    specPath: string;
+    status: string;
+    draft: boolean;
+    dispatcher: DispatcherHealth['state'];
+}
+/** 控制台“关于与诊断”页的数据：只读，取不到的项目显式标 null，不影响其余各项。 */
+export declare function about(deps: CommandDeps, o: {
+    version: string;
+    consoleFile: ConsoleFile | null;
+    env?: NodeJS.ProcessEnv;
+}): Promise<{
+    items: AboutItem[];
+    teams: AboutTeam[];
+}>;

package/dist/commands/about.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { WinglineError } from '../errors.js';
+import { draftPathOf } from '../spec/draft.js';
+import { dispatcherHealth } from './dispatcher/lifecycle.js';
+import { inRange } from './version-range.js';
+/** 目录下所有文件的字节数之和；目录不存在算 0。 */
+function dirBytes(dir) {
+    let total = 0;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const e of entries) {
+        const p = path.join(dir, e.name);
+        try {
+            total += e.isDirectory() ? dirBytes(p) : fs.statSync(p).size;
+        }
+        catch {
+            // 读到一半被删掉的文件不算
+        }
+    }
+    return total;
+}
+async function orcaVersion(deps) {
+    try {
+        const v = await deps.orca.version();
+        return {
+            version: { key: 'orca.version', value: v, source: 'orca' },
+            verified: { key: 'orca.verified', value: inRange(v, deps.verifiedOrca), source: 'default', note: deps.verifiedOrca },
+        };
+    }
+    catch (err) {
+        const note = err instanceof WinglineError ? err.code : 'unknown';
+        return {
+            version: { key: 'orca.version', value: null, source: 'orca', note },
+            verified: { key: 'orca.verified', value: null, source: 'default', note: deps.verifiedOrca },
+        };
+    }
+}
+function orcaPathItem(deps, env) {
+    if (env.WINGLINE_ORCA)
+        return { key: 'orca.path', value: deps.orcaPath, source: 'env', note: 'WINGLINE_ORCA' };
+    if (env.ORCA_CLI_COMMAND)
+        return { key: 'orca.path', value: deps.orcaPath, source: 'env', note: 'ORCA_CLI_COMMAND' };
+    return { key: 'orca.path', value: deps.orcaPath, source: 'default', note: 'PATH' };
+}
+function consoleItems(f) {
+    if (!f)
+        return [];
+    return [
+        { key: 'console.pid', value: f.pid, source: 'file' },
+        { key: 'console.port', value: f.port, source: 'file' },
+        { key: 'console.startedAt', value: f.startedAt, source: 'file' },
+    ];
+}
+/** 控制台“关于与诊断”页的数据：只读，取不到的项目显式标 null，不影响其余各项。 */
+export async function about(deps, o) {
+    const env = o.env ?? deps.env;
+    const orca = await orcaVersion(deps);
+    const items = [
+        { key: 'wingline.version', value: o.version, source: 'default' },
+        orcaPathItem(deps, env),
+        orca.version,
+        orca.verified,
+        env.WINGLINE_HOME
+            ? { key: 'home.path', value: deps.home, source: 'env', note: 'WINGLINE_HOME' }
+            : { key: 'home.path', value: deps.home, source: 'default' },
+        { key: 'registry.migration', value: deps.registry.schemaVersion(), source: 'registry' },
+        { key: 'logs.bytes', value: dirBytes(path.join(deps.home, 'logs')), source: 'file' },
+        ...consoleItems(o.consoleFile),
+    ];
+    const teams = deps.registry.listTeams().map((t) => ({
+        name: t.name,
+        specPath: t.specPath,
+        status: t.status,
+        draft: fs.existsSync(draftPathOf(t.specPath)),
+        dispatcher: dispatcherHealth(deps, t.name).state,
+    }));
+    return { items, teams };
+}

package/dist/commands/autostart/apply.d.ts

@@ -0,0 +1,20 @@
+import fs from 'node:fs';
+import type { AutostartPlan } from './plan.js';
+export type Exec = (file: string, args: string[]) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export type FsLike = Pick<typeof fs, 'mkdirSync' | 'writeFileSync' | 'readFileSync' | 'renameSync' | 'rmSync' | 'existsSync' | 'statSync'>;
+/** autostart.log 超过这个大小，安装时先改名为 autostart.log.1（覆盖已有的 .1）。 */
+export declare const LOG_ROTATE_BYTES: number;
+export type Sleep = (ms: number) => Promise<void>;
+/**
+ * 写文件（先写临时文件再改名）并注册；注册失败则恢复原来的文件并重新加载它（原来没有就删掉刚写的），不留半成品。
+ * Linux 上没有 systemd 用户会话 → autostart_unsupported，什么都不写。
+ */
+export declare function applyAutostart(plan: AutostartPlan, exec: Exec, fsx?: FsLike, sleep?: Sleep): Promise<void>;
+/** 从服务管理器注销并删除自己的文件（日志留着）；没安装过也算成功。 */
+export declare function removeAutostart(plan: AutostartPlan, exec: Exec, fsx?: FsLike): Promise<{
+    removed: boolean;
+}>;

package/dist/commands/autostart/apply.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { WinglineError } from '../../errors.js';
+/** autostart.log 超过这个大小，安装时先改名为 autostart.log.1（覆盖已有的 .1）。 */
+export const LOG_ROTATE_BYTES = 1024 * 1024;
+const RETRY_PAUSE_MS = 1000;
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** 命令起不来（ENOENT 等）按退出码 127 处理，不让它直接抛出去。 */
+async function run(exec, c) {
+    try {
+        return await exec(c.file, c.args);
+    }
+    catch (err) {
+        return { code: 127, stdout: '', stderr: err instanceof Error ? err.message : String(err) };
+    }
+}
+/** 带 retries 的步骤失败后停一秒再试，最多多试 retries 次。 */
+async function runStep(exec, c, sleep) {
+    let r = await run(exec, c);
+    for (let i = 0; r.code !== 0 && i < (c.retries ?? 0); i++) {
+        await sleep(RETRY_PAUSE_MS);
+        r = await run(exec, c);
+    }
+    return r;
+}
+function failure(c, r) {
+    const out = r.stderr.trim() || r.stdout.trim();
+    return new WinglineError('internal', 'autostart_failed', `${c.file} ${c.args.join(' ')} 失败（退出码 ${r.code}）${out ? `：${out}` : ''}`, {
+        detail: { stdout: r.stdout, stderr: r.stderr },
+    });
+}
+function rotateLog(logPath, fsx) {
+    if (!fsx.existsSync(logPath) || fsx.statSync(logPath).size <= LOG_ROTATE_BYTES)
+        return;
+    fsx.rmSync(`${logPath}.1`, { force: true });
+    fsx.renameSync(logPath, `${logPath}.1`);
+}
+/**
+ * 写文件（先写临时文件再改名）并注册；注册失败则恢复原来的文件并重新加载它（原来没有就删掉刚写的），不留半成品。
+ * Linux 上没有 systemd 用户会话 → autostart_unsupported，什么都不写。
+ */
+export async function applyAutostart(plan, exec, fsx = fs, sleep = defaultSleep) {
+    if (plan.probe) {
+        const r = await run(exec, plan.probe);
+        if (r.code !== 0) {
+            throw new WinglineError('input', 'autostart_unsupported', '没有可用的 systemd 用户会话，无法安装自启动', {
+                hint: `登录后请手动执行 wl restore --all${r.stderr.trim() ? `（${r.stderr.trim()}）` : ''}`,
+            });
+        }
+    }
+    fsx.mkdirSync(path.dirname(plan.file.path), { recursive: true });
+    fsx.mkdirSync(path.dirname(plan.logPath), { recursive: true });
+    rotateLog(plan.logPath, fsx);
+    const previous = fsx.existsSync(plan.file.path) ? fsx.readFileSync(plan.file.path, 'utf8') : null;
+    const tmp = `${plan.file.path}.tmp`;
+    try {
+        fsx.writeFileSync(tmp, plan.file.content);
+        fsx.renameSync(tmp, plan.file.path);
+        for (const c of plan.register) {
+            const r = await runStep(exec, c, sleep);
+            if (r.code !== 0 && !c.allowFail)
+                throw failure(c, r);
+        }
+    }
+    catch (err) {
+        fsx.rmSync(tmp, { force: true });
+        if (previous === null)
+            fsx.rmSync(plan.file.path, { force: true });
+        else {
+            // 旧文件放回去，并把旧代理重新加载回来（register 里的 bootout 可能已经把它卸掉了）；尽力而为，失败不再覆盖原来的错误
+            fsx.writeFileSync(plan.file.path, previous);
+            for (const c of plan.register)
+                await runStep(exec, c, sleep);
+        }
+        throw err instanceof WinglineError ? err : new WinglineError('internal', 'autostart_failed', `安装自启动失败：${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+}
+/** 从服务管理器注销并删除自己的文件（日志留着）；没安装过也算成功。 */
+export async function removeAutostart(plan, exec, fsx = fs) {
+    for (const c of plan.unregister)
+        await run(exec, c);
+    const removed = fsx.existsSync(plan.file.path);
+    fsx.rmSync(plan.file.path, { force: true });
+    return { removed };
+}

package/dist/commands/autostart/index.d.ts

@@ -0,0 +1,37 @@
+import type { CommandDeps } from '../deps.js';
+import { type Exec, type FsLike } from './apply.js';
+import { type AutostartStatus } from './status.js';
+export { applyAutostart, removeAutostart, type Exec, type FsLike, type Sleep } from './apply.js';
+export { installedCommand, planAutostart, planTargets, type AutostartPlan, type AutostartPlatform, type PlanOptions, type TargetOptions } from './plan.js';
+export { autostartStatus, type AutostartStatus } from './status.js';
+/** 登录时 Orca 常常还没起来：默认最多等 15 分钟。 */
+export declare const DEFAULT_WAIT_ORCA = "15m";
+/** 宿主环境（平台、用户、node、入口脚本、系统命令与文件系统），由 CLI 注入，测试里不碰真实系统。 */
+export interface AutostartSys {
+    platform: NodeJS.Platform;
+    homeDir: string;
+    uid?: number;
+    user?: string;
+    node: string;
+    script: string;
+    exec: Exec;
+    fs: FsLike;
+}
+export declare function autostartInstall(deps: CommandDeps, sys: AutostartSys, a?: {
+    waitOrca?: string;
+}): Promise<{
+    platform: import("./plan.js").AutostartPlatform;
+    file: string;
+    command: string[];
+    logPath: string;
+    waitOrca: string;
+}>;
+export declare function autostartUninstall(deps: CommandDeps, sys: AutostartSys): Promise<{
+    removed: boolean;
+    file: string;
+}>;
+export declare function autostartStatusOf(deps: CommandDeps, sys: AutostartSys): Promise<AutostartStatus & {
+    platform: string;
+    user?: string;
+    logPath: string;
+}>;

package/dist/commands/autostart/index.js

@@ -0,0 +1,38 @@
+import { parseDuration } from '../dispatcher/controls.js';
+import { applyAutostart, removeAutostart } from './apply.js';
+import { installedCommand, planAutostart, planTargets } from './plan.js';
+import { autostartStatus } from './status.js';
+export { applyAutostart, removeAutostart } from './apply.js';
+export { installedCommand, planAutostart, planTargets } from './plan.js';
+export { autostartStatus } from './status.js';
+/** 登录时 Orca 常常还没起来：默认最多等 15 分钟。 */
+export const DEFAULT_WAIT_ORCA = '15m';
+function planOf(deps, sys, waitOrca) {
+    return planAutostart({
+        platform: sys.platform, homeDir: sys.homeDir, uid: sys.uid, user: sys.user, node: sys.node, script: sys.script,
+        home: deps.home, orca: deps.orcaPath, waitOrca,
+    });
+}
+/** 卸载与查看状态用：只要位置和系统命令，不要求安装命令里的路径可用。 */
+function targetsOf(deps, sys) {
+    return planTargets({ platform: sys.platform, homeDir: sys.homeDir, uid: sys.uid, user: sys.user, home: deps.home });
+}
+export async function autostartInstall(deps, sys, a = {}) {
+    const waitOrca = a.waitOrca ?? DEFAULT_WAIT_ORCA;
+    parseDuration(waitOrca);
+    const plan = planOf(deps, sys, waitOrca);
+    await applyAutostart(plan, sys.exec, sys.fs);
+    return { platform: plan.platform, file: plan.file.path, command: installedCommand(plan.platform, plan.file.content), logPath: plan.logPath, waitOrca };
+}
+export async function autostartUninstall(deps, sys) {
+    const plan = targetsOf(deps, sys);
+    return { file: plan.file.path, ...(await removeAutostart(plan, sys.exec, sys.fs)) };
+}
+export async function autostartStatusOf(deps, sys) {
+    const plan = targetsOf(deps, sys);
+    const status = await autostartStatus(plan, sys.exec, {
+        readFile: (p) => sys.fs.readFileSync(p, 'utf8'),
+        exists: (p) => sys.fs.existsSync(p),
+    });
+    return { ...status, platform: plan.platform, ...(plan.user !== undefined ? { user: plan.user } : {}), logPath: plan.logPath };
+}

package/dist/commands/autostart/plan.d.ts

@@ -0,0 +1,47 @@
+export type AutostartPlatform = 'darwin' | 'linux';
+interface Step {
+    file: string;
+    args: string[];
+    /** 失败不算错（例如 bootout 一个还没加载的代理）。 */
+    allowFail?: boolean;
+    /** 失败后再试几次（每次间隔 1 秒）：bootout 返回时旧代理可能还没卸载完，紧接着的 bootstrap 会报 I/O 错误。 */
+    retries?: number;
+}
+export interface AutostartPlan {
+    platform: AutostartPlatform;
+    /** Linux：用来判断有没有 systemd 用户会话；失败 → autostart_unsupported。 */
+    probe?: Step;
+    file: {
+        path: string;
+        content: string;
+    };
+    logPath: string;
+    register: Step[];
+    unregister: Step[];
+    /** Linux：`loginctl show-user` 用。 */
+    user?: string;
+}
+export interface PlanOptions {
+    platform: NodeJS.Platform;
+    homeDir: string;
+    uid?: number;
+    user?: string;
+    node: string;
+    script: string;
+    /** WINGLINE_HOME */
+    home: string;
+    orca: string;
+    /** 如 `15m`，原样写进命令行。 */
+    waitOrca: string;
+}
+export type TargetOptions = Pick<PlanOptions, 'platform' | 'homeDir' | 'uid' | 'user' | 'home'>;
+/**
+ * 文件位置、日志路径与要执行的系统命令（`file.content` 为空）。卸载和查看状态只需要这些：
+ * 不要求命令里的 node / orca 路径能用于安装，否则环境一变（orca 只剩裸名、node 搬家）反而卸载不了已经装好的文件。
+ */
+export declare function planTargets(o: TargetOptions): AutostartPlan;
+/** 纯函数：生成文件内容与要执行的系统命令，不碰文件系统。 */
+export declare function planAutostart(o: PlanOptions): AutostartPlan;
+/** 从已安装的文件里读出它实际会执行的命令（`wl autostart status` 用它检查 node 与入口脚本还在不在）。 */
+export declare function installedCommand(platform: AutostartPlatform, content: string): string[];
+export {};

package/dist/commands/autostart/plan.js

@@ -0,0 +1,127 @@
+import path from 'node:path';
+import { WinglineError } from '../../errors.js';
+import { parseDuration } from '../dispatcher/controls.js';
+import { absoluteSelfCommand } from '../self.js';
+const P = path.posix;
+const LABEL = 'wingline.restore';
+const UNIT = 'wingline-restore.service';
+const SYSTEM_DIRS = ['/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin'];
+const xmlEscape = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+const xmlUnescape = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+/** 登录时的 PATH 极简，orca 可能是 `#!/usr/bin/env node` 之类的脚本：显式带上 node 与 orca 所在目录（去重，node 在前）。 */
+function pathEnv(node, orca) {
+    return [...new Set([P.dirname(node), P.dirname(orca), ...SYSTEM_DIRS])].join(':');
+}
+/** systemd 单元里的值：`\`、`"` 转义，`%` 写 `%%`。 */
+const unitValue = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/%/g, '%%');
+/** ExecStart 里的一个词：含空白、引号、反斜杠时用双引号包裹；`%` 写 `%%`，`$` 写 `$$`。 */
+function execWord(arg) {
+    const escaped = unitValue(arg).replace(/\$/g, () => '$$');
+    return /[\s"'\\]/.test(arg) ? `"${escaped}"` : escaped;
+}
+function plist(command, env, log) {
+    const s = (v) => `<string>${xmlEscape(v)}</string>`;
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        '<dict>',
+        '  <key>Label</key>', `  ${s(LABEL)}`,
+        '  <key>ProgramArguments</key>', '  <array>', ...command.map((c) => `    ${s(c)}`), '  </array>',
+        '  <key>RunAtLoad</key>', '  <true/>',
+        '  <key>EnvironmentVariables</key>', '  <dict>', '    <key>PATH</key>', `    ${s(env)}`, '  </dict>',
+        '  <key>StandardOutPath</key>', `  ${s(log)}`,
+        '  <key>StandardErrorPath</key>', `  ${s(log)}`,
+        '</dict>', '</plist>', '',
+    ].join('\n');
+}
+function unitFile(command, env, log) {
+    const logPath = log.replace(/%/g, '%%');
+    return [
+        '[Unit]', 'Description=Wingline: restore teams after login', '',
+        '[Service]', 'Type=oneshot', `Environment="PATH=${unitValue(env)}"`, `ExecStart=${command.map(execWord).join(' ')}`,
+        `StandardOutput=append:${logPath}`, `StandardError=append:${logPath}`, '',
+        '[Install]', 'WantedBy=default.target', '',
+    ].join('\n');
+}
+const unsupported = (why) => new WinglineError('input', 'autostart_unsupported', `这个平台暂不支持自启动：${why}`, { hint: '登录后请手动执行 wl restore --all' });
+/**
+ * 文件位置、日志路径与要执行的系统命令（`file.content` 为空）。卸载和查看状态只需要这些：
+ * 不要求命令里的 node / orca 路径能用于安装，否则环境一变（orca 只剩裸名、node 搬家）反而卸载不了已经装好的文件。
+ */
+export function planTargets(o) {
+    if (o.platform !== 'darwin' && o.platform !== 'linux')
+        throw unsupported(o.platform === 'win32' ? 'Windows 要等探针 5 之后' : o.platform);
+    const logPath = P.join(o.home, 'logs', 'autostart.log');
+    if (o.platform === 'darwin') {
+        if (o.uid === undefined)
+            throw unsupported('无法确定用户 ID');
+        const file = P.join(o.homeDir, 'Library', 'LaunchAgents', `${LABEL}.plist`);
+        const bootout = { file: '/bin/launchctl', args: ['bootout', `gui/${o.uid}/${LABEL}`], allowFail: true };
+        return {
+            platform: 'darwin', file: { path: file, content: '' }, logPath,
+            register: [bootout, { file: '/bin/launchctl', args: ['bootstrap', `gui/${o.uid}`, file], retries: 2 }],
+            unregister: [bootout],
+        };
+    }
+    const systemctl = '/usr/bin/systemctl';
+    return {
+        platform: 'linux', ...(o.user !== undefined ? { user: o.user } : {}), logPath,
+        probe: { file: systemctl, args: ['--user', 'show-environment'] },
+        file: { path: P.join(o.homeDir, '.config', 'systemd', 'user', UNIT), content: '' },
+        register: [{ file: systemctl, args: ['--user', 'daemon-reload'] }, { file: systemctl, args: ['--user', 'enable', UNIT] }],
+        unregister: [{ file: systemctl, args: ['--user', 'disable', UNIT], allowFail: true }, { file: systemctl, args: ['--user', 'daemon-reload'], allowFail: true }],
+    };
+}
+/** 纯函数：生成文件内容与要执行的系统命令，不碰文件系统。 */
+export function planAutostart(o) {
+    const plan = planTargets(o);
+    parseDuration(o.waitOrca);
+    const c = absoluteSelfCommand({
+        platform: o.platform, node: o.node, script: o.script, home: o.home, orca: o.orca,
+        args: ['restore', '--all', '--wait-orca', o.waitOrca, '--actor', 'autostart'],
+    });
+    const command = [c.file, ...c.args];
+    const env = pathEnv(o.node, o.orca);
+    const content = plan.platform === 'darwin' ? plist(command, env, plan.logPath) : unitFile(command, env, plan.logPath);
+    return { ...plan, file: { ...plan.file, content } };
+}
+/** 把 ExecStart 的一行拆回词（与 execWord 互逆）。 */
+function tokenize(line) {
+    const out = [];
+    let cur = null;
+    let quoted = false;
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (c === '\\' && quoted) {
+            cur = (cur ?? '') + (line[++i] ?? '');
+            continue;
+        }
+        if (c === '"') {
+            quoted = !quoted;
+            cur = cur ?? '';
+            continue;
+        }
+        if (!quoted && /\s/.test(c)) {
+            if (cur !== null)
+                out.push(cur);
+            cur = null;
+            continue;
+        }
+        if ((c === '%' || c === '$') && line[i + 1] === c)
+            i++;
+        cur = (cur ?? '') + c;
+    }
+    if (cur !== null)
+        out.push(cur);
+    return out;
+}
+/** 从已安装的文件里读出它实际会执行的命令（`wl autostart status` 用它检查 node 与入口脚本还在不在）。 */
+export function installedCommand(platform, content) {
+    if (platform === 'darwin') {
+        const block = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(content)?.[1] ?? '';
+        return [...block.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => xmlUnescape(m[1]));
+    }
+    const line = content.split(/\r?\n/).find((l) => l.startsWith('ExecStart='));
+    return line ? tokenize(line.slice('ExecStart='.length)) : [];
+}