@weiping/wingline-core 0.1.1 → 0.2.0

package/dist/audit-table.d.ts

@@ -0,0 +1,11 @@
+import type { AuditTable } from './audit.js';
+import type { CommandDeps } from './commands/deps.js';
+/** 审计表里命令的最小形状：吃 deps 打头，后面参数不限于一个。 */
+type AnyCommand = (deps: CommandDeps, ...a: any[]) => Promise<unknown>;
+/** 取一张按调用方命令集定型的审计表；内容始终是同一张表。 */
+export declare function coreAuditTable<C extends {
+    [K in keyof C]: (deps: CommandDeps, ...a: any[]) => Promise<unknown>;
+}>(): AuditTable<C>;
+/** 宽松版：给不想定型的一方（如插件 worker）用。 */
+export declare const CORE_AUDIT: AuditTable<Record<string, AnyCommand>>;
+export {};

package/dist/audit-table.js

@@ -0,0 +1,85 @@
+/** 地址参数取 `@` 之后的团队名；解析不出（没有 `@`）记 `-`。 */
+const ofAddress = (a) => a.address.split('@')[1] ?? '-';
+/** 任务 id 的团队名从注册表查；查不到（任务不存在、已被清理）记 `-`。 */
+const byTask = (idOf) => (_a, ctx) => ctx.deps.registry.getTaskExt(idOf(_a))?.team ?? '-';
+const byGate = (gateId) => (_a, ctx) => ctx.deps.registry.getGate(gateId(_a))?.team ?? '-';
+/** 只有结果里才有团队名（up 成功时）；失败或没跑出结果记 `-`。 */
+const byResult = (_a, ctx) => ctx.result?.team ?? '-';
+const id = (a) => a.id;
+const ENTRIES = {
+    init: {
+        command: 'init',
+        team: byResult,
+        summary: (a, ctx) => ({ mode: a.mode, template: a.template, created: ctx.result?.created })
+    },
+    up: {
+        command: 'up',
+        team: byResult,
+        summary: (a) => ({ adoptRun: a.adoptRun, newRun: a.newRun, draft: a.draft })
+    },
+    down: { command: 'down', team: (a) => a.team, summary: (a) => ({ close: a.close }) },
+    restore: {
+        command: 'restore',
+        team: (a) => a.team,
+        skip: (a) => !!a.dryRun,
+        summary: (a) => ({ dryRun: !!a.dryRun, noTasks: !!a.noTasks, session: Object.keys(a.sessions ?? {}) })
+    },
+    send: { command: 'send', team: ofAddress, target: (a) => a.address, summary: (a) => ({ message: a.message }) },
+    createTask: {
+        command: 'task create',
+        team: (a) => a.team,
+        target: (_a, ctx) => ctx.result?.id ?? null,
+        summary: (a) => ({ title: a.title, post: a.post, tags: a.tags, parent: a.parent, as: a.as })
+    },
+    claimTask: { command: 'task claim', team: byTask(id), target: id, summary: (a) => ({ as: a.as }) },
+    releaseTask: { command: 'task release', team: byTask(id), target: id, summary: (a) => ({ as: a.as }) },
+    reassignTask: { command: 'task reassign', team: byTask(id), target: id, summary: (a) => ({ to: a.to }) },
+    startTask: { command: 'task start', team: byTask(id), target: id, summary: (a) => ({ as: a.as }) },
+    planTask: { command: 'task plan', team: byTask(id), target: id, summary: (a) => ({ text: a.text }) },
+    doneTask: { command: 'task done', team: byTask(id), target: id, summary: (a) => ({ as: a.as, resumeEpoch: a.resumeEpoch }) },
+    escalateTask: {
+        command: 'task escalate',
+        team: byTask(id),
+        target: (a) => a.id,
+        summary: (a) => ({ reason: a.reason, reopen: a.reopen, as: a.as })
+    },
+    resolveGate: {
+        command: 'task resolve',
+        team: byGate((a) => a.gateId),
+        target: (a) => a.gateId,
+        summary: (a) => ({ resolution: a.resolution, reassign: a.reassign, as: a.as })
+    },
+    recoverTask: { command: 'task recover', team: byTask(id), target: (a) => a.id, summary: (a) => ({ as: a.as }) },
+    dispatcherUp: { command: 'dispatcher up', team: (a) => a.team, summary: (a) => ({ platform: a.platform }) },
+    dispatcherDown: { command: 'dispatcher down', team: (a) => a.team, summary: (a) => ({ close: a.close }) },
+    freezePostCmd: { command: 'dispatcher freeze', team: ofAddress, target: (a) => a.address, summary: (a) => ({ reason: a.reason }) },
+    unfreezePostCmd: { command: 'dispatcher unfreeze', team: ofAddress, target: (a) => a.address },
+    hushCmd: { command: 'dispatcher hush', team: ofAddress, target: (a) => a.address, summary: (a) => ({ forMs: a.forMs }) },
+    unhushCmd: { command: 'dispatcher unhush', team: ofAddress, target: (a) => a.address },
+    dispatcherReply: {
+        command: 'dispatcher reply',
+        team: (a) => a.team,
+        target: (a) => a.messageId,
+        summary: (a) => ({ body: a.body, again: a.again })
+    },
+    saveSpecCmd: {
+        command: 'spec save',
+        team: (a) => a.team,
+        target: (_a, ctx) => ctx.result?.path ?? null,
+        summary: (a, ctx) => {
+            const r = ctx.result;
+            return { baseHash: a.baseHash?.slice(0, 16), running: a.running, wrote: r?.wrote, hash: r?.hash?.slice(0, 16) };
+        }
+    },
+    discardDraftCmd: {
+        command: 'spec discard-draft',
+        team: (a) => a.team,
+        summary: (_a, ctx) => ({ discarded: ctx.result?.discarded })
+    }
+};
+/** 取一张按调用方命令集定型的审计表；内容始终是同一张表。 */
+export function coreAuditTable() {
+    return ENTRIES;
+}
+/** 宽松版：给不想定型的一方（如插件 worker）用。 */
+export const CORE_AUDIT = coreAuditTable();

package/dist/audit.js

@@ -4,7 +4,7 @@ import { actorOf, resolveActor } from './commands/task/identity.js';
 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',
+    'unfreezePostCmd', 'hushCmd', 'unhushCmd', 'dispatcherReply', 'init',
 ];
 /** 换行与控制字符换成空格（一一对应，长度不变），超长截断并标明原长。 */
 const CONTROL = /[\x00-\x1f\x7f]/g;

package/dist/commands/about.d.ts

@@ -1,12 +1,23 @@
 import type { ConsoleFile } from '../server/control.js';
 import type { CommandDeps } from './deps.js';
 import { type DispatcherHealth } from './dispatcher/lifecycle.js';
+import { type AutostartStatus, type AutostartSys } from './autostart/index.js';
 export interface AboutItem {
     key: string;
     value: string | number | boolean | null;
     source: 'env' | 'default' | 'registry' | 'file' | 'orca';
     note?: string;
 }
+export type AboutAutostart = ({
+    supported: true;
+} & AutostartStatus & {
+    platform: string;
+    user?: string;
+    logPath: string;
+}) | {
+    supported: false;
+    reason: string;
+};
 export interface AboutTeam {
     name: string;
     specPath: string;
@@ -19,7 +30,9 @@ export declare function about(deps: CommandDeps, o: {
     version: string;
     consoleFile: ConsoleFile | null;
     env?: NodeJS.ProcessEnv;
+    autostartSys?: AutostartSys;
 }): Promise<{
     items: AboutItem[];
     teams: AboutTeam[];
+    autostart: AboutAutostart;
 }>;

package/dist/commands/about.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 import { WinglineError } from '../errors.js';
 import { draftPathOf } from '../spec/draft.js';
 import { dispatcherHealth } from './dispatcher/lifecycle.js';
+import { autostartStatusOf } from './autostart/index.js';
+import { realAutostartSys } from './autostart/sys.js';
 import { inRange } from './version-range.js';
 /** 目录下所有文件的字节数之和；目录不存在算 0。 */
 function dirBytes(dir) {
@@ -57,6 +59,15 @@ function consoleItems(f) {
         { key: 'console.startedAt', value: f.startedAt, source: 'file' },
     ];
 }
+/** 开机自启状态：取不到（平台不支持 / 权限不足）时显式说原因，不抛错。 */
+async function autostartItem(deps, sys) {
+    try {
+        return { supported: true, ...(await autostartStatusOf(deps, sys)) };
+    }
+    catch (err) {
+        return { supported: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+}
 /** 控制台“关于与诊断”页的数据：只读，取不到的项目显式标 null，不影响其余各项。 */
 export async function about(deps, o) {
     const env = o.env ?? deps.env;
@@ -80,5 +91,5 @@ export async function about(deps, o) {
         draft: fs.existsSync(draftPathOf(t.specPath)),
         dispatcher: dispatcherHealth(deps, t.name).state,
     }));
-    return { items, teams };
+    return { items, teams, autostart: await autostartItem(deps, o.autostartSys ?? realAutostartSys()) };
 }

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

@@ -0,0 +1,3 @@
+import type { AutostartSys } from './index.js';
+/** 控制台服务在 core 内，需要同样的宿主信息：系统命令以参数数组启动（不经 shell），入口脚本取符号链接解析后的真实路径。 */
+export declare function realAutostartSys(): AutostartSys;

package/dist/commands/autostart/sys.js

@@ -0,0 +1,23 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** 控制台服务在 core 内，需要同样的宿主信息：系统命令以参数数组启动（不经 shell），入口脚本取符号链接解析后的真实路径。 */
+export function realAutostartSys() {
+    const exec = (file, args) => new Promise((resolve, reject) => {
+        const child = spawn(file, args, { shell: false });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => { stdout += String(d); });
+        child.stderr.on('data', (d) => { stderr += String(d); });
+        child.on('error', reject);
+        child.on('close', (code) => resolve({ code: code ?? 1, stdout, stderr }));
+    });
+    const entry = process.argv[1] ?? '';
+    let script = path.resolve(entry);
+    try {
+        script = fs.realpathSync(entry);
+    }
+    catch { /* 保持 resolve 的结果 */ }
+    return { platform: process.platform, homeDir: os.homedir(), uid: process.getuid?.(), user: os.userInfo().username, node: process.execPath, script, exec, fs };
+}

package/dist/commands/dispatcher/lifecycle.d.ts

@@ -21,6 +21,10 @@ export declare function dispatcherLaunchCommand(a: {
 export interface UpArgs {
     team: string;
     platform?: NodeJS.Platform;
+    /** 覆盖启动命令里的 node 可执行文件。插件 worker 的 process.execPath 是宿主（Orca）的二进制，必须传真实 node。 */
+    node?: string;
+    /** 覆盖启动命令里的 wingline 入口脚本。插件等宿主进程的 argv[1] 不是 wingline，必须显式传。 */
+    script?: string;
     confirmMs?: number;
     pollMs?: number;
     sleep?: (ms: number) => Promise<void>;

package/dist/commands/dispatcher/lifecycle.js

@@ -62,7 +62,13 @@ export async function dispatcherUp(deps, a) {
     }
     const platform = a.platform ?? process.platform;
     const command = dispatcherLaunchCommand({
-        platform, node: process.execPath, script: process.argv[1] ?? '', team: a.team, home: deps.home, orca: deps.orcaPath, nodeOnPath: platform === 'win32' ? nodeOnPath(deps) : undefined,
+        platform,
+        node: a.node ?? process.execPath,
+        script: a.script ?? process.argv[1] ?? '',
+        team: a.team,
+        home: deps.home,
+        orca: deps.orcaPath,
+        nodeOnPath: platform === 'win32' ? nodeOnPath(deps) : undefined,
     });
     const lead = deps.registry.listPosts(a.team).find((p) => p.isLead);
     const { handle } = await deps.orca.terminalCreate({ worktree: lead.worktree, title: address, command });

package/dist/commands/down.js

@@ -8,6 +8,7 @@ async function closePost(deps, post, specHash) {
         const located = await locatePost(orca, address);
         if (!located) {
             registry.setPostStatus(address, 'closed');
+            registry.finalizePostRequests(post.team, address.split('@')[0]);
             return { address, outcome: 'already_gone' };
         }
         const id = nextRequestId(registry, post.team, address.split('@')[0], 'close', specHash);
@@ -18,6 +19,8 @@ async function closePost(deps, post, specHash) {
         });
         registry.finishRequest(id, ptyKilled ? 'done' : 'uncertain', { ptyKilled });
         registry.setPostStatus(address, ptyKilled ? 'closed' : 'uncertain');
+        if (ptyKilled)
+            registry.finalizePostRequests(post.team, address.split('@')[0]);
         return ptyKilled ? { address, outcome: 'closed' } : { address, outcome: 'uncertain', reason: 'Orca 未确认进程已退出' };
     }
     catch (err) {

package/dist/commands/init.d.ts

@@ -0,0 +1,17 @@
+import { type CommandDeps } from './deps.js';
+import { type TeamTemplateId } from './templates.js';
+export type InitTeamMode = 'template' | 'import';
+export interface InitTeamArgs {
+    mode: InitTeamMode;
+    name?: string;
+    repo?: string;
+    template?: TeamTemplateId;
+    dir?: string;
+    specPath?: string;
+}
+export interface InitTeamResult {
+    team: string;
+    specPath: string;
+    created: boolean;
+}
+export declare function initTeamCmd(deps: CommandDeps, a: InitTeamArgs): Promise<InitTeamResult>;

package/dist/commands/init.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { WinglineError } from '../errors.js';
+import { specHash } from '../spec/hash.js';
+import { loadTeamSpec } from '../spec/load.js';
+import { postAddress } from './deps.js';
+import { TEAM_TEMPLATES, renderBrief, renderNorms, renderTeamYaml, } from './templates.js';
+const TEAM_NAME_RE = /^[a-z0-9-]+$/;
+function writeTemplate(targetDir, tpl, name, repo) {
+    const briefsDir = path.join(targetDir, 'briefs');
+    fs.mkdirSync(briefsDir, { recursive: true });
+    const normsPath = path.join(targetDir, 'NORMS.md');
+    if (!fs.existsSync(normsPath)) {
+        fs.writeFileSync(normsPath, renderNorms({ team: name, posts: tpl.posts.map((p) => p.id) }), 'utf8');
+    }
+    for (const p of tpl.posts) {
+        const briefPath = path.join(targetDir, p.brief);
+        fs.mkdirSync(path.dirname(briefPath), { recursive: true });
+        if (!fs.existsSync(briefPath)) {
+            fs.writeFileSync(briefPath, renderBrief(p.role, { team: name, post: p.id }), 'utf8');
+        }
+    }
+    const specPath = path.join(targetDir, 'team.yaml');
+    fs.writeFileSync(specPath, renderTeamYaml(tpl, { name, repo }), 'utf8');
+    return specPath;
+}
+function registerSpec(deps, spec) {
+    const hash = specHash(spec);
+    deps.registry.upsertTeam({
+        name: spec.name,
+        specPath: spec.specPath,
+        specHash: hash,
+        runId: null,
+        coordinatorHandle: null,
+        status: 'stopped',
+    });
+    for (const p of spec.posts) {
+        deps.registry.upsertPost({
+            address: postAddress(p.id, spec.name),
+            team: spec.name,
+            agent: p.agent,
+            worktree: p.worktree,
+            handle: null,
+            status: 'offline',
+            isLead: p.id === spec.lead,
+            sessionMarker: null,
+            sessionId: null,
+            sessionAt: null,
+        });
+    }
+}
+function initFromTemplate(deps, a) {
+    const name = a.name ?? '';
+    if (!TEAM_NAME_RE.test(name)) {
+        throw new WinglineError('input', 'team_name_invalid', '团队名只能用小写字母、数字与连字符');
+    }
+    const rawRepo = a.repo?.trim() ?? '';
+    if (!rawRepo || /[\x00-\x1f\x7f]/.test(a.repo ?? '')) {
+        throw new WinglineError('input', 'invalid_param', rawRepo ? '代码库目录不能包含控制字符' : '缺少代码库目录');
+    }
+    const tplId = a.template ?? 'duo';
+    const tpl = TEAM_TEMPLATES[tplId];
+    if (!tpl) {
+        throw new WinglineError('input', 'invalid_param', `未知团队模板：${String(tplId)}`);
+    }
+    const targetDir = a.dir ? path.resolve(a.dir) : path.join(deps.home, 'teams', name);
+    const specPath = path.join(targetDir, 'team.yaml');
+    const repo = rawRepo.startsWith('path:') ? rawRepo : `path:${rawRepo}`;
+    const existing = deps.registry.getTeam(name);
+    if (existing) {
+        if (existing.specPath === specPath && fs.existsSync(specPath)) {
+            return { team: name, specPath, created: false };
+        }
+        throw new WinglineError('input', 'team_already_exists', `团队 ${name} 已存在（${existing.specPath}）`);
+    }
+    if (fs.existsSync(specPath)) {
+        throw new WinglineError('input', 'spec_already_exists', `配置文件已存在：${specPath}，请改用“导入已有配置”`);
+    }
+    writeTemplate(targetDir, tpl, name, repo);
+    const spec = loadTeamSpec(specPath);
+    registerSpec(deps, spec);
+    return { team: name, specPath, created: true };
+}
+function initFromImport(deps, a) {
+    const rawPath = a.specPath?.trim() ?? '';
+    if (!rawPath) {
+        throw new WinglineError('input', 'invalid_param', '缺少配置文件路径');
+    }
+    const spec = loadTeamSpec(rawPath);
+    const existing = deps.registry.getTeam(spec.name);
+    if (existing) {
+        if (existing.specPath === spec.specPath) {
+            return { team: spec.name, specPath: spec.specPath, created: false };
+        }
+        throw new WinglineError('input', 'team_already_exists', `同名团队 ${spec.name} 已登记在另一路径：${existing.specPath}`);
+    }
+    registerSpec(deps, spec);
+    return { team: spec.name, specPath: path.resolve(rawPath), created: true };
+}
+export async function initTeamCmd(deps, a) {
+    if (a.mode === 'template')
+        return initFromTemplate(deps, a);
+    if (a.mode === 'import')
+        return initFromImport(deps, a);
+    throw new WinglineError('input', 'invalid_param', `未知初始化模式：${String(a.mode)}`);
+}

package/dist/commands/launch.d.ts

@@ -13,7 +13,16 @@ export declare function recorded<T>(reg: Registry, id: string, fn: () => Promise
     value: T;
 }>;
 export declare const stepDone: (reg: Registry, id: string) => boolean;
-/** 终端被关后重新拉起要换新 id，否则 Orca 会按旧 id 回放旧回执。 */
+/**
+ * 终端被关后重新拉起要换新 id，否则 Orca 会按旧 id 回放旧回执。
+ *
+ * 两段推进：
+ * ① brief 段（原语义，located 时也生效）：create+brief 都 done 才推进——
+ *    at_prompt 拒发后 brief 行缺失，重跑必须复用同一代把 brief 补发。
+ * ② 重启段（仅 !located，终端已消失）：create+wait 都 done 的代整代跳过——
+ *    没有 brief 行的岗位（wait 未确认就中断，brief 从未发生）原来会永远卡在
+ *    「create 已 done 的代」上，beginRequest 撞 request_already_done。
+ */
 export declare function lifetimeGen(l: Launch, post: string, located: boolean): number;
 /** 会话标记 `WLS-` + 8 位小写十六进制；restore 靠它引号精确搜索找回岗位会话（spec §4）。 */
 export declare function newSessionMarker(rand?: () => string): string;

package/dist/commands/launch.js

@@ -21,12 +21,24 @@ export async function recorded(reg, id, fn, ok = () => true) {
     return { confirmed, value };
 }
 export const stepDone = (reg, id) => reg.getRequest(id)?.state === 'done';
-/** 终端被关后重新拉起要换新 id，否则 Orca 会按旧 id 回放旧回执。 */
+/**
+ * 终端被关后重新拉起要换新 id，否则 Orca 会按旧 id 回放旧回执。
+ *
+ * 两段推进：
+ * ① brief 段（原语义，located 时也生效）：create+brief 都 done 才推进——
+ *    at_prompt 拒发后 brief 行缺失，重跑必须复用同一代把 brief 补发。
+ * ② 重启段（仅 !located，终端已消失）：create+wait 都 done 的代整代跳过——
+ *    没有 brief 行的岗位（wait 未确认就中断，brief 从未发生）原来会永远卡在
+ *    「create 已 done 的代」上，beginRequest 撞 request_already_done。
+ */
 export function lifetimeGen(l, post, located) {
     const done = (step, g) => stepDone(l.deps.registry, requestId(l.spec.name, post, step, l.hash, g));
     let g = 0;
     while (done('create', g) && done('brief', g))
         g++;
+    if (!located)
+        while (done('create', g) && done('wait', g))
+            g++;
     if (!located && done('create', g))
         g++;
     return g;

package/dist/commands/spec.d.ts

@@ -1,3 +1,4 @@
+import { type SpecEditOp } from '../spec/edit.js';
 import { type SpecError } from '../spec/load.js';
 import { type SpecPlan } from '../spec/plan-change.js';
 import type { CommandDeps } from './deps.js';
@@ -12,8 +13,9 @@ export interface SpecForEdit {
         hash: string | null;
     } | null;
     running: boolean;
+    files: Record<string, string>;
 }
-/** 编辑器加载：正式规格与草稿（如果有）各给出文本、解析结果与内容哈希。 */
+/** 编辑器加载：正式规格与草稿（如果有）各给出文本、解析结果与内容哈希，附上引用文档的正文。 */
 export declare function readSpecForEdit(deps: CommandDeps, team: string): SpecForEdit;
 export interface SpecEditResult {
     yaml: string;
@@ -21,20 +23,19 @@ export interface SpecEditResult {
     errors: SpecError[];
     preview: SpecPlan | null;
 }
-/** 校验一段 YAML（可先套用表单的一处修改）并预演；不写任何文件。 */
+/** 校验一段 YAML（可先套用编辑页的一处修改）并预演；不写任何文件。`files` 是还没落盘的文档正文。 */
 export declare function validateSpecEdit(deps: CommandDeps, a: {
     team: string;
     yaml: string;
-    set?: {
-        path: Array<string | number>;
-        value: unknown;
-    };
+    set?: SpecEditOp;
+    files?: Record<string, string>;
 }): SpecEditResult;
 export interface SaveSpecArgs {
     team: string;
     yaml: string;
     baseHash: string | null;
     running: boolean;
+    files?: Record<string, string>;
     retryRequest?: string;
 }
 /** 保存规格；两次保存相同内容天然幂等，所以 retryRequest 只是被路由校验格式，这里不用。 */
@@ -42,6 +43,7 @@ export declare function saveSpecCmd(deps: CommandDeps, a: SaveSpecArgs): Promise
     wrote: 'draft' | 'spec';
     path: string;
     hash: string;
+    docsUpdated: string[];
 }>;
 export declare function discardDraftCmd(deps: CommandDeps, a: {
     team: string;

package/dist/commands/spec.js

@@ -1,7 +1,9 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import { WinglineError } from '../errors.js';
-import { discardDraft, draftPathOf, fileHash, assertSpecSize, saveSpec } from '../spec/draft.js';
-import { setField } from '../spec/edit.js';
+import { assertSpecSize, checkSaveConflict, discardDraft, draftPathOf, fileHash, saveSpec } from '../spec/draft.js';
+import { DOC_LIMIT_BYTES, docRelsOf, readDocText, resolveDocPath, writeDocAtomic } from '../spec/doc.js';
+import { applySpecOp } from '../spec/edit.js';
 import { loadTeamSpec, validateSpecText } from '../spec/load.js';
 import { planSpecChange } from '../spec/plan-change.js';
 function teamOf(deps, team) {
@@ -18,7 +20,24 @@ const readText = (file) => {
         throw new WinglineError('input', 'spec_not_found', `读不到团队规格 ${file}`, { cause });
     }
 };
-/** 编辑器加载：正式规格与草稿（如果有）各给出文本、解析结果与内容哈希。 */
+/** 把规格（与草稿）引用的文档正文读出来；解析不了的相对路径跳过，不让整个编辑页打不开。 */
+function readDocs(dir, parseds) {
+    const files = {};
+    for (const parsed of parseds) {
+        for (const rel of docRelsOf(parsed)) {
+            if (rel in files)
+                continue;
+            try {
+                files[rel] = readDocText(resolveDocPath(dir, rel));
+            }
+            catch {
+                // resolveDocPath 拒绝的路径（越界、非 .md）：编辑页照样打开，只是不带这份正文
+            }
+        }
+    }
+    return files;
+}
+/** 编辑器加载：正式规格与草稿（如果有）各给出文本、解析结果与内容哈希，附上引用文档的正文。 */
 export function readSpecForEdit(deps, team) {
     const row = teamOf(deps, team);
     const view = (file) => {
@@ -26,11 +45,14 @@ export function readSpecForEdit(deps, team) {
         return { yaml, parsed: validateSpecText(yaml, row.specPath).parsed, hash: fileHash(file) };
     };
     const draftFile = draftPathOf(row.specPath);
+    const spec = view(row.specPath);
+    const draft = fs.existsSync(draftFile) ? view(draftFile) : null;
     return {
         specPath: row.specPath,
-        ...view(row.specPath),
-        draft: fs.existsSync(draftFile) ? view(draftFile) : null,
+        ...spec,
+        draft,
         running: row.status === 'up',
+        files: readDocs(path.dirname(row.specPath), [spec.parsed, draft?.parsed ?? null]),
     };
 }
 function currentSpec(specPath) {
@@ -43,23 +65,58 @@ function currentSpec(specPath) {
         throw err;
     }
 }
-/** 校验一段 YAML（可先套用表单的一处修改）并预演；不写任何文件。 */
+/** 校验一段 YAML（可先套用编辑页的一处修改）并预演；不写任何文件。`files` 是还没落盘的文档正文。 */
 export function validateSpecEdit(deps, a) {
     const row = teamOf(deps, a.team);
     assertSpecSize(a.yaml);
-    const yaml = a.set ? setField(a.yaml, a.set.path, a.set.value) : a.yaml;
+    // applySpecOp 已把缺省 op 转给 setField，这里不再分叉
+    const yaml = a.set ? applySpecOp(a.yaml, a.set) : a.yaml;
     assertSpecSize(yaml);
-    const { spec, parsed, errors } = validateSpecText(yaml, row.specPath);
+    const { spec, parsed, errors } = validateSpecText(yaml, row.specPath, { virtualFiles: new Set(Object.keys(a.files ?? {})) });
     const preview = spec ? planSpecChange(currentSpec(row.specPath), spec, { running: row.status === 'up', specPath: row.specPath }) : null;
     return { yaml, parsed, errors, preview };
 }
+const docFiles = (files) => {
+    if (files === undefined)
+        return {};
+    if (!files || typeof files !== 'object' || Array.isArray(files) || !Object.values(files).every((v) => typeof v === 'string')) {
+        throw new WinglineError('input', 'invalid_param', '参数 files 不合法');
+    }
+    return files;
+};
+/** 先校验规格、再查冲突（冲突时一个字节都不写）、最后把文档写到磁盘；team.yaml 由随后的 saveSpec 写。 */
+function writeDocs(specPath, yaml, files, a) {
+    const { parsed, errors } = validateSpecText(yaml, specPath, { virtualFiles: new Set(Object.keys(files)) });
+    if (errors.length > 0)
+        throw new WinglineError('input', 'spec_invalid', errors[0].message, { detail: { errors } });
+    checkSaveConflict({ specPath, text: yaml, baseHash: a.baseHash, running: a.running });
+    const referenced = new Set(docRelsOf(parsed));
+    for (const [rel, content] of Object.entries(files)) {
+        if (!referenced.has(rel))
+            throw new WinglineError('input', 'doc_not_referenced', `文档 ${rel} 没有被团队规格引用`);
+        if (Buffer.byteLength(content, 'utf8') > DOC_LIMIT_BYTES) {
+            throw new WinglineError('input', 'doc_too_large', `文档 ${path.basename(rel)} 超过 ${DOC_LIMIT_BYTES / 1024} KB 上限`);
+        }
+    }
+    const dir = path.dirname(specPath);
+    const docsUpdated = [];
+    for (const [rel, content] of Object.entries(files)) {
+        writeDocAtomic(resolveDocPath(dir, rel), content);
+        docsUpdated.push(rel);
+    }
+    return docsUpdated;
+}
 /** 保存规格；两次保存相同内容天然幂等，所以 retryRequest 只是被路由校验格式，这里不用。 */
 export async function saveSpecCmd(deps, a) {
     const row = teamOf(deps, a.team);
     if (a.running !== (row.status === 'up')) {
         throw new WinglineError('input', 'spec_conflict', '团队状态已变化，请重新加载');
     }
-    return saveSpec({ specPath: row.specPath, text: a.yaml, baseHash: a.baseHash, running: a.running });
+    assertSpecSize(a.yaml);
+    const files = docFiles(a.files);
+    const docsUpdated = writeDocs(row.specPath, a.yaml, files, { baseHash: a.baseHash, running: a.running });
+    const res = saveSpec({ specPath: row.specPath, text: a.yaml, baseHash: a.baseHash, running: a.running });
+    return { ...res, docsUpdated };
 }
 export async function discardDraftCmd(deps, a) {
     return discardDraft(teamOf(deps, a.team).specPath);

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

@@ -2,4 +2,5 @@ import type { CommandDeps } from '../deps.js';
 export declare function planTask(deps: CommandDeps, a: {
     id: string;
     text: string;
+    as?: string;
 }): Promise<void>;

package/dist/commands/task/plan.js

@@ -5,7 +5,7 @@ import { preflightTask } from './preflight.js';
 import { findTask } from './query.js';
 export async function planTask(deps, a) {
     const { team } = await preflightTask(deps, a.id);
-    const actor = await resolveActor(deps);
+    const actor = await resolveActor(deps, a.as);
     await deps.registry.withTeamLock(team.name, async () => {
         const task = await findTask(deps, team.name, a.id);
         if (task.status === 'completed' || task.status === 'failed') {

package/dist/commands/templates.d.ts

@@ -0,0 +1,32 @@
+export type TeamTemplateId = 'duo' | 'solo' | 'trio';
+export type RoleKind = 'builder' | 'checker' | 'planner';
+export interface TeamTemplatePost {
+    id: string;
+    role: RoleKind;
+    agent: string;
+    model?: string;
+    launch?: string;
+    brief: string;
+}
+export interface TeamTemplate {
+    id: TeamTemplateId;
+    label: string;
+    summary: string;
+    lead: string;
+    posts: TeamTemplatePost[];
+    links: Record<string, Record<string, string[]>>;
+}
+export declare const TEAM_TEMPLATES: Record<TeamTemplateId, TeamTemplate>;
+export declare const ROLE_BRIEFS: Record<RoleKind, (team: string, post: string) => string>;
+export declare function renderTeamYaml(t: TeamTemplate, a: {
+    name: string;
+    repo: string;
+}): string;
+export declare function renderNorms(a: {
+    team: string;
+    posts: string[];
+}): string;
+export declare function renderBrief(role: RoleKind, a: {
+    team: string;
+    post: string;
+}): string;