@birdie_moblie/open_spec 2.1.7 → 2.2.0

package/dist/index.js

@@ -1,10 +1,10 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { stringify as stringifyYaml } from 'yaml';
 import { appendText, exists, writeText, ensureDir, writeJson } from './shared/fs.js';
-import { findProjectRoot, loadConfig, saveConfig, defaultConfig, configPathOf } from './config/load.js';
-import { keptMarketplaceRefs, listPresets, loadPreset, mergePreset, scaffoldPreset } from './config/presets.js';
+import { findProjectRoot, loadConfig, loadProjectConfig, saveConfig, defaultConfig, configPathOf } from './config/load.js';
+import { usePreset } from './config/preset-use.js';
 import { effectiveTaskCategories } from './config/schema.js';
+import { syncPresetCache } from './config/preset-repo.js';
 import { createChange, listChangeNames, requireChange, resolveChangeName } from './core/change.js';
 import { nextAction } from './core/flow.js';
 import { buildInstructions } from './core/instructions.js';
@@ -36,39 +36,33 @@ export function initProject(input) {
     ensureDir(resolveInside(projectRoot, path.posix.join(OPENSPEC_DIR, 'changes'), 'openspec_path_outside_project'));
     ensureDir(resolveInside(projectRoot, path.posix.join(OPENSPEC_DIR, 'archive'), 'openspec_path_outside_project'));
     const hadConfig = Boolean(configPathOf(projectRoot));
-    let config = hadConfig ? loadConfig(projectRoot) : defaultConfig();
+    let config = hadConfig ? loadProjectConfig(projectRoot) : defaultConfig();
     if (input.tools !== undefined)
         config = { ...config, tools: input.tools };
+    if (config.preset && !input.preset) {
+        progress(`同步 preset ${config.preset.id}（${config.preset.ref}）`);
+        syncPresetCache(projectRoot, config.preset);
+    }
+    const rewriteConfig = !hadConfig || input.tools !== undefined;
+    if (rewriteConfig)
+        saveConfig(projectRoot, config);
     if (input.preset) {
-        progress(`应用 preset ${input.preset}`);
-        const preset = loadPreset(input.preset);
-        for (const kept of keptMarketplaceRefs(config, preset)) {
-            progress(`  保留宿主 marketplace ${kept.name}@${kept.ref.slice(0, 12)}（preset 基线 ${kept.presetRef.slice(0, 12)}）`);
-        }
-        config = mergePreset(config, preset);
-        scaffold = scaffoldPreset(projectRoot, preset);
+        progress(`引用 preset ${input.preset.id}（${input.preset.ref}）`);
+        scaffold = usePreset({ projectRoot, ...input.preset }).scaffold;
+        config = loadProjectConfig(projectRoot);
         for (const item of scaffold) {
             progress(item.status === 'created' ? `  生成 ${item.path}（模板，需填写）` : `  保留已有 ${item.path}`);
         }
-        const lockedMarketplaces = (preset.marketplaces ?? []).map((item) => requireImmutableMarketplace(item));
-        writeText(resolveInside(projectRoot, path.posix.join(OPENSPEC_DIR, 'preset-lock.yaml'), 'preset_lock_outside_project'), stringifyYaml({
-            schemaVersion: preset.schemaVersion,
-            id: preset.id,
-            version: preset.version,
-            marketplaces: lockedMarketplaces,
-            plugins: preset.plugins ?? [],
-        }, { lineWidth: 0 }));
     }
-    const presetPlugins = config.plugins ?? [];
-    const presetMarketplaces = (config.marketplaces ?? []).map((item) => requireImmutableMarketplace(item));
-    const rewriteConfig = !hadConfig || input.tools !== undefined || Boolean(input.preset);
-    if (rewriteConfig)
-        saveConfig(projectRoot, config);
+    // 插件与宿主按生效配置安装：preset 基线声明的插件也要装上。
+    const effective = loadConfig(projectRoot);
+    const presetPlugins = effective.plugins ?? [];
+    const presetMarketplaces = (effective.marketplaces ?? []).map((item) => requireImmutableMarketplace(item));
     writeInstallCli(projectRoot, VERSION, PACKAGE_NAME);
     appendGitignore(projectRoot);
-    const hosts = config.tools ?? [];
+    const hosts = effective.tools ?? [];
     const mode = input.skipPlugins ? 'skip' : input.yes ? 'install' : 'pending';
-    progress(rewriteConfig
+    progress(rewriteConfig || input.preset
         ? `写入 openspec/config.yaml 与 install-cli.mjs`
         : `刷新 install-cli.mjs 与宿主交付（保留已有 config.yaml）`);
     if (hosts.length > 0)
@@ -120,7 +114,7 @@ export function initProject(input) {
         if (pluginInstalls.length > 0)
             writeInstallReceipt(projectRoot, pluginInstalls);
         // 入口在安装时就解析一遍；marketplace 未锁定已在上面记为 issue，不重复记。
-        for (const entry of inspectHookEntries(projectRoot, config)) {
+        for (const entry of inspectHookEntries(projectRoot, effective)) {
             if (!entry.ok && entry.code !== 'marketplace_not_locked') {
                 issues.push({ scope: `entry:${entry.hook}`, error: `${entry.code}: ${entry.error}` });
             }
@@ -154,7 +148,7 @@ export function initProject(input) {
     });
     return result;
 }
-export { createChange, listChangeNames, requireChange, resolveChangeName, nextAction, buildInstructions, addSources, collect, abortUpdate, parseSourceArg, parseSourceFileArg, createWorker, acceptWorker, answerWorker, cancelWorker, approveGate, rejectGate, isKnownGate, runVerifyCommands, recordEvidence, writeReport, renderReportMarkdown, requestFix, changedFilesFromState, archiveChange, collectPendingWork, renderPendingWork, listPresets, loadPreset, addMarketplace, listMarketplaces, installPlugin, verifyDelivery, verifyInstallCli, effectiveTaskCategories, BUILTIN_MARKETPLACE, assertPluginsPresent, inspectMarketplaceDependencies, inspectHookEntries, };
+export { createChange, listChangeNames, requireChange, resolveChangeName, nextAction, buildInstructions, addSources, collect, abortUpdate, parseSourceArg, parseSourceFileArg, createWorker, acceptWorker, answerWorker, cancelWorker, approveGate, rejectGate, isKnownGate, runVerifyCommands, recordEvidence, writeReport, renderReportMarkdown, requestFix, changedFilesFromState, archiveChange, collectPendingWork, renderPendingWork, addMarketplace, listMarketplaces, installPlugin, verifyDelivery, verifyInstallCli, effectiveTaskCategories, BUILTIN_MARKETPLACE, assertPluginsPresent, inspectMarketplaceDependencies, inspectHookEntries, };
 function appendGitignore(projectRoot) {
     const file = resolveInside(projectRoot, '.gitignore', 'gitignore_outside_project');
     const entries = [

package/dist/marketplace/registry.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { isImmutableRef } from '../shared/git-snapshot.js';
 declare const RecordSchema: z.ZodObject<{
     name: z.ZodString;
     repo: z.ZodOptional<z.ZodString>;
@@ -66,6 +67,5 @@ export declare function inspectMarketplaceDependencies(projectRoot: string, mark
     marketplace: string;
     minVersion?: string;
 }>): DependencyCheck[];
-export declare function isImmutableRef(ref: string): boolean;
-export {};
+export { isImmutableRef };
 //# sourceMappingURL=registry.d.ts.map

package/dist/marketplace/registry.js

@@ -2,9 +2,9 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { renameSync } from 'node:fs';
 import { z } from 'zod';
-import { execFile } from '../shared/exec.js';
 import { copyPath, ensureDir, exists, readJson, removePath, writeJson } from '../shared/fs.js';
 import { digestDirectory } from '../shared/hash.js';
+import { isImmutableRef, snapshotGitRef } from '../shared/git-snapshot.js';
 import { AppError } from '../shared/errors.js';
 import { resolveInside } from '../shared/paths.js';
 import { compareVersions } from '../shared/version.js';
@@ -223,57 +223,10 @@ function addGitMarketplace(input) {
             return { name, repo, ref, resolvedSha: ref, digest: digestDirectory(cached), cachePath: cached };
         }
     }
-    ensureDir(marketplaceCacheRoot());
-    const temporary = resolveInside(marketplaceCacheRoot(), `.clone-${name}-${randomUUID()}`, 'marketplace_cache_outside_home');
-    try {
-        fetchImmutableRef(repo, ref, temporary);
-        const checkout = execFile('git', ['checkout', '--detach', 'FETCH_HEAD'], { cwd: temporary });
-        if (!checkout.ok)
-            throw new AppError('marketplace_checkout_failed', checkout.stderr || checkout.stdout);
-        const resolved = execFile('git', ['rev-parse', 'HEAD'], { cwd: temporary });
-        if (!resolved.ok)
-            throw new AppError('marketplace_revision_failed', resolved.stderr || resolved.stdout);
-        const resolvedSha = resolved.stdout.trim();
-        removePath(path.join(temporary, '.git'));
-        const cachePath = marketplaceCacheDir(name, resolvedSha);
-        if (exists(cachePath))
-            removePath(temporary);
-        else {
-            ensureDir(path.dirname(cachePath));
-            renameSync(temporary, cachePath);
-        }
-        return { name, repo, ref, resolvedSha, digest: digestDirectory(cachePath), cachePath };
-    }
-    finally {
-        if (exists(temporary))
-            removePath(temporary);
-    }
-}
-/** 网络操作给足时间，且禁止 git 等待终端输入（否则会静默挂到超时）。 */
-const GIT_NETWORK_OPTIONS = { timeoutMs: 300_000, env: { GIT_TERMINAL_PROMPT: '0' } };
-/**
- * 只拉取不可变 ref 指向的那一个提交：init + remote add + fetch --depth 1。
- * 服务端不允许按 SHA 拉取时回退为完整 clone 后再 fetch。
- */
-function fetchImmutableRef(repo, ref, temporary) {
-    ensureDir(temporary);
-    const init = execFile('git', ['init', '-q'], { cwd: temporary });
-    if (!init.ok)
-        throw new AppError('marketplace_clone_failed', `git init 失败: ${init.stderr || init.stdout}`);
-    const remote = execFile('git', ['remote', 'add', 'origin', repo], { cwd: temporary });
-    if (!remote.ok)
-        throw new AppError('marketplace_clone_failed', `git remote add 失败: ${remote.stderr || remote.stdout}`);
-    const shallow = execFile('git', ['fetch', '--depth', '1', 'origin', ref], { cwd: temporary, ...GIT_NETWORK_OPTIONS });
-    if (shallow.ok)
-        return;
-    removePath(temporary);
-    const clone = execFile('git', ['clone', '--no-checkout', repo, temporary], { cwd: path.dirname(temporary), ...GIT_NETWORK_OPTIONS });
-    if (!clone.ok) {
-        throw new AppError('marketplace_clone_failed', `git 拉取 ${repo} 失败。浅拉取 ${ref}: ${shallow.stderr || shallow.stdout}；完整 clone: ${clone.stderr || clone.stdout}`);
-    }
-    const fetch = execFile('git', ['fetch', '--depth', '1', 'origin', ref], { cwd: temporary, ...GIT_NETWORK_OPTIONS });
-    if (!fetch.ok)
-        throw new AppError('marketplace_fetch_failed', `git fetch ${ref} 失败: ${fetch.stderr || fetch.stdout}`);
+    const snapshot = snapshotGitRef({
+        repo, ref, label: 'marketplace', cacheRoot: marketplaceCacheRoot(), cacheDir: (sha) => marketplaceCacheDir(name, sha),
+    });
+    return { name, repo, ref, ...snapshot };
 }
 function validateMarketplace(root) {
     const ids = new Set();
@@ -333,10 +286,8 @@ function inferName(repo) {
     const base = repo.split('/').pop() ?? 'marketplace';
     return base.replace(/\.git$/, '');
 }
-export function isImmutableRef(ref) {
-    return /^[0-9a-f]{40}$/i.test(ref) || /^refs\/tags\/[^/]+$/.test(ref);
-}
 function errorCode(error) {
     return error instanceof AppError ? error.code : 'dependency_check_failed';
 }
+export { isImmutableRef };
 //# sourceMappingURL=registry.js.map

package/dist/marketplace/upgrade.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { isScalar, parseDocument } from 'yaml';
-import { configPathOf, loadConfig } from '../config/load.js';
+import { configPathOf, loadConfig, loadProjectConfig } from '../config/load.js';
 import { listChangeNames } from '../core/change.js';
 import { inspectHookEntries } from '../hooks/engine.js';
 import { AppError } from '../shared/errors.js';
@@ -17,10 +17,12 @@ import { addMarketplace, assertPluginsPresent, isImmutableRef } from './registry
  */
 export function upgradeMarketplace(input) {
     const { projectRoot, name, ref } = input;
+    // ref 写回项目层，所以只在项目层里找声明；插件依赖取生效配置。
+    const layer = loadProjectConfig(projectRoot);
     const config = loadConfig(projectRoot);
     const configFile = configPathOf(projectRoot);
-    const index = (config.marketplaces ?? []).findIndex((item) => item.name === name);
-    const declared = config.marketplaces?.[index];
+    const index = (layer.marketplaces ?? []).findIndex((item) => item.name === name);
+    const declared = layer.marketplaces?.[index];
     if (!configFile || !declared) {
         throw new AppError('marketplace_not_configured', `config 未声明 marketplace: ${name}；升级只针对宿主配置中的远端 marketplace`);
     }

package/dist/shared/fs.d.ts

@@ -3,6 +3,8 @@ export declare function ensureDir(dir: string): void;
 export declare function readText(file: string): string;
 export declare function writeText(file: string, content: string): void;
 export declare function readJson<T>(file: string): T;
+/** 同目录临时文件加 rename：中断时旧内容保持完整。 */
+export declare function writeTextAtomic(file: string, content: string): void;
 export declare function writeJson(file: string, value: unknown): void;
 export declare function appendText(file: string, line: string): void;
 export declare function copyDir(from: string, to: string): void;

package/dist/shared/fs.js

@@ -23,11 +23,12 @@ export function readJson(file) {
         throw new AppError('invalid_json', `JSON 文件无法解析: ${file}`, error instanceof Error ? error.message : String(error));
     }
 }
-export function writeJson(file, value) {
+/** 同目录临时文件加 rename：中断时旧内容保持完整。 */
+export function writeTextAtomic(file, content) {
     ensureDir(path.dirname(file));
     const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${randomUUID()}.tmp`);
     try {
-        writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+        writeFileSync(temporary, content, 'utf8');
         renameSync(temporary, file);
     }
     catch (error) {
@@ -36,6 +37,9 @@ export function writeJson(file, value) {
         throw error;
     }
 }
+export function writeJson(file, value) {
+    writeTextAtomic(file, `${JSON.stringify(value, null, 2)}\n`);
+}
 export function appendText(file, line) {
     ensureDir(path.dirname(file));
     writeFileSync(file, line, { encoding: 'utf8', flag: 'a' });

package/dist/shared/git-snapshot.d.ts

@@ -0,0 +1,18 @@
+export declare function isImmutableRef(ref: string): boolean;
+/**
+ * 把 Git 仓库在不可变 ref 上的内容取成去掉 .git 的只读快照，按解析出的 SHA 缓存。
+ * 总是联网拉取；同一 SHA 已有缓存时要求内容与刚拉到的一致，否则报错而不采用缓存，避免把被改过的缓存写进锁。
+ * `label` 作为错误码前缀（如 marketplace_clone_failed），让调用方保留各自的错误码。
+ */
+export declare function snapshotGitRef(input: {
+    repo: string;
+    ref: string;
+    label: string;
+    cacheRoot: string;
+    cacheDir: (resolvedSha: string) => string;
+}): {
+    resolvedSha: string;
+    cachePath: string;
+    digest: string;
+};
+//# sourceMappingURL=git-snapshot.d.ts.map

package/dist/shared/git-snapshot.js

@@ -0,0 +1,75 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { renameSync } from 'node:fs';
+import { execFile } from './exec.js';
+import { ensureDir, exists, removePath } from './fs.js';
+import { digestDirectory } from './hash.js';
+import { AppError } from './errors.js';
+import { resolveInside } from './paths.js';
+export function isImmutableRef(ref) {
+    return /^[0-9a-f]{40}$/i.test(ref) || /^refs\/tags\/[^/]+$/.test(ref);
+}
+/** 网络操作给足时间，且禁止 git 等待终端输入（否则会静默挂到超时）。 */
+const GIT_NETWORK_OPTIONS = { timeoutMs: 300_000, env: { GIT_TERMINAL_PROMPT: '0' } };
+/**
+ * 把 Git 仓库在不可变 ref 上的内容取成去掉 .git 的只读快照，按解析出的 SHA 缓存。
+ * 总是联网拉取；同一 SHA 已有缓存时要求内容与刚拉到的一致，否则报错而不采用缓存，避免把被改过的缓存写进锁。
+ * `label` 作为错误码前缀（如 marketplace_clone_failed），让调用方保留各自的错误码。
+ */
+export function snapshotGitRef(input) {
+    const { repo, ref, label } = input;
+    ensureDir(input.cacheRoot);
+    const temporary = resolveInside(input.cacheRoot, `.clone-${randomUUID()}`, `${label}_cache_outside_home`);
+    try {
+        fetchImmutableRef(repo, ref, temporary, label);
+        const checkout = execFile('git', ['checkout', '--detach', 'FETCH_HEAD'], { cwd: temporary });
+        if (!checkout.ok)
+            throw new AppError(`${label}_checkout_failed`, checkout.stderr || checkout.stdout);
+        const resolved = execFile('git', ['rev-parse', 'HEAD'], { cwd: temporary });
+        if (!resolved.ok)
+            throw new AppError(`${label}_revision_failed`, resolved.stderr || resolved.stdout);
+        const resolvedSha = resolved.stdout.trim();
+        removePath(path.join(temporary, '.git'));
+        const digest = digestDirectory(temporary);
+        const cachePath = input.cacheDir(resolvedSha);
+        if (exists(cachePath)) {
+            if (digestDirectory(cachePath) !== digest) {
+                throw new AppError(`${label}_digest_mismatch`, `本机缓存与仓库 ${ref} 的内容不一致，可能被改动过: ${cachePath}；删除该目录后重试`);
+            }
+        }
+        else {
+            ensureDir(path.dirname(cachePath));
+            renameSync(temporary, cachePath);
+        }
+        return { resolvedSha, cachePath, digest };
+    }
+    finally {
+        if (exists(temporary))
+            removePath(temporary);
+    }
+}
+/**
+ * 只拉取不可变 ref 指向的那一个提交：init + remote add + fetch --depth 1。
+ * 服务端不允许按 SHA 拉取时回退为完整 clone 后再 fetch。
+ */
+function fetchImmutableRef(repo, ref, temporary, label) {
+    ensureDir(temporary);
+    const init = execFile('git', ['init', '-q'], { cwd: temporary });
+    if (!init.ok)
+        throw new AppError(`${label}_clone_failed`, `git init 失败: ${init.stderr || init.stdout}`);
+    const remote = execFile('git', ['remote', 'add', 'origin', repo], { cwd: temporary });
+    if (!remote.ok)
+        throw new AppError(`${label}_clone_failed`, `git remote add 失败: ${remote.stderr || remote.stdout}`);
+    const shallow = execFile('git', ['fetch', '--depth', '1', 'origin', ref], { cwd: temporary, ...GIT_NETWORK_OPTIONS });
+    if (shallow.ok)
+        return;
+    removePath(temporary);
+    const clone = execFile('git', ['clone', '--no-checkout', repo, temporary], { cwd: path.dirname(temporary), ...GIT_NETWORK_OPTIONS });
+    if (!clone.ok) {
+        throw new AppError(`${label}_clone_failed`, `git 拉取 ${repo} 失败。浅拉取 ${ref}: ${shallow.stderr || shallow.stdout}；完整 clone: ${clone.stderr || clone.stdout}`);
+    }
+    const fetch = execFile('git', ['fetch', '--depth', '1', 'origin', ref], { cwd: temporary, ...GIT_NETWORK_OPTIONS });
+    if (!fetch.ok)
+        throw new AppError(`${label}_fetch_failed`, `git fetch ${ref} 失败: ${fetch.stderr || fetch.stdout}`);
+}
+//# sourceMappingURL=git-snapshot.js.map

package/dist/shared/pkg.js

@@ -8,7 +8,7 @@ export function packageRoot() {
     for (let i = 0; i < 8; i += 1) {
         if (existsSync(path.join(dir, 'package.json'))) {
             fallback = dir;
-            if (existsSync(path.join(dir, 'skills')) || existsSync(path.join(dir, 'presets')))
+            if (existsSync(path.join(dir, 'skills')))
                 return dir;
         }
         const parent = path.dirname(dir);

package/docs/getting-started.md

@@ -6,7 +6,7 @@
 4. 审查 Gate-A 后调用 `/opsx-apply`。
 5. `/opsx-verify` 通过 Gate-C 后 `/opsx-archive`。
 
-`init --preset flutter-mobile --yes` 会按项目配置中的完整 Git SHA（或 `refs/tags/<tag>`）解析 marketplace，校验插件后调用 Claude/Codex 原生 marketplace 与 selector。项目 `openspec/marketplace-lock.json` 记录 resolved SHA、marketplace digest 和 plugin digest；adapter 合同来自插件 `plugin.json` 的 `extensions["org.openspec"]`，不写进 CLI。
+`init --preset flutter-mobile --preset-repo <preset 仓库> --preset-ref refs/tags/<tag> --yes` 引用团队 preset 仓库中的 preset（见[团队 preset](guides/configuration.md#团队-preset)），再按生效配置中的完整 Git SHA（或 `refs/tags/<tag>`）解析 marketplace，校验插件后调用 Claude/Codex 原生 marketplace 与 selector。项目 `openspec/marketplace-lock.json` 记录 resolved SHA、marketplace digest 和 plugin digest；adapter 合同来自插件 `plugin.json` 的 `extensions["org.openspec"]`，不写进 CLI。
 
 Claude 的 marketplace 与插件一律以 `--scope local` 安装，写入 `.claude/settings.local.json`（项目级、仅本人、不入库）：其中的 marketplace 路径是本机缓存的绝对路径，用 project scope 会随 `.claude/settings.json` 提交给团队成员。每位成员在自己机器上执行一次 `openspec init --yes` 即可；团队共享的是 `openspec/config.yaml` 与 `marketplace-lock.json`。
 

package/docs/guides/configuration.md

@@ -20,7 +20,7 @@ verify `command` 由引擎直接启动子进程执行，不经 shell；需要管
 
 verify 每次创建独立 run。命令、skill/file/check evidence 和 QA report 都必须属于当前 run；required evidence 缺失、file digest 变化或旧 report 不会通过。`reviewScope` 先裁剪引擎 changed-set，`failurePolicy` 只控制 optional 失败，不能放行 required Hook。
 
-Config 为严格 schema：重复 Hook ID、重复 collect capability、未知 category 引用、旧 `context/rules`、可变 marketplace branch ref 都会报错。Preset 按 Hook ID 与 plugin selector 幂等合并，同一插件取较高的 `minVersion`；宿主已声明的 marketplace 保留自身的 repo 与 ref，preset 只补充宿主缺少的 marketplace。Preset 还可声明 `scaffold: [{ path, template, description }]`：`init --preset` 与 `preset apply` 会把 `presets/<template>` 复制到项目 `path`，只创建不覆盖；模板首行的 `<!-- openspec:fill-me -->` 标记未删除前，指向该文件的 `file` hook 不能回执 `passed`。
+Config 为严格 schema：重复 Hook ID、重复 collect capability、未知 category 引用、旧 `context/rules`、可变 marketplace branch ref 都会报错。
 
 `designRefs` 是 task-plan 的可选节点 id 数组，省略/空数组合法，非空项必须是非空字符串。`packet.refs.design` 提供设计来源 locator 与采集 artifact；详细格式与 status 提示见 [工作流](workflow.md#设计节点引用)。
 
@@ -28,6 +28,13 @@ Config 为严格 schema：重复 Hook ID、重复 collect capability、未知 ca
 
 插件 Hook 通过 `use: entry@marketplace` 引用根 manifest 的 `extensions.org.openspec.hooks`，首轮支持 skill/command；与 name/command/path 等内联实现互斥。`operation: preview` 切换为 source adapter 的预演入口。宿主 input 为 JSON 参数，inputFiles 为额外依赖文件路径；动态 --input 的顶层值优先。类型、阶段、重复 ID、损坏和缺失入口明确失败。详情及示例见[插件运行契约](../maintainers/plugin-runtime-contract.md)。
 
-已定制的宿主迁移使用精确差异，保留 Hook 的类型、command、required、参数、范围和顺序；同 ID 的 preset 合并是整项替换，不能用它覆盖宿主验收命令。
+项目层同 ID 的 hook 整条替换 preset 条目，覆盖时要写出完整的 Hook（类型、command、required、参数、范围）。
 
 parse/tech/plan 的 Hook 可用 capability 限定仅在当前来源账本包含该能力时适用；省略则应用于整个阶段。required tech command 只在适用时禁止 skipTech。
+
+## 团队 preset
+
+- `preset: { repo, ref, id }` 引用独立 Git 仓库中的一个 preset，`ref` 必须是完整 SHA 或 `refs/tags/<tag>`。config 其余字段是项目层，生效配置 = preset 基线 + 项目层：分类按名覆盖（`null` 删除）；hook 同 ID 整条替换并保留基线位置，`disableHooks: [id]` 禁用基线 hook，项目新增 hook 排在基线之后，需要插在中间时用 `hookOrder: { <stage>: [id, ...] }` 指定该阶段的顺序（列出的依次在前，其余保持原相对顺序）；验收设置按字段覆盖；插件取并集，同一插件取较高 `minVersion`；marketplace 以项目声明为准，基线只补缺；`tools` 只来自项目层。
+- `openspec/preset-lock.json` 记录解析出的 SHA 与内容摘要，与 config 一起提交。运行时只读本机缓存、不联网；成员拉取后执行 `openspec init` 按锁补齐缓存，`openspec doctor` 报告锁缺失、锁与 config 不一致、缓存缺失或被改。
+- 命令：`preset use <id> --repo <repo> --ref <ref>` 引用；`preset upgrade --ref <ref>` 升级，列出基线变化与被项目层遮住的更新，不兼容时还原；`preset status` 查看每项来源（生效配置本体用 `config get`）；`preset list`、`preset show <id>` 查看仓库内容；`preset migrate <id> --repo --ref [--dry-run]` 把旧的拷贝式配置迁移为引用，迁移前后生效配置必须一致（同阶段 hook 顺序不同时自动生成 `hookOrder`；preset 提高的插件最低版本无法取消，会在结果中列出）。
+- preset 仓库：每个 preset 一个目录，`<id>/preset.yaml`（`schemaVersion: openspec.team-preset.v2`，可用 `requires.openspec` 声明最低 OpenSpec 版本）加模板文件。`scaffold: [{ path, template, description }]` 的 template 相对该目录，引用或升级时只创建不覆盖；模板首行的 `<!-- openspec:fill-me -->` 标记未删除前，指向该文件的 `file` hook 不能回执 `passed`。仓库根部的 `openspec-presets.json` 由 `openspec preset index` 生成，CI 用 `openspec preset validate` 校验规则、模板、插件引用与索引一致性。

package/docs/guides/plugin-migration.md

@@ -2,7 +2,7 @@
 
 OpenSpec 只负责来源、阶段、调用和证据身份。插件提供 Skill、source adapter / Hook 声明和公开工具入口绑定；已有独立工具项目负责格式解析、执行实现、兼容范围和功能测试。预设选择入口；宿主拥有参数、真实路径与业务断言。`org.openspec.hooks` 与 Claude/Codex 原生事件 Hook 是独立契约。
 
-`flutter-mobile/plugin-hooks.json` 是可供既有宿主选择性迁移的插件配置片段，遵循现有 ProjectConfigPatch schema，没有新增预设合并机制。它声明来源指导、只读预演、生成、国际化实施和真实 locale 命令。预演参数通过 Worker `--input` 提供；locale 命令通过宿主 `input.manifest` 或动态输入指定清单。verify 如需相同校验，复用 `intl-locales-check`，指定独立 Hook ID、stage: verify 和固定宿主参数。
+preset 仓库中的 `flutter-mobile/plugin-hooks.json` 是可供既有宿主选择性迁移的插件配置片段，遵循现有 ProjectConfigPatch schema，没有新增预设合并机制。它声明来源指导、只读预演、生成、国际化实施和真实 locale 命令。预演参数通过 Worker `--input` 提供；locale 命令通过宿主 `input.manifest` 或动态输入指定清单。verify 如需相同校验，复用 `intl-locales-check`，指定独立 Hook ID、stage: verify 和固定宿主参数。
 
 ## 版本归属与独立升级
 
@@ -11,11 +11,11 @@ OpenSpec 只负责来源、阶段、调用和证据身份。插件提供 Skill
 | 层 | 负责 | 何时变化 |
 |---|---|---|
 | OpenSpec | Hook 入口解析、[插件运行契约](../maintainers/plugin-runtime-contract.md)、回执身份 | 契约变化时 |
-| preset | 平台约定、引用的入口 ID、所需插件最低版本、已验证的基线 ref | 随 OpenSpec 发版 |
+| preset | 平台约定、引用的入口 ID、所需插件最低版本、已验证的基线 ref | 在 preset 仓库打 tag 发布 |
 | 插件与工具 | 工具行为和用法（写在插件 Skill）、所需工具版本与能力核对 | 独立发版 |
 | 宿主 | `openspec/config.yaml` 的 marketplace ref 与 `openspec/marketplace-lock.json`，即实际使用的精确版本 | 按需升级 |
 
-preset 的 ref 只是发布时验证过的基线，在 OpenSpec 下次发版时顺带更新。工具生成什么形状、有哪些参数、输入文件格式是什么，写在插件 Skill 或插件 Hook 的 `inputDescription` 里；preset 与核心节点只写平台约定和验收原则，不复述工具行为，否则工具每次变化 preset 都得跟版。例如计划覆盖检查的输入格式见 yapi-source-guidance，国际化快照清单见 intl-workflow。
+preset 的 ref 只是发布时验证过的基线，在 preset 仓库下次发布时更新。工具生成什么形状、有哪些参数、输入文件格式是什么，写在插件 Skill 或插件 Hook 的 `inputDescription` 里；preset 与核心节点只写平台约定和验收原则，不复述工具行为，否则工具每次变化 preset 都得跟版。例如计划覆盖检查的输入格式见 yapi-source-guidance，国际化快照清单见 intl-workflow。
 
 `flutter-mobile` 的基线 ref 为 `06081ec27a557d8f5e4d443aa8549ab026173f94`（2.2.1 起）。自 2.2.3 起引用的 `yapi-plan-coverage` 需要 yapi-dart-coding 插件 0.2.1，任务级翻译需要 intl-utils 插件 0.2.3，基线 ref 早于这两个版本。发布 preset 前先发布工具和插件，再把基线 ref 更新为包含它们的已发布提交。插件需要的工具版本由插件 Skill 声明，不写在 preset 里。
 
@@ -37,7 +37,7 @@ openspec marketplace upgrade <marketplace> --ref <完整 Git SHA 或 refs/tags/<
 
 之后按插件 Skill 的要求升级宿主工具依赖（例如 pubspec 中的 Git ref），核对依赖锁解析到的提交，`openspec doctor` 通过后再开始新的 change。
 
-同一 marketplace 的插件共用一个 ref，升级其中一个插件就是取该市场的新快照，市场自身的 CI 负责整体一致。`preset apply` 与 `init --preset` 保留宿主已声明的 marketplace ref，只补充宿主缺少的 marketplace，并在输出中列出与 preset 基线不同的项（`keptMarketplaces`）。
+同一 marketplace 的插件共用一个 ref，升级其中一个插件就是取该市场的新快照，市场自身的 CI 负责整体一致。项目层声明的 marketplace ref 优先于 preset 基线，preset 只补充项目缺少的 marketplace；`openspec preset status` 中标为 `override` 的 marketplace 就是项目覆盖了基线的项。
 
 ### 兼容检查
 
@@ -52,7 +52,7 @@ openspec marketplace upgrade <marketplace> --ref <完整 Git SHA 或 refs/tags/<
 
 ## 迁移与安装注意事项
 
-迁移已有宿主时先冻结配置与插件锁，再按 Hook ID 精确修改对应实现。保留原来的 required、command 参数、taskCategories、target/include/exclude/allowEmpty 与顺序；已有真实 command 不能退化成 check 或文字 passed。更新为插件入口时移除互斥的内联 command/name，保留原意并显式填入参数。不要直接 `preset apply` 覆盖宿主，因为同 ID 的 Hook 会被整项替换。新增 file 模板只创建不覆盖，真实宿主约定不能回退为模板。
+迁移已有宿主时先冻结配置与插件锁，再按 Hook ID 精确修改对应实现。保留原来的 required、command 参数、taskCategories、target/include/exclude/allowEmpty 与顺序；已有真实 command 不能退化成 check 或文字 passed。更新为插件入口时移除互斥的内联 command/name，保留原意并显式填入参数。引用 preset 的项目在项目层写同 ID 的 Hook 即可覆盖 preset 条目，覆盖是整项替换，要写出完整内容。新增 file 模板只创建不覆盖，真实宿主约定不能回退为模板。
 
 工具依赖可使用已发布的 tag，并在依赖锁中核验解析提交；marketplace 使用已验收的固定提交。插件或分发版本更新后，须通过原生 CLI 刷新安装，核对实际版本、作用域、路径与完整摘要，再生成宿主锁和回执。仅修改锁文件不能证明安装已更新。模板记录运行参数的来源，个人模型、凭据和服务地址由宿主及本机配置提供；显式临时覆盖仍由工具支持。
 

package/docs/guides/ui-conventions-template.md

@@ -6,7 +6,7 @@ flutter-mobile preset 的 parse / tech / plan Worker 以 required `file` hook
 
 ## 由 init 自动生成
 
-`openspec init --preset flutter-mobile`（或 `openspec preset apply flutter-mobile`）会按 preset 的 `scaffold` 声明，把模板 [presets/flutter-mobile/ui-conventions.md](../../presets/flutter-mobile/ui-conventions.md) 放到项目的 `docs/agent/ui-conventions.md`。只创建、不覆盖：已存在的文件不会被重复 init 改动。
+`openspec preset use flutter-mobile`（或 `openspec init --preset flutter-mobile`）会按 preset 的 `scaffold` 声明，把 preset 仓库中的模板放到项目的 `docs/agent/ui-conventions.md`。只创建、不覆盖：已存在的文件不会被重复引用或升级改动。
 
 路径由 `openspec/config.yaml` 中 `type: file` hook 的 `path` 决定；preset 默认在 parse / tech / plan / ui code 四处声明为 `docs/agent/ui-conventions.md`。项目可以改，但四个 hook 与 `scaffold.path` 要一起改。
 
@@ -36,4 +36,4 @@ flutter-mobile preset 的 parse / tech / plan Worker 以 required `file` hook
 
 国际化流程填写项目实际选用的资源格式、代码读取入口、翻译、合入、生成和校验命令，以及参数配置来源。工具指导由所选插件 Hook 提供，模板不预填生成器、资源格式或第三方版本。保留宿主已确认的增量策略、必需语言、占位符及历史文案保护要求；无国际化需求时注明不适用。
 
-同步预设时先比较宿主 Hook 的类型、命令、required、参数、范围与顺序。`preset apply` 会替换同 ID 的配置项，不能用它覆盖已经定制的宿主验收命令；使用经核对的精确差异迁移。
+升级 preset 用 `openspec preset upgrade`：项目层覆盖的条目保持不变，输出会列出被覆盖遮住的 preset 更新；旧的拷贝式配置先用 `openspec preset migrate` 迁移。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@birdie_moblie/open_spec",
-  "version": "2.1.7",
+  "version": "2.2.0",
   "description": "AI-native Spec Coding 工具：确定性产品规格工作流",
   "keywords": [
     "openspec",
@@ -34,7 +34,6 @@
     "dist",
     "bin/openspec.js",
     "skills",
-    "presets",
     "plugin.json",
     ".claude-plugin",
     ".codex-plugin",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "openspec",
-  "version": "2.1.7",
+  "version": "2.2.0",
   "description": "OpenSpec 确定性产品规格工作流",
   "license": "MIT",
   "author": { "name": "OpenSpec Contributors" },

package/presets/backend-service.yaml

@@ -1,19 +0,0 @@
-schemaVersion: openspec.team-preset.v1
-version: 2.0.0
-id: backend-service
-title: Backend Service
-description: 后端服务团队的 spec-product 默认配置
-configPatch:
-  schema: spec-product
-  hooks:
-    - id: contract-check
-      stage: verify
-      type: check
-      category: contract
-      description: 核对接口契约与错误码是否与 spec 一致
-      required: true
-    - id: unit-test
-      stage: verify
-      type: command
-      command: pnpm test
-      required: true

package/presets/flutter-mobile/plugin-hooks.json

@@ -1,68 +0,0 @@
-{
-  "schema": "spec-product",
-  "hooks": [
-    {
-      "id": "yapi-guidance-parse",
-      "stage": "parse",
-      "type": "skill",
-      "use": "yapi-source-guidance@mobile-marketplace",
-      "capability": "interfaces",
-      "required": true
-    },
-    {
-      "id": "yapi-guidance-tech",
-      "stage": "tech",
-      "type": "skill",
-      "use": "yapi-source-guidance@mobile-marketplace",
-      "capability": "interfaces",
-      "required": true
-    },
-    {
-      "id": "yapi-preview",
-      "stage": "tech",
-      "type": "command",
-      "use": "yapi-discovery@mobile-marketplace",
-      "operation": "preview",
-      "capability": "interfaces",
-      "required": true
-    },
-    {
-      "id": "yapi-plan-coverage",
-      "stage": "plan",
-      "type": "command",
-      "use": "yapi-plan-coverage@mobile-marketplace",
-      "capability": "interfaces",
-      "required": true
-    },
-    {
-      "id": "yapi-generation",
-      "stage": "execute",
-      "type": "skill",
-      "use": "yapi-codegen@mobile-marketplace",
-      "taskCategories": [
-        "api-codegen"
-      ],
-      "required": true
-    },
-    {
-      "id": "intl-workflow",
-      "stage": "execute",
-      "type": "skill",
-      "use": "intl-workflow@mobile-marketplace",
-      "taskCategories": [
-        "ui"
-      ],
-      "required": true
-    },
-    {
-      "id": "i18n-inline",
-      "stage": "execute",
-      "type": "command",
-      "use": "intl-locales-check@mobile-marketplace",
-      "taskCategories": [
-        "ui"
-      ],
-      "required": true
-    }
-  ]
-}