@weiping/wingline-core 0.1.1 → 0.2.0

package/dist/server/api-write.js

@@ -5,10 +5,50 @@ import { auditedCommands } from '../audit.js';
 import { send } from '../commands/send.js';
 import { createTask } from '../commands/task/create.js';
 import { escalateTask, recoverTask, resolveGate } from '../commands/task/escalate.js';
-import { reassignTask } from '../commands/task/claim.js';
+import { claimTask, reassignTask, releaseTask } from '../commands/task/claim.js';
+import { planTask } from '../commands/task/plan.js';
+import { startTask } from '../commands/task/start.js';
+import { doneTask } from '../commands/task/done.js';
 import { freezePostCmd, hushCmd, unfreezePostCmd, unhushCmd } from '../commands/dispatcher/controls.js';
+import { dispatcherDown, dispatcherUp } from '../commands/dispatcher/lifecycle.js';
 import { dispatcherReply } from '../commands/dispatcher/inbox.js';
 import { discardDraftCmd, saveSpecCmd } from '../commands/spec.js';
+import { down } from '../commands/down.js';
+import { restore } from '../commands/restore/index.js';
+import { up } from '../commands/up.js';
+import { initTeamCmd } from '../commands/init.js';
+import { autostartInstall, autostartUninstall } from '../commands/autostart/index.js';
+import { realAutostartSys } from '../commands/autostart/sys.js';
+/** 布尔开关：只收 true / false（缺省放行）。字符串 "false" 不再当成真值。 */
+function checkBool(key, val) {
+    if (val !== undefined && typeof val !== 'boolean') {
+        throw new WinglineError('input', 'invalid_param', `参数 ${key}=${val} 不合法`);
+    }
+}
+/** 毫秒数：只收有限数字（缺省放行）。 */
+function checkNumber(key, val) {
+    if (val !== undefined && (typeof val !== 'number' || !Number.isFinite(val))) {
+        throw new WinglineError('input', 'invalid_param', `参数 ${key}=${val} 不合法`);
+    }
+}
+/** 岗位 → 会话 id 的字符串映射：对象、且每个值都是字符串。 */
+function parseSessions(raw) {
+    if (raw === undefined)
+        return undefined;
+    const ok = !!raw && typeof raw === 'object' && !Array.isArray(raw) && Object.values(raw).every((v) => typeof v === 'string');
+    if (!ok)
+        throw new WinglineError('input', 'invalid_param', '参数 sessions 不合法');
+    return raw;
+}
+/** 标签：字符串数组。 */
+function parseTags(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (!Array.isArray(raw) || !raw.every((t) => typeof t === 'string')) {
+        throw new WinglineError('input', 'invalid_param', '参数 tags 不合法');
+    }
+    return raw;
+}
 export const WRITE_ROUTES = [
     {
         pattern: '/api/teams/:team/send',
@@ -16,6 +56,7 @@ export const WRITE_ROUTES = [
         fields: ['post', 'message', 'retryRequest'],
         call: async (cmds, ctx) => {
             checkParam('post', ctx.body.post);
+            checkParam('message', ctx.body.message);
             const address = postAddress(ctx.body.post, ctx.params.team);
             return cmds.send(ctx.deps, { address, message: ctx.body.message, retryRequest: ctx.body.retryRequest });
         },
@@ -26,11 +67,12 @@ export const WRITE_ROUTES = [
         fields: ['title', 'post', 'tags', 'parent', 'retryRequest'],
         call: async (cmds, ctx) => {
             const { title, post, tags, parent, retryRequest } = ctx.body;
-            if (post)
+            checkParam('title', title);
+            if (post !== undefined)
                 checkParam('post', post);
-            if (parent)
+            if (parent !== undefined)
                 checkParam('id', parent);
-            return cmds.createTask(ctx.deps, { team: ctx.params.team, title, post: post ? postAddress(post, ctx.params.team) : undefined, tags, parent, retryRequest });
+            return cmds.createTask(ctx.deps, { team: ctx.params.team, title, post: post ? postAddress(post, ctx.params.team) : undefined, tags: parseTags(tags), parent, retryRequest });
         },
     },
     {
@@ -39,6 +81,8 @@ export const WRITE_ROUTES = [
         fields: ['reason', 'reopen', 'retryRequest'],
         call: async (cmds, ctx) => {
             const { reason, reopen, retryRequest } = ctx.body;
+            checkParam('reason', reason);
+            checkBool('reopen', reopen);
             return cmds.escalateTask(ctx.deps, { id: ctx.params.id, reason, reopen, retryRequest });
         },
     },
@@ -60,14 +104,50 @@ export const WRITE_ROUTES = [
         fields: ['retryRequest'],
         call: async (cmds, ctx) => cmds.recoverTask(ctx.deps, { id: ctx.params.id }),
     },
+    {
+        pattern: '/api/teams/:team/tasks/:id/claim',
+        check: ['team', 'id'],
+        fields: ['as', 'retryRequest'],
+        call: async (cmds, ctx) => cmds.claimTask(ctx.deps, { id: ctx.params.id, as: actorOf(ctx) }),
+    },
+    {
+        pattern: '/api/teams/:team/tasks/:id/release',
+        check: ['team', 'id'],
+        fields: ['as', 'retryRequest'],
+        call: async (cmds, ctx) => cmds.releaseTask(ctx.deps, { id: ctx.params.id, as: actorOf(ctx) }),
+    },
+    {
+        pattern: '/api/teams/:team/tasks/:id/plan',
+        check: ['team', 'id'],
+        fields: ['as', 'text', 'retryRequest'],
+        call: async (cmds, ctx) => {
+            const { text } = ctx.body;
+            if (typeof text !== 'string' || !text.trim())
+                throw new WinglineError('input', 'invalid_param', '参数 text 不合法');
+            return cmds.planTask(ctx.deps, { id: ctx.params.id, as: actorOf(ctx), text });
+        },
+    },
+    {
+        pattern: '/api/teams/:team/tasks/:id/start',
+        check: ['team', 'id'],
+        fields: ['as', 'retryRequest'],
+        call: async (cmds, ctx) => cmds.startTask(ctx.deps, { id: ctx.params.id, as: actorOf(ctx) }),
+    },
+    {
+        pattern: '/api/teams/:team/tasks/:id/done',
+        check: ['team', 'id'],
+        fields: ['as', 'retryRequest'],
+        call: async (cmds, ctx) => cmds.doneTask(ctx.deps, { id: ctx.params.id, as: actorOf(ctx) }),
+    },
     {
         pattern: '/api/teams/:team/gates/:gateId/resolve',
         check: ['team', 'gateId'],
         fields: ['resolution', 'reassign', 'retryRequest'],
         call: async (cmds, ctx) => {
             const { resolution, reassign } = ctx.body;
-            if (reassign !== undefined && typeof reassign !== 'string')
-                checkParam('post', reassign);
+            checkParam('resolution', resolution);
+            if (reassign !== undefined)
+                checkParam('reassign', reassign);
             const target = reassign ? (reassign.includes('@') ? reassign : (checkParam('post', reassign), postAddress(reassign, ctx.params.team))) : undefined;
             return cmds.resolveGate(ctx.deps, { gateId: ctx.params.gateId, resolution, reassign: target });
         },
@@ -76,7 +156,10 @@ export const WRITE_ROUTES = [
         pattern: '/api/teams/:team/posts/:post/freeze',
         check: ['team', 'post'],
         fields: ['reason', 'retryRequest'],
-        call: async (cmds, ctx) => cmds.freezePostCmd(ctx.deps, { address: postAddress(ctx.params.post, ctx.params.team), reason: ctx.body.reason }),
+        call: async (cmds, ctx) => {
+            checkParam('reason', ctx.body.reason);
+            return cmds.freezePostCmd(ctx.deps, { address: postAddress(ctx.params.post, ctx.params.team), reason: ctx.body.reason });
+        },
     },
     {
         pattern: '/api/teams/:team/posts/:post/unfreeze',
@@ -88,7 +171,10 @@ export const WRITE_ROUTES = [
         pattern: '/api/teams/:team/posts/:post/hush',
         check: ['team', 'post'],
         fields: ['forMs', 'retryRequest'],
-        call: async (cmds, ctx) => cmds.hushCmd(ctx.deps, { address: postAddress(ctx.params.post, ctx.params.team), forMs: ctx.body.forMs }),
+        call: async (cmds, ctx) => {
+            checkNumber('forMs', ctx.body.forMs);
+            return cmds.hushCmd(ctx.deps, { address: postAddress(ctx.params.post, ctx.params.team), forMs: ctx.body.forMs });
+        },
     },
     {
         pattern: '/api/teams/:team/posts/:post/unhush',
@@ -102,21 +188,23 @@ export const WRITE_ROUTES = [
         fields: ['body', 'again', 'retryRequest'],
         call: async (cmds, ctx) => {
             const { body, again } = ctx.body;
+            checkParam('body', body);
+            checkBool('again', again);
             return cmds.dispatcherReply(ctx.deps, { team: ctx.params.team, messageId: ctx.params.messageId, body, again });
         },
     },
     {
         pattern: '/api/teams/:team/spec',
         check: ['team'],
-        fields: ['yaml', 'baseHash', 'running', 'retryRequest'],
+        fields: ['yaml', 'baseHash', 'running', 'files', 'retryRequest'],
         call: async (cmds, ctx) => {
-            const { yaml, baseHash, running } = ctx.body;
+            const { yaml, baseHash, running, files } = ctx.body;
             checkParam('yaml', yaml);
             if (baseHash !== null)
                 checkParam('baseHash', baseHash);
             if (typeof running !== 'boolean')
                 throw new WinglineError('input', 'invalid_param', '参数 running 不合法');
-            return cmds.saveSpecCmd(ctx.deps, { team: ctx.params.team, yaml, baseHash, running });
+            return cmds.saveSpecCmd(ctx.deps, { team: ctx.params.team, yaml, baseHash, running, files });
         },
     },
     {
@@ -125,8 +213,102 @@ export const WRITE_ROUTES = [
         fields: ['retryRequest'],
         call: async (cmds, ctx) => cmds.discardDraftCmd(ctx.deps, { team: ctx.params.team }),
     },
+    {
+        pattern: '/api/teams/:team/up',
+        check: ['team'],
+        fields: ['draft', 'newRun', 'adoptRun', 'retryRequest'],
+        call: async (cmds, ctx) => {
+            const { draft, newRun, adoptRun } = ctx.body;
+            checkBool('draft', draft);
+            checkBool('newRun', newRun);
+            if (adoptRun !== undefined)
+                checkParam('adoptRun', adoptRun);
+            return cmds.up(ctx.deps, { team: ctx.params.team, draft, newRun, adoptRun });
+        },
+    },
+    {
+        pattern: '/api/teams/:team/down',
+        check: ['team'],
+        fields: ['close', 'retryRequest'],
+        call: async (cmds, ctx) => {
+            checkBool('close', ctx.body.close);
+            return cmds.down(ctx.deps, { team: ctx.params.team, close: !!ctx.body.close });
+        },
+    },
+    {
+        pattern: '/api/teams/:team/restore',
+        check: ['team'],
+        fields: ['dryRun', 'noTasks', 'sessions', 'retryRequest'],
+        call: async (cmds, ctx) => {
+            const { dryRun, noTasks } = ctx.body;
+            checkBool('dryRun', dryRun);
+            checkBool('noTasks', noTasks);
+            return cmds.restore(ctx.deps, { team: ctx.params.team, dryRun: !!dryRun, noTasks: !!noTasks, sessions: parseSessions(ctx.body.sessions) });
+        },
+    },
+    {
+        pattern: '/api/teams/:team/dispatcher/up',
+        check: ['team'],
+        fields: ['retryRequest'],
+        call: async (cmds, ctx) => cmds.dispatcherUp(ctx.deps, { team: ctx.params.team }),
+    },
+    {
+        pattern: '/api/teams/:team/dispatcher/down',
+        check: ['team'],
+        fields: ['close', 'retryRequest'],
+        call: async (cmds, ctx) => {
+            checkBool('close', ctx.body.close);
+            return cmds.dispatcherDown(ctx.deps, { team: ctx.params.team, close: ctx.body.close ?? true });
+        },
+    },
+    {
+        pattern: '/api/teams',
+        check: [],
+        fields: ['mode', 'name', 'repo', 'template', 'dir', 'specPath', 'retryRequest'],
+        call: async (cmds, ctx) => {
+            const { mode, name, repo, template, dir, specPath } = ctx.body;
+            if (mode !== 'template' && mode !== 'import')
+                throw new WinglineError('input', 'invalid_param', '参数 mode 不合法');
+            for (const key of ['name', 'repo', 'template', 'dir', 'specPath']) {
+                if (ctx.body[key] !== undefined)
+                    checkParam(key, ctx.body[key]);
+            }
+            return cmds.initTeamCmd(ctx.deps, { mode, name, repo, template, dir, specPath });
+        },
+    },
+    {
+        pattern: '/api/autostart/install',
+        check: [],
+        fields: ['waitOrca', 'retryRequest'],
+        call: async (cmds, ctx) => {
+            if (ctx.body.waitOrca !== undefined)
+                checkParam('waitOrca', ctx.body.waitOrca);
+            return cmds.autostartInstall(ctx.deps, { waitOrca: ctx.body.waitOrca });
+        },
+    },
+    {
+        pattern: '/api/autostart/uninstall',
+        check: [],
+        fields: ['retryRequest'],
+        call: async (cmds, ctx) => cmds.autostartUninstall(ctx.deps),
+    },
 ];
 const ofAddress = (a) => a.address.split('@')[1] ?? '-';
+/** 任务执行流的执行者：必填；不带 @ 时按本团队岗位解释，带 @ 时团队后缀必须一致。 */
+function actorOf(ctx) {
+    const raw = ctx.body.as;
+    if (typeof raw !== 'string' || !raw.trim())
+        throw new WinglineError('input', 'invalid_param', '参数 as 不合法');
+    if (!raw.includes('@')) {
+        checkParam('post', raw);
+        return postAddress(raw, ctx.params.team);
+    }
+    const [post, team] = raw.split('@');
+    checkParam('post', post);
+    if (team !== ctx.params.team)
+        throw new WinglineError('input', 'invalid_param', '执行者不属于该团队');
+    return raw;
+}
 const byTask = (idOf) => (_a, ctx) => ctx.deps.registry.getTaskExt(idOf(_a))?.team ?? '-';
 const byGate = (gateId) => (_a, ctx) => ctx.deps.registry.getGate(gateId(_a))?.team ?? '-';
 export const CONSOLE_AUDIT = {
@@ -165,6 +347,36 @@ export const CONSOLE_AUDIT = {
         target: (a) => a.gateId,
         summary: (a) => ({ resolution: a.resolution, reassign: a.reassign }),
     },
+    claimTask: {
+        command: 'task claim',
+        team: byTask((a) => a.id),
+        target: (a) => a.id,
+        summary: (a) => ({ as: a.as }),
+    },
+    releaseTask: {
+        command: 'task release',
+        team: byTask((a) => a.id),
+        target: (a) => a.id,
+        summary: (a) => ({ as: a.as }),
+    },
+    planTask: {
+        command: 'task plan',
+        team: byTask((a) => a.id),
+        target: (a) => a.id,
+        summary: (a) => ({ as: a.as, text: a.text }),
+    },
+    startTask: {
+        command: 'task start',
+        team: byTask((a) => a.id),
+        target: (a) => a.id,
+        summary: (a) => ({ as: a.as }),
+    },
+    doneTask: {
+        command: 'task done',
+        team: byTask((a) => a.id),
+        target: (a) => a.id,
+        summary: (a) => ({ as: a.as }),
+    },
     freezePostCmd: {
         command: 'dispatcher freeze',
         team: ofAddress,
@@ -209,8 +421,48 @@ export const CONSOLE_AUDIT = {
         team: (a) => a.team,
         summary: (_a, ctx) => ({ discarded: ctx.result?.discarded }),
     },
+    up: {
+        command: 'up',
+        team: (a) => a.team,
+        summary: (a) => ({ draft: a.draft, newRun: a.newRun, adoptRun: a.adoptRun }),
+    },
+    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 ?? {}) }),
+    },
+    dispatcherUp: {
+        command: 'dispatcher up',
+        team: (a) => a.team,
+    },
+    dispatcherDown: {
+        command: 'dispatcher down',
+        team: (a) => a.team,
+        summary: (a) => ({ close: a.close }),
+    },
+    initTeamCmd: {
+        command: 'init',
+        // 新建团队没有 :team 路径参数：团队名从结果里取
+        team: (_a, ctx) => ctx.result?.team ?? '-',
+        summary: (a, ctx) => ({ mode: a.mode, template: a.template, created: ctx.result?.created }),
+    },
+    autostartInstall: {
+        command: 'autostart install',
+        team: () => '-',
+        summary: (a) => ({ waitOrca: a.waitOrca }),
+    },
+    autostartUninstall: {
+        command: 'autostart uninstall',
+        team: () => '-',
+    },
 };
-/** 控制台用 `console:`，TUI 用 `tui:`；两者共用同一张审计表，执行者都是 human。 */
+/** 控制台用 `console:`，TUI 用 `tui:`，Orca 插件用 `plugin:`；三者共用同一张审计表，执行者都是 human。 */
 export function auditedWriteCommands(prefix) {
     const raw = {
         send,
@@ -219,6 +471,12 @@ export function auditedWriteCommands(prefix) {
         reassignTask,
         recoverTask,
         resolveGate,
+        // 任务执行流：控制台口径只透传 id/as（+plan 的 text），resumeEpoch 等其余参数不暴露
+        claimTask: (deps, a) => claimTask(deps, { id: a.id, as: a.as }),
+        releaseTask: (deps, a) => releaseTask(deps, { id: a.id, as: a.as }),
+        planTask: (deps, a) => planTask(deps, { id: a.id, as: a.as, text: a.text }),
+        startTask: (deps, a) => startTask(deps, { id: a.id, as: a.as }),
+        doneTask: (deps, a) => doneTask(deps, { id: a.id, as: a.as }),
         freezePostCmd,
         unfreezePostCmd,
         hushCmd,
@@ -226,6 +484,21 @@ export function auditedWriteCommands(prefix) {
         dispatcherReply,
         saveSpecCmd,
         discardDraftCmd,
+        // core 的 up 吃 specPath，控制台给的是 team 名：包装层先查注册表换算
+        up: async (deps, a) => {
+            const row = deps.registry.getTeam(a.team);
+            if (!row)
+                throw new WinglineError('input', 'team_unknown', `团队 ${a.team} 未登记`);
+            return up(deps, { specPath: row.specPath, draft: a.draft, newRun: a.newRun, adoptRun: a.adoptRun });
+        },
+        down: (deps, a) => down(deps, { team: a.team, close: !!a.close }),
+        restore: (deps, a) => restore(deps, { team: a.team, dryRun: !!a.dryRun, noTasks: !!a.noTasks, sessions: a.sessions }),
+        dispatcherUp: (deps, a) => dispatcherUp(deps, { team: a.team, node: a.node, script: a.script }),
+        dispatcherDown: (deps, a) => dispatcherDown(deps, { team: a.team, close: a.close ?? true }),
+        initTeamCmd,
+        // 系统宿主（launchd/systemd）只有真实执行时才能取：默认 realAutostartSys，测试经 cmds 注入替换
+        autostartInstall: (deps, a) => autostartInstall(deps, realAutostartSys(), { waitOrca: a.waitOrca }),
+        autostartUninstall: (deps) => autostartUninstall(deps, realAutostartSys()),
     };
     return auditedCommands(raw, CONSOLE_AUDIT, { prefix, actor: 'human' });
 }

package/dist/server/index.js

@@ -71,11 +71,11 @@ function respondError(res, err, warn, where) {
 }
 const BODY_LIMIT = 64 * 1024;
 /**
- * 规格的 yaml 字段上限是 48 KB（按 UTF-8 字节），但 JSON 里换行等要转义，最坏每字节变 2 到 6 字节，
- * 所以保存 / 校验规格的请求体不能套 64 KB 的通用上限，否则 40 KB 出头的 yaml 会先撞 413。
- * 超过 48 KB 的 yaml 由 spec_too_large 拒绝；这里的上限只防止读入无限大的请求体。
+ * 规格编辑接口的请求体：规格 48 KB + 若干份 64 KB 以内的 .md 文档，JSON 转义后最坏再放大几倍，
+ * 所以不能套 64 KB 的通用上限。超过各自上限由 spec_too_large / doc_too_large 拒绝；
+ * 这里的 512 KB 只防止读入无限大的请求体。
  */
-const SPEC_BODY_LIMIT = 48 * 1024 * 6 + 4096;
+const SPEC_BODY_LIMIT = 512 * 1024;
 const SPEC_BODY_ROUTE = /^\/api\/teams\/[^/]+\/spec(?:\/validate)?$/;
 const bodyLimitFor = (pathname) => (SPEC_BODY_ROUTE.test(pathname) ? SPEC_BODY_LIMIT : BODY_LIMIT);
 /**

package/dist/spec/doc.d.ts

@@ -0,0 +1,13 @@
+export declare const DOC_LIMIT_BYTES: number;
+/**
+ * 控制台只允许写团队目录里被规格引用的 .md。路径来自不可信的请求体：
+ * 绝对路径、`..` 越界、非 .md、含 \0、软链接指向目录外，一律拒绝。
+ * shortcut: 新建文件时穿过本身是软链接的父目录不在检查之列（规格引用校验已把可写范围限到团队目录）
+ */
+export declare function resolveDocPath(specDir: string, rel: string): string;
+/** 读文档正文；读不到（还没落盘、被删掉）一律返回空串，让编辑器拿到一个可编辑的初值。 */
+export declare function readDocText(abs: string): string;
+/** 原子写文档（照 saveSpec 的 writeAtomic：临时文件 + 改名，继承已有文件的权限位），并建出缺失的父目录。 */
+export declare function writeDocAtomic(abs: string, content: string): void;
+/** 从原始 YAML 对象里取 norms 与 posts[*].brief 引用的相对路径（去重）；不是对象就返回空。 */
+export declare function docRelsOf(parsed: unknown): string[];

package/dist/spec/doc.js

@@ -0,0 +1,62 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { WinglineError } from '../errors.js';
+import { writeAtomic } from './draft.js';
+export const DOC_LIMIT_BYTES = 64 * 1024;
+/**
+ * 控制台只允许写团队目录里被规格引用的 .md。路径来自不可信的请求体：
+ * 绝对路径、`..` 越界、非 .md、含 \0、软链接指向目录外，一律拒绝。
+ * shortcut: 新建文件时穿过本身是软链接的父目录不在检查之列（规格引用校验已把可写范围限到团队目录）
+ */
+export function resolveDocPath(specDir, rel) {
+    const bad = () => new WinglineError('input', 'doc_path_invalid', `文档路径 ${rel} 必须位于团队目录内且为 .md 文件`);
+    if (typeof rel !== 'string' || rel === '' || !rel.endsWith('.md') || rel.includes('\0'))
+        throw bad();
+    const abs = path.resolve(specDir, rel.replace(/\\/g, '/'));
+    const within = path.relative(specDir, abs);
+    if (within === '' || within.startsWith('..') || path.isAbsolute(within))
+        throw bad();
+    // 已存在的路径可能是软链接：解析后的真实位置必须仍在真实团队目录内
+    if (fs.existsSync(abs)) {
+        const real = path.relative(fs.realpathSync(specDir), fs.realpathSync(abs));
+        if (real === '' || real.startsWith('..') || path.isAbsolute(real))
+            throw bad();
+    }
+    return abs;
+}
+/** 读文档正文；读不到（还没落盘、被删掉）一律返回空串，让编辑器拿到一个可编辑的初值。 */
+export function readDocText(abs) {
+    try {
+        return fs.readFileSync(abs, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/** 原子写文档（照 saveSpec 的 writeAtomic：临时文件 + 改名，继承已有文件的权限位），并建出缺失的父目录。 */
+export function writeDocAtomic(abs, content) {
+    if (Buffer.byteLength(content, 'utf8') > DOC_LIMIT_BYTES) {
+        throw new WinglineError('input', 'doc_too_large', `文档 ${path.basename(abs)} 超过 ${DOC_LIMIT_BYTES / 1024} KB 上限`);
+    }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    writeAtomic(abs, content);
+}
+/** 从原始 YAML 对象里取 norms 与 posts[*].brief 引用的相对路径（去重）；不是对象就返回空。 */
+export function docRelsOf(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return [];
+    const raw = parsed;
+    const rels = new Set();
+    if (typeof raw.norms === 'string')
+        rels.add(raw.norms);
+    if (Array.isArray(raw.posts)) {
+        for (const post of raw.posts) {
+            const brief = post?.brief;
+            if (Array.isArray(brief))
+                for (const b of brief)
+                    if (typeof b === 'string')
+                        rels.add(b);
+        }
+    }
+    return [...rels];
+}

package/dist/spec/draft.d.ts

@@ -3,7 +3,23 @@ export declare const SPEC_MAX_BYTES: number;
 export declare function draftPathOf(specPath: string): string;
 export declare const textHash: (text: string) => string;
 export declare function fileHash(file: string): string | null;
+/**
+ * 先写同目录临时文件再改名，避免留下半截文件。改名会换掉文件本身，所以：
+ * 符号链接要写到它指向的真实文件上（链接保持链接），已有文件的权限位要带过去。
+ */
+export declare function writeAtomic(link: string, text: string): void;
 export declare function assertSpecSize(text: string): void;
+/** 保存前的冲突检查：目标文件当前内容既不等于新内容、也不等于加载时的 baseHash 时抛 spec_conflict。 */
+export declare function checkSaveConflict(a: {
+    specPath: string;
+    text: string;
+    baseHash: string | null;
+    running: boolean;
+}): {
+    target: string;
+    hash: string;
+    skip: boolean;
+};
 /** 保存规格：团队运行中写草稿，否则写正式规格。`running` 与注册表是否一致由调用方检查。 */
 export declare function saveSpec(a: {
     specPath: string;

package/dist/spec/draft.js

@@ -44,7 +44,7 @@ function modeOf(file) {
  * 先写同目录临时文件再改名，避免留下半截文件。改名会换掉文件本身，所以：
  * 符号链接要写到它指向的真实文件上（链接保持链接），已有文件的权限位要带过去。
  */
-function writeAtomic(link, text) {
+export function writeAtomic(link, text) {
     const file = realTarget(link);
     const tmp = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.tmp`);
     try {
@@ -64,6 +64,17 @@ export function assertSpecSize(text) {
         throw new WinglineError('input', 'spec_too_large', `规格超过 ${SPEC_MAX_BYTES / 1024} KB`);
     }
 }
+/** 保存前的冲突检查：目标文件当前内容既不等于新内容、也不等于加载时的 baseHash 时抛 spec_conflict。 */
+export function checkSaveConflict(a) {
+    const target = a.running ? draftPathOf(a.specPath) : a.specPath;
+    const hash = textHash(a.text);
+    const current = fileHash(target);
+    if (current === hash)
+        return { target, hash, skip: true };
+    if (current !== a.baseHash)
+        throw new WinglineError('input', 'spec_conflict', `${path.basename(target)} 在加载后被改动过，请重新加载`);
+    return { target, hash, skip: false };
+}
 /** 保存规格：团队运行中写草稿，否则写正式规格。`running` 与注册表是否一致由调用方检查。 */
 export function saveSpec(a) {
     assertSpecSize(a.text);
@@ -71,14 +82,10 @@ export function saveSpec(a) {
     if (errors.length > 0) {
         throw new WinglineError('input', 'spec_invalid', errors[0].message, { detail: { errors } });
     }
-    const target = a.running ? draftPathOf(a.specPath) : a.specPath;
-    const result = { wrote: a.running ? 'draft' : 'spec', path: target, hash: textHash(a.text) };
-    const current = fileHash(target);
-    if (current === result.hash)
+    const { target, hash, skip } = checkSaveConflict(a);
+    const result = { wrote: a.running ? 'draft' : 'spec', path: target, hash };
+    if (skip)
         return result;
-    if (current !== a.baseHash) {
-        throw new WinglineError('input', 'spec_conflict', `${path.basename(target)} 在加载后被改动过，请重新加载`);
-    }
     writeAtomic(target, a.text);
     return result;
 }

package/dist/spec/edit.d.ts

@@ -1,4 +1,25 @@
 type Path = Array<string | number>;
 /** 把表单的一处修改写回 YAML：`value === null` 删除该字段。 */
 export declare function setField(text: string, path: Path, value: unknown): string;
+type SpecPost = {
+    id: string;
+    agent: string;
+    model?: string;
+    launch?: string;
+    worktree?: string;
+    brief?: string[];
+};
+export type SpecEditOp = {
+    op?: 'set';
+    path: Path;
+    value: unknown;
+} | {
+    op: 'add_post';
+    post: SpecPost;
+} | {
+    op: 'remove_post';
+    index: number;
+};
+/** 把团队编辑页的一处规格修改写回 YAML：op 缺省是 set（等价 setField），add_post / remove_post 增删岗位。 */
+export declare function applySpecOp(text: string, op: SpecEditOp): string;
 export {};