@openspecui/core 2.1.2 → 2.1.3

package/dist/index.d.mts

@@ -696,18 +696,10 @@ declare class OpenSpecAdapter {
    * Read project.md content (reactive)
    */
   readProjectMd(): Promise<string | null>;
-  /**
-   * Read AGENTS.md content (reactive)
-   */
-  readAgentsMd(): Promise<string | null>;
   /**
    * Write project.md content
    */
   writeProjectMd(content: string): Promise<void>;
-  /**
-   * Write AGENTS.md content
-   */
-  writeAgentsMd(content: string): Promise<void>;
   readSpec(specId: string): Promise<Spec | null>;
   readSpecRaw(specId: string): Promise<string | null>;
   readChange(changeId: string): Promise<Change | null>;
@@ -1538,6 +1530,9 @@ declare const DEFAULT_CONFIG: OpenSpecUIConfig;
  *
  * 负责读写 openspec/.openspecui.json 配置文件。
  * 读取操作使用 reactiveReadFile，支持响应式更新。
+ *
+ * `.openspecui.json` 是预期中的项目级 UI 配置文件，但只有显式偏离默认值的
+ * override 才会落盘。仅启动 openspecui 或仅依赖默认配置时，不应触发文件写入。
  */
 declare class ConfigManager {
   private configPath;
@@ -1545,6 +1540,7 @@ declare class ConfigManager {
   private resolvedRunner;
   private resolvingRunnerPromise;
   constructor(projectDir: string);
+  private parseConfigContent;
   /**
    * 读取配置（响应式）
    *
@@ -1558,6 +1554,8 @@ declare class ConfigManager {
    * 会触发文件监听，自动更新订阅者。
    */
   writeConfig(config: OpenSpecUIConfigUpdate): Promise<void>;
+  private resolveDefaultCliCommandParts;
+  private isDefaultCliCommand;
   /**
    * 解析并缓存可用 CLI runner。
    */
@@ -1691,6 +1689,9 @@ declare class CliExecutor {
   }, onEvent: (event: CliStreamEvent) => void): Promise<() => void>;
   /**
    * 流式执行任意命令（数组形式）
+   *
+   * 字面量 `openspec` 会自动通过已解析的 CLI runner 执行，
+   * 其它命令保持原始 spawn 行为。
    */
   executeCommandStream(command: readonly string[], onEvent: (event: CliStreamEvent) => void): () => void;
 }
@@ -1711,7 +1712,7 @@ interface AIToolOption {
   name: string;
   /** 工具 ID（用于 CLI 参数） */
   value: string;
-  /** 是否可用（available: false 的工具不会出现在主列表中） */
+  /** 是否可由 openspec init 直接管理 */
   available: boolean;
   /** 成功消息中使用的标签 */
   successLabel?: string;
@@ -1736,11 +1737,18 @@ declare function getAvailableTools(): ToolConfig[];
  */
 declare function getAvailableToolIds(): string[];
 /**
- * 获取所有工具（包括 available: false 的）
+ * 获取所有工具
  */
 declare function getAllTools(): ToolConfig[];
 /**
- * 获取所有工具 ID 列表（包括 available: false 的）
+ * 检测当前项目中已经存在的工具目录。
+ *
+ * 这里对齐 OpenSpec 官方 `getAvailableTools(projectPath)` 的语义：
+ * 仅根据项目根目录下的工具目录是否存在来判断，不读取全局命令安装状态。
+ */
+declare function getDetectedProjectTools(projectDir: string): Promise<ToolConfig[]>;
+/**
+ * 获取所有工具 ID 列表
  */
 declare function getAllToolIds(): string[];
 /**
@@ -1756,6 +1764,44 @@ declare function getConfiguredTools(projectDir: string): Promise<string[]>;
  */
 declare function isToolConfigured(projectDir: string, toolId: string): Promise<boolean>;
 //#endregion
+//#region src/tool-init-state.d.ts
+declare const TOOL_WORKFLOW_TO_SKILL_DIR: {
+  readonly propose: "openspec-propose";
+  readonly explore: "openspec-explore";
+  readonly new: "openspec-new-change";
+  readonly continue: "openspec-continue-change";
+  readonly apply: "openspec-apply-change";
+  readonly ff: "openspec-ff-change";
+  readonly sync: "openspec-sync-specs";
+  readonly archive: "openspec-archive-change";
+  readonly 'bulk-archive': "openspec-bulk-archive-change";
+  readonly verify: "openspec-verify-change";
+  readonly onboard: "openspec-onboard";
+};
+type ToolWorkflowId = keyof typeof TOOL_WORKFLOW_TO_SKILL_DIR;
+type ToolInitDelivery = 'both' | 'skills' | 'commands';
+type ToolInitStatus = 'uninitialized' | 'partial' | 'initialized';
+interface ToolInitState {
+  toolId: string;
+  toolName: string;
+  status: ToolInitStatus;
+  hasAnyArtifacts: boolean;
+  expectedSkillCount: number;
+  presentExpectedSkillCount: number;
+  detectedSkillCount: number;
+  expectedCommandCount: number;
+  presentExpectedCommandCount: number;
+  detectedCommandCount: number;
+  missingSkillWorkflows: ToolWorkflowId[];
+  missingCommandWorkflows: ToolWorkflowId[];
+  unexpectedSkillWorkflows: ToolWorkflowId[];
+  unexpectedCommandWorkflows: ToolWorkflowId[];
+}
+declare function getToolInitStates(projectDir: string, options: {
+  delivery: ToolInitDelivery;
+  workflows: readonly string[];
+}): Promise<ToolInitState[]>;
+//#endregion
 //#region src/dashboard-types.d.ts
 declare const DASHBOARD_METRIC_KEYS: readonly ["specifications", "requirements", "activeChanges", "inProgressChanges", "completedChanges", "taskCompletionPercent"];
 type DashboardMetricKey = (typeof DASHBOARD_METRIC_KEYS)[number];
@@ -2346,8 +2392,6 @@ interface ExportSnapshot {
   }>;
   /** Project.md content */
   projectMd?: string;
-  /** AGENTS.md content */
-  agentsMd?: string;
   /** OPSX configuration data (for Config view) */
   opsx?: {
     configYaml?: string;
@@ -2962,4 +3006,4 @@ type PtyServerMessage = z.infer<typeof PtyServerMessageSchema>;
 type PtySessionInfo = z.infer<typeof PtySessionInfoSchema>;
 type PtyPlatform = z.infer<typeof PtyPlatformSchema>;
 //#endregion
-export { type AIToolOption, AI_TOOLS, type ApplyInstructions, ApplyInstructionsSchema, type ApplyTask, ApplyTaskSchema, type ArchiveMeta, type ArtifactInstructions, ArtifactInstructionsSchema, type ArtifactStatus, ArtifactStatusSchema, CODE_EDITOR_THEME_VALUES, type Change, type ChangeFile, ChangeFileSchema, type ChangeMeta, ChangeSchema, type ChangeStatus, ChangeStatusSchema, CliExecutor, type CliResult, type CliRunnerAttempt, type CliSniffResult, type CliStreamEvent, type CodeEditorTheme, CodeEditorThemeSchema, ConfigManager, DASHBOARD_METRIC_KEYS, DEFAULT_CONFIG, type DashboardCardAvailability, type DashboardConfig, DashboardConfigSchema, type DashboardGitCommitEntry, type DashboardGitDiffStats, type DashboardGitEntry, type DashboardGitSnapshot, type DashboardGitUncommittedEntry, type DashboardGitWorktree, type DashboardMetricKey, type DashboardOverview, type DashboardSummary, type DashboardTrendKind, type DashboardTrendMeta, type DashboardTrendPoint, type DashboardTriColorTrendPoint, type Delta, type DeltaOperation, DeltaOperationType, DeltaSchema, type DeltaSpec, DeltaSpecSchema, type DependencyInfo, DependencyInfoSchema, type ExportSnapshot, type FileChangeEvent, type FileChangeType, type HostedAppChannelKind, type HostedAppChannelManifest, type HostedAppCompatibilityEntry, type HostedAppVersionManifest, type HostedBackendHealthResponse, MarkdownParser, OFFICIAL_APP_BASE_URL, OpenSpecAdapter, type OpenSpecUIConfig, OpenSpecUIConfigSchema, type OpenSpecUIConfigUpdate, OpenSpecWatcher, OpsxKernel, type PathCallback, ProjectWatcher, type ProjectWatcherReinitializeReason, type ProjectWatcherRuntimeStatus, PtyAttachMessageSchema, PtyBufferResponseSchema, type PtyClientMessage, PtyClientMessageSchema, PtyCloseMessageSchema, PtyCreateMessageSchema, PtyCreatedResponseSchema, PtyErrorCodeSchema, PtyErrorResponseSchema, PtyExitResponseSchema, PtyInputMessageSchema, PtyListMessageSchema, PtyListResponseSchema, PtyOutputResponseSchema, type PtyPlatform, PtyPlatformSchema, PtyResizeMessageSchema, type PtyServerMessage, PtyServerMessageSchema, type PtySessionInfo, PtyTitleResponseSchema, ReactiveContext, ReactiveState, type ReactiveStateOptions, type Requirement, RequirementSchema, type ResolvedCliRunner, type SchemaArtifact, SchemaArtifactSchema, type SchemaDetail, SchemaDetailSchema, type SchemaInfo, SchemaInfoSchema, type SchemaResolution, SchemaResolutionSchema, type Spec, type SpecMeta, SpecSchema, type Task, TaskSchema, type TemplateContentMap, type TemplatesMap, TemplatesSchema, type TerminalConfig, TerminalConfigSchema, type TerminalRendererEngine, TerminalRendererEngineSchema, type ToolConfig, VIRTUAL_PROJECT_DIRNAME, type ValidationIssue, type ValidationResult, Validator, type WatchEvent, type WatchEventType, type WatcherRuntimeStatus, acquireWatcher, buildCliRunnerCandidates, buildHostedLaunchUrl, buildHostedVersionManifestUrl, clearCache, closeAllProjectWatchers, closeAllWatchers, contextStorage, createCleanCliEnv, createFileChangeObservable, getActiveWatcherCount, getAllToolIds, getAllTools, getAvailableToolIds, getAvailableTools, getCacheSize, getConfiguredTools, getDefaultCliCommand, getDefaultCliCommandString, getProjectWatcher, getToolById, getWatchedProjectDir, getWatcherRuntimeStatus, initWatcherPool, isGlobPattern, isHostedAppVersionManifest, isHostedBackendHealthResponse, isTerminalRendererEngine, isToolConfigured, isWatcherPoolInitialized, normalizeHostedAppBaseUrl, parseCliCommand, reactiveExists, reactiveReadDir, reactiveReadFile, reactiveStat, resolveHostedAppBaseUrl, resolveHostedChannelForVersion, sniffGlobalCli, toOpsxDisplayPath };
+export { type AIToolOption, AI_TOOLS, type ApplyInstructions, ApplyInstructionsSchema, type ApplyTask, ApplyTaskSchema, type ArchiveMeta, type ArtifactInstructions, ArtifactInstructionsSchema, type ArtifactStatus, ArtifactStatusSchema, CODE_EDITOR_THEME_VALUES, type Change, type ChangeFile, ChangeFileSchema, type ChangeMeta, ChangeSchema, type ChangeStatus, ChangeStatusSchema, CliExecutor, type CliResult, type CliRunnerAttempt, type CliSniffResult, type CliStreamEvent, type CodeEditorTheme, CodeEditorThemeSchema, ConfigManager, DASHBOARD_METRIC_KEYS, DEFAULT_CONFIG, type DashboardCardAvailability, type DashboardConfig, DashboardConfigSchema, type DashboardGitCommitEntry, type DashboardGitDiffStats, type DashboardGitEntry, type DashboardGitSnapshot, type DashboardGitUncommittedEntry, type DashboardGitWorktree, type DashboardMetricKey, type DashboardOverview, type DashboardSummary, type DashboardTrendKind, type DashboardTrendMeta, type DashboardTrendPoint, type DashboardTriColorTrendPoint, type Delta, type DeltaOperation, DeltaOperationType, DeltaSchema, type DeltaSpec, DeltaSpecSchema, type DependencyInfo, DependencyInfoSchema, type ExportSnapshot, type FileChangeEvent, type FileChangeType, type HostedAppChannelKind, type HostedAppChannelManifest, type HostedAppCompatibilityEntry, type HostedAppVersionManifest, type HostedBackendHealthResponse, MarkdownParser, OFFICIAL_APP_BASE_URL, OpenSpecAdapter, type OpenSpecUIConfig, OpenSpecUIConfigSchema, type OpenSpecUIConfigUpdate, OpenSpecWatcher, OpsxKernel, type PathCallback, ProjectWatcher, type ProjectWatcherReinitializeReason, type ProjectWatcherRuntimeStatus, PtyAttachMessageSchema, PtyBufferResponseSchema, type PtyClientMessage, PtyClientMessageSchema, PtyCloseMessageSchema, PtyCreateMessageSchema, PtyCreatedResponseSchema, PtyErrorCodeSchema, PtyErrorResponseSchema, PtyExitResponseSchema, PtyInputMessageSchema, PtyListMessageSchema, PtyListResponseSchema, PtyOutputResponseSchema, type PtyPlatform, PtyPlatformSchema, PtyResizeMessageSchema, type PtyServerMessage, PtyServerMessageSchema, type PtySessionInfo, PtyTitleResponseSchema, ReactiveContext, ReactiveState, type ReactiveStateOptions, type Requirement, RequirementSchema, type ResolvedCliRunner, type SchemaArtifact, SchemaArtifactSchema, type SchemaDetail, SchemaDetailSchema, type SchemaInfo, SchemaInfoSchema, type SchemaResolution, SchemaResolutionSchema, type Spec, type SpecMeta, SpecSchema, TOOL_WORKFLOW_TO_SKILL_DIR, type Task, TaskSchema, type TemplateContentMap, type TemplatesMap, TemplatesSchema, type TerminalConfig, TerminalConfigSchema, type TerminalRendererEngine, TerminalRendererEngineSchema, type ToolConfig, type ToolInitDelivery, type ToolInitState, type ToolInitStatus, type ToolWorkflowId, VIRTUAL_PROJECT_DIRNAME, type ValidationIssue, type ValidationResult, Validator, type WatchEvent, type WatchEventType, type WatcherRuntimeStatus, acquireWatcher, buildCliRunnerCandidates, buildHostedLaunchUrl, buildHostedVersionManifestUrl, clearCache, closeAllProjectWatchers, closeAllWatchers, contextStorage, createCleanCliEnv, createFileChangeObservable, getActiveWatcherCount, getAllToolIds, getAllTools, getAvailableToolIds, getAvailableTools, getCacheSize, getConfiguredTools, getDefaultCliCommand, getDefaultCliCommandString, getDetectedProjectTools, getProjectWatcher, getToolById, getToolInitStates, getWatchedProjectDir, getWatcherRuntimeStatus, initWatcherPool, isGlobPattern, isHostedAppVersionManifest, isHostedBackendHealthResponse, isTerminalRendererEngine, isToolConfigured, isWatcherPoolInitialized, normalizeHostedAppBaseUrl, parseCliCommand, reactiveExists, reactiveReadDir, reactiveReadFile, reactiveStat, resolveHostedAppBaseUrl, resolveHostedChannelForVersion, sniffGlobalCli, toOpsxDisplayPath };

package/dist/index.mjs

@@ -11,6 +11,7 @@ import { EventEmitter } from "events";
 import { watch } from "fs";
 import { exec, spawn } from "child_process";
 import { promisify } from "util";
+import { homedir } from "node:os";
 import { parse } from "yaml";
 
 //#region src/parser.ts
@@ -1417,23 +1418,11 @@ var OpenSpecAdapter = class {
 		return reactiveReadFile(join(this.openspecDir, "project.md"));
 	}
 	/**
-	* Read AGENTS.md content (reactive)
-	*/
-	async readAgentsMd() {
-		return reactiveReadFile(join(this.openspecDir, "AGENTS.md"));
-	}
-	/**
 	* Write project.md content
 	*/
 	async writeProjectMd(content) {
 		await writeFile(join(this.openspecDir, "project.md"), content, "utf-8");
 	}
-	/**
-	* Write AGENTS.md content
-	*/
-	async writeAgentsMd(content) {
-		await writeFile(join(this.openspecDir, "AGENTS.md"), content, "utf-8");
-	}
 	async readSpec(specId) {
 		try {
 			const content = await this.readSpecRaw(specId);
@@ -1604,24 +1593,6 @@ This project uses OpenSpec for spec-driven development.
 - \`specs/\` - Source of truth specifications
 - \`changes/\` - Active change proposals
 - \`changes/archive/\` - Completed changes
-`, "utf-8");
-		await writeFile(join(this.openspecDir, "AGENTS.md"), `# AI Agent Instructions
-
-This project uses OpenSpec for spec-driven development.
-
-## Available Commands
-- \`openspec list\` - List changes or specs
-- \`openspec view\` - Dashboard view
-- \`openspec show <name>\` - Show change or spec details
-- \`openspec validate <name>\` - Validate change or spec
-- \`openspec archive <change>\` - Archive completed change
-
-## Workflow
-1. Create a change proposal in \`changes/<change-id>/proposal.md\`
-2. Define delta specs in \`changes/<change-id>/specs/\`
-3. Track tasks in \`changes/<change-id>/tasks.md\`
-4. Implement and mark tasks complete
-5. Archive when done: \`openspec archive <change-id>\`
 `, "utf-8");
 	}
 	/**
@@ -1880,7 +1851,7 @@ var OpenSpecWatcher = class extends EventEmitter {
 			});
 		});
 		this.watchDir(this.openspecDir, (filename, eventType) => {
-			if (filename === "project.md" || filename === "AGENTS.md") this.emitDebounced(`project:${filename}`, {
+			if (filename === "project.md") this.emitDebounced(`project:${filename}`, {
 				type: "project",
 				action: eventType === "rename" ? "create" : "update",
 				path: join(this.openspecDir, filename),
@@ -2344,11 +2315,68 @@ const DEFAULT_CONFIG = {
 	terminal: TerminalConfigSchema.parse({}),
 	dashboard: DashboardConfigSchema.parse({})
 };
+function areStringArraysEqual(left, right) {
+	if (left === right) return true;
+	if (!left || !right) return !left && !right;
+	if (left.length !== right.length) return false;
+	return left.every((value, index) => value === right[index]);
+}
+function pruneNullish(value) {
+	if (value === null || value === void 0) return;
+	if (Array.isArray(value)) return value.map((entry) => pruneNullish(entry)).filter((entry) => entry !== void 0);
+	if (typeof value === "object") {
+		const normalizedEntries = Object.entries(value).flatMap(([key, entryValue]) => {
+			const nextValue = pruneNullish(entryValue);
+			return nextValue === void 0 ? [] : [[key, nextValue]];
+		});
+		return Object.fromEntries(normalizedEntries);
+	}
+	return value;
+}
+function hasOwnEntries(value) {
+	return Object.keys(value).length > 0;
+}
+function toPersistedConfig(config, options = {}) {
+	const persisted = {};
+	const command = config.cli.command?.trim();
+	const args = (config.cli.args ?? []).map((arg) => arg.trim()).filter(Boolean);
+	const cliCommandParts = command ? [command, ...args] : void 0;
+	if (cliCommandParts && !areStringArraysEqual(cliCommandParts, options.defaultCliCommandParts)) {
+		const persistedCommand = cliCommandParts[0];
+		persisted.cli = args.length > 0 ? {
+			command: persistedCommand,
+			args
+		} : { command: persistedCommand };
+	}
+	if (config.theme !== DEFAULT_CONFIG.theme) persisted.theme = config.theme;
+	const codeEditor = {};
+	if (config.codeEditor.theme !== DEFAULT_CONFIG.codeEditor.theme) codeEditor.theme = config.codeEditor.theme;
+	if (hasOwnEntries(codeEditor)) persisted.codeEditor = codeEditor;
+	if (config.appBaseUrl !== DEFAULT_CONFIG.appBaseUrl) persisted.appBaseUrl = config.appBaseUrl;
+	const terminal = {};
+	if (config.terminal.fontSize !== DEFAULT_CONFIG.terminal.fontSize) terminal.fontSize = config.terminal.fontSize;
+	if (config.terminal.fontFamily !== DEFAULT_CONFIG.terminal.fontFamily) terminal.fontFamily = config.terminal.fontFamily;
+	if (config.terminal.cursorBlink !== DEFAULT_CONFIG.terminal.cursorBlink) terminal.cursorBlink = config.terminal.cursorBlink;
+	if (config.terminal.cursorStyle !== DEFAULT_CONFIG.terminal.cursorStyle) terminal.cursorStyle = config.terminal.cursorStyle;
+	if (config.terminal.scrollback !== DEFAULT_CONFIG.terminal.scrollback) terminal.scrollback = config.terminal.scrollback;
+	if (config.terminal.rendererEngine !== DEFAULT_CONFIG.terminal.rendererEngine) terminal.rendererEngine = config.terminal.rendererEngine;
+	if (hasOwnEntries(terminal)) persisted.terminal = terminal;
+	const dashboard = {};
+	if (config.dashboard.trendPointLimit !== DEFAULT_CONFIG.dashboard.trendPointLimit) dashboard.trendPointLimit = config.dashboard.trendPointLimit;
+	if (hasOwnEntries(dashboard)) persisted.dashboard = dashboard;
+	return persisted;
+}
+function isPersistedConfigEmpty(config) {
+	return !hasOwnEntries(config);
+}
 /**
 * 配置管理器
 *
 * 负责读写 openspec/.openspecui.json 配置文件。
 * 读取操作使用 reactiveReadFile，支持响应式更新。
+*
+* `.openspecui.json` 是预期中的项目级 UI 配置文件，但只有显式偏离默认值的
+* override 才会落盘。仅启动 openspecui 或仅依赖默认配置时，不应触发文件写入。
 */
 var ConfigManager = class {
 	configPath;
@@ -2359,18 +2387,11 @@ var ConfigManager = class {
 		this.projectDir = projectDir;
 		this.configPath = join(projectDir, "openspec", ".openspecui.json");
 	}
-	/**
-	* 读取配置（响应式）
-	*
-	* 如果配置文件不存在，返回默认配置。
-	* 如果配置文件格式错误，返回默认配置并打印警告。
-	*/
-	async readConfig() {
-		const content = await reactiveReadFile(this.configPath);
+	parseConfigContent(content) {
 		if (!content) return DEFAULT_CONFIG;
 		try {
-			const parsed = JSON.parse(content);
-			const result = OpenSpecUIConfigSchema.safeParse(parsed);
+			const normalized = pruneNullish(JSON.parse(content)) ?? {};
+			const result = OpenSpecUIConfigSchema.safeParse(normalized);
 			if (result.success) return result.data;
 			console.warn("Invalid config format, using defaults:", result.error.message);
 			return DEFAULT_CONFIG;
@@ -2380,12 +2401,24 @@ var ConfigManager = class {
 		}
 	}
 	/**
+	* 读取配置（响应式）
+	*
+	* 如果配置文件不存在，返回默认配置。
+	* 如果配置文件格式错误，返回默认配置并打印警告。
+	*/
+	async readConfig() {
+		const content = await reactiveReadFile(this.configPath);
+		return this.parseConfigContent(content);
+	}
+	/**
 	* 写入配置
 	*
 	* 会触发文件监听，自动更新订阅者。
 	*/
 	async writeConfig(config) {
-		const current = await this.readConfig();
+		const currentContent = await reactiveReadFile(this.configPath);
+		const fileExists = currentContent !== null;
+		const current = this.parseConfigContent(currentContent);
 		const nextCli = { ...current.cli };
 		if (config.cli && Object.prototype.hasOwnProperty.call(config.cli, "command")) {
 			const trimmed = config.cli.command?.trim();
@@ -2401,7 +2434,7 @@ var ConfigManager = class {
 			else delete nextCli.args;
 		}
 		if (!nextCli.command) delete nextCli.args;
-		const merged = {
+		const persisted = toPersistedConfig({
 			...current,
 			cli: nextCli,
 			theme: config.theme ?? current.theme,
@@ -2418,13 +2451,25 @@ var ConfigManager = class {
 				...current.dashboard,
 				...config.dashboard
 			}
-		};
-		const serialized = JSON.stringify(merged, null, 2);
+		});
+		if (isPersistedConfigEmpty(persisted) && !fileExists) return;
+		const serialized = isPersistedConfigEmpty(persisted) ? "{}" : JSON.stringify(persisted, null, 2);
+		if (currentContent === serialized) return;
 		await mkdir(dirname(this.configPath), { recursive: true });
 		await writeFile(this.configPath, serialized, "utf-8");
 		updateReactiveFileCache(this.configPath, serialized);
 		this.invalidateResolvedCliRunner();
 	}
+	async resolveDefaultCliCommandParts() {
+		return (await resolveCliRunner(buildCliRunnerCandidates({ userAgent: process.env.npm_config_user_agent }).filter((candidate) => candidate.id !== "configured"), this.projectDir, createCleanCliEnv())).commandParts;
+	}
+	async isDefaultCliCommand(commandParts) {
+		try {
+			return areStringArraysEqual(commandParts, await this.resolveDefaultCliCommandParts());
+		} catch {
+			return false;
+		}
+	}
 	/**
 	* 解析并缓存可用 CLI runner。
 	*/
@@ -2442,8 +2487,7 @@ var ConfigManager = class {
 	async resolveCliRunnerUncached() {
 		const config = await this.readConfig();
 		const configuredCommandParts = this.getConfiguredCommandParts(config.cli);
-		const hasConfiguredCommand = configuredCommandParts.length > 0;
-		const resolved = await resolveCliRunner(hasConfiguredCommand ? [{
+		return await resolveCliRunner(configuredCommandParts.length > 0 ? [{
 			id: "configured",
 			source: "config.cli.command",
 			commandParts: configuredCommandParts
@@ -2451,20 +2495,6 @@ var ConfigManager = class {
 			configuredCommandParts,
 			userAgent: process.env.npm_config_user_agent
 		}), this.projectDir, createCleanCliEnv());
-		if (!hasConfiguredCommand) {
-			const [resolvedCommand, ...resolvedArgs] = resolved.commandParts;
-			const currentCommand = config.cli.command?.trim();
-			const currentArgs = config.cli.args ?? [];
-			if (currentCommand !== resolvedCommand || currentArgs.length !== resolvedArgs.length || currentArgs.some((arg, index) => arg !== resolvedArgs[index])) try {
-				await this.writeConfig({ cli: {
-					command: resolvedCommand,
-					args: resolvedArgs
-				} });
-			} catch (err) {
-				console.warn("Failed to persist auto-detected CLI command:", err);
-			}
-		}
-		return resolved;
 	}
 	/**
 	* 获取 CLI 命令（数组形式）
@@ -2511,6 +2541,13 @@ var ConfigManager = class {
 			} });
 			return;
 		}
+		if (await this.isDefaultCliCommand(commandParts)) {
+			await this.writeConfig({ cli: {
+				command: null,
+				args: null
+			} });
+			return;
+		}
 		const [resolvedCommand, ...resolvedArgs] = commandParts;
 		await this.writeConfig({ cli: {
 			command: resolvedCommand,
@@ -2823,9 +2860,36 @@ var CliExecutor = class {
 	}
 	/**
 	* 流式执行任意命令（数组形式）
+	*
+	* 字面量 `openspec` 会自动通过已解析的 CLI runner 执行，
+	* 其它命令保持原始 spawn 行为。
 	*/
 	executeCommandStream(command, onEvent) {
 		const [cmd, ...cmdArgs] = command;
+		if (cmd === "openspec") {
+			let cancelResolved = null;
+			let cancelled = false;
+			this.executeStream([...cmdArgs], onEvent).then((cancel) => {
+				if (cancelled) {
+					cancel();
+					return;
+				}
+				cancelResolved = cancel;
+			}).catch((err) => {
+				onEvent({
+					type: "stderr",
+					data: err instanceof Error ? err.message : String(err)
+				});
+				onEvent({
+					type: "exit",
+					exitCode: null
+				});
+			});
+			return () => {
+				cancelled = true;
+				cancelResolved?.();
+			};
+		}
 		onEvent({
 			type: "command",
 			data: command.join(" ")
@@ -3067,12 +3131,6 @@ const AI_TOOLS = [
 		available: true,
 		successLabel: "Windsurf",
 		skillsDir: ".windsurf"
-	},
-	{
-		name: "AGENTS.md (works with Amp, VS Code, …)",
-		value: "agents",
-		available: false,
-		successLabel: "your AGENTS.md-compatible assistant"
 	}
 ];
 /**
@@ -3088,13 +3146,25 @@ function getAvailableToolIds() {
 	return getAvailableTools().map((tool) => tool.value);
 }
 /**
-* 获取所有工具（包括 available: false 的）
+* 获取所有工具
 */
 function getAllTools() {
 	return AI_TOOLS;
 }
 /**
-* 获取所有工具 ID 列表（包括 available: false 的）
+* 检测当前项目中已经存在的工具目录。
+*
+* 这里对齐 OpenSpec 官方 `getAvailableTools(projectPath)` 的语义：
+* 仅根据项目根目录下的工具目录是否存在来判断，不读取全局命令安装状态。
+*/
+async function getDetectedProjectTools(projectDir) {
+	return (await Promise.all(AI_TOOLS.map(async (tool) => {
+		if (!tool.skillsDir) return null;
+		return await reactiveExists(join$1(projectDir, tool.skillsDir)) ? tool : null;
+	}))).filter((tool) => tool !== null);
+}
+/**
+* 获取所有工具 ID 列表
 */
 function getAllToolIds() {
 	return AI_TOOLS.map((tool) => tool.value);
@@ -3173,6 +3243,143 @@ async function isToolConfigured(projectDir, toolId) {
 	return (await getConfiguredTools(projectDir)).includes(toolId);
 }
 
+//#endregion
+//#region src/tool-init-state.ts
+const TOOL_WORKFLOW_TO_SKILL_DIR = {
+	propose: "openspec-propose",
+	explore: "openspec-explore",
+	new: "openspec-new-change",
+	continue: "openspec-continue-change",
+	apply: "openspec-apply-change",
+	ff: "openspec-ff-change",
+	sync: "openspec-sync-specs",
+	archive: "openspec-archive-change",
+	"bulk-archive": "openspec-bulk-archive-change",
+	verify: "openspec-verify-change",
+	onboard: "openspec-onboard"
+};
+const ALL_TOOL_WORKFLOWS = Object.keys(TOOL_WORKFLOW_TO_SKILL_DIR);
+function toKnownWorkflows(workflows) {
+	return workflows.filter((workflow) => workflow in TOOL_WORKFLOW_TO_SKILL_DIR);
+}
+function resolveCodexHome() {
+	const configuredHome = process.env.CODEX_HOME?.trim();
+	return resolve(configuredHome ? configuredHome : join$1(homedir(), ".codex"));
+}
+function resolveToolCommandPath(projectDir, toolId, workflow) {
+	switch (toolId) {
+		case "amazon-q": return resolve(projectDir, ".amazonq", "prompts", `opsx-${workflow}.md`);
+		case "antigravity": return resolve(projectDir, ".agent", "workflows", `opsx-${workflow}.md`);
+		case "auggie": return resolve(projectDir, ".augment", "commands", `opsx-${workflow}.md`);
+		case "claude": return resolve(projectDir, ".claude", "commands", "opsx", `${workflow}.md`);
+		case "cline": return resolve(projectDir, ".clinerules", "workflows", `opsx-${workflow}.md`);
+		case "codebuddy": return resolve(projectDir, ".codebuddy", "commands", "opsx", `${workflow}.md`);
+		case "codex": return resolve(resolveCodexHome(), "prompts", `opsx-${workflow}.md`);
+		case "continue": return resolve(projectDir, ".continue", "prompts", `opsx-${workflow}.prompt`);
+		case "costrict": return resolve(projectDir, ".cospec", "openspec", "commands", `opsx-${workflow}.md`);
+		case "crush": return resolve(projectDir, ".crush", "commands", "opsx", `${workflow}.md`);
+		case "cursor": return resolve(projectDir, ".cursor", "commands", `opsx-${workflow}.md`);
+		case "factory": return resolve(projectDir, ".factory", "commands", `opsx-${workflow}.md`);
+		case "gemini": return resolve(projectDir, ".gemini", "commands", "opsx", `${workflow}.toml`);
+		case "github-copilot": return resolve(projectDir, ".github", "prompts", `opsx-${workflow}.prompt.md`);
+		case "iflow": return resolve(projectDir, ".iflow", "commands", `opsx-${workflow}.md`);
+		case "kilocode": return resolve(projectDir, ".kilocode", "workflows", `opsx-${workflow}.md`);
+		case "kiro": return resolve(projectDir, ".kiro", "prompts", `opsx-${workflow}.prompt.md`);
+		case "opencode": return resolve(projectDir, ".opencode", "command", `opsx-${workflow}.md`);
+		case "pi": return resolve(projectDir, ".pi", "prompts", `opsx-${workflow}.md`);
+		case "qoder": return resolve(projectDir, ".qoder", "commands", "opsx", `${workflow}.md`);
+		case "qwen": return resolve(projectDir, ".qwen", "commands", `opsx-${workflow}.toml`);
+		case "roocode": return resolve(projectDir, ".roo", "commands", `opsx-${workflow}.md`);
+		case "windsurf": return resolve(projectDir, ".windsurf", "workflows", `opsx-${workflow}.md`);
+		default: return null;
+	}
+}
+function getSkillArtifacts(projectDir, skillsDir) {
+	return ALL_TOOL_WORKFLOWS.map((workflow) => ({
+		workflow,
+		path: resolve(projectDir, skillsDir, "skills", TOOL_WORKFLOW_TO_SKILL_DIR[workflow], "SKILL.md")
+	}));
+}
+function getCommandArtifacts(projectDir, toolId) {
+	return ALL_TOOL_WORKFLOWS.flatMap((workflow) => {
+		const path = resolveToolCommandPath(projectDir, toolId, workflow);
+		return path ? [{
+			workflow,
+			path
+		}] : [];
+	});
+}
+function invalidateToolInitCaches(projectDir) {
+	const cacheRoots = /* @__PURE__ */ new Set();
+	for (const tool of AI_TOOLS) {
+		if (tool.skillsDir) cacheRoots.add(resolve(projectDir, tool.skillsDir));
+		for (const workflow of ALL_TOOL_WORKFLOWS) {
+			const commandPath = resolveToolCommandPath(projectDir, tool.value, workflow);
+			if (commandPath) cacheRoots.add(dirname$1(commandPath));
+		}
+	}
+	for (const root of cacheRoots) clearCache(root);
+}
+async function getExistingArtifactPaths(entries) {
+	const presence = await Promise.all(entries.map(async (entry) => ({
+		path: entry.path,
+		exists: await reactiveExists(entry.path)
+	})));
+	return new Set(presence.filter((entry) => entry.exists).map((entry) => entry.path));
+}
+function countExisting(entries, existingPaths) {
+	return entries.reduce((count, entry) => count + (existingPaths.has(entry.path) ? 1 : 0), 0);
+}
+function collectMissingWorkflows(entries, existingPaths) {
+	return entries.filter((entry) => !existingPaths.has(entry.path)).map((entry) => entry.workflow);
+}
+function collectUnexpectedWorkflows(entries, desiredWorkflowSet, existingPaths) {
+	return entries.filter((entry) => !desiredWorkflowSet.has(entry.workflow) && existingPaths.has(entry.path)).map((entry) => entry.workflow);
+}
+async function getToolInitStates(projectDir, options) {
+	invalidateToolInitCaches(projectDir);
+	const desiredWorkflows = toKnownWorkflows(options.workflows);
+	const desiredWorkflowSet = new Set(desiredWorkflows);
+	const shouldGenerateSkills = options.delivery !== "commands";
+	const shouldGenerateCommands = options.delivery !== "skills";
+	return Promise.all(AI_TOOLS.filter((tool) => tool.skillsDir).map(async (tool) => {
+		const skillArtifacts = getSkillArtifacts(projectDir, tool.skillsDir);
+		const commandArtifacts = getCommandArtifacts(projectDir, tool.value);
+		const existingSkillPaths = await getExistingArtifactPaths(skillArtifacts);
+		const existingCommandPaths = await getExistingArtifactPaths(commandArtifacts);
+		const expectedSkillArtifacts = shouldGenerateSkills ? skillArtifacts.filter((entry) => desiredWorkflowSet.has(entry.workflow)) : [];
+		const expectedCommandArtifacts = shouldGenerateCommands ? commandArtifacts.filter((entry) => desiredWorkflowSet.has(entry.workflow)) : [];
+		const missingSkillWorkflows = collectMissingWorkflows(expectedSkillArtifacts, existingSkillPaths);
+		const missingCommandWorkflows = collectMissingWorkflows(expectedCommandArtifacts, existingCommandPaths);
+		const unexpectedSkillWorkflows = collectUnexpectedWorkflows(shouldGenerateSkills ? skillArtifacts : skillArtifacts, shouldGenerateSkills ? desiredWorkflowSet : /* @__PURE__ */ new Set(), existingSkillPaths);
+		const unexpectedCommandWorkflows = collectUnexpectedWorkflows(shouldGenerateCommands ? commandArtifacts : commandArtifacts, shouldGenerateCommands ? desiredWorkflowSet : /* @__PURE__ */ new Set(), existingCommandPaths);
+		const expectedSkillCount = expectedSkillArtifacts.length;
+		const presentExpectedSkillCount = expectedSkillCount - missingSkillWorkflows.length;
+		const detectedSkillCount = countExisting(skillArtifacts, existingSkillPaths);
+		const expectedCommandCount = expectedCommandArtifacts.length;
+		const presentExpectedCommandCount = expectedCommandCount - missingCommandWorkflows.length;
+		const detectedCommandCount = countExisting(commandArtifacts, existingCommandPaths);
+		const hasAnyArtifacts = detectedSkillCount + detectedCommandCount > 0;
+		const isInitialized = missingSkillWorkflows.length === 0 && missingCommandWorkflows.length === 0 && unexpectedSkillWorkflows.length === 0 && unexpectedCommandWorkflows.length === 0;
+		return {
+			toolId: tool.value,
+			toolName: tool.name,
+			status: !hasAnyArtifacts ? "uninitialized" : isInitialized ? "initialized" : "partial",
+			hasAnyArtifacts,
+			expectedSkillCount,
+			presentExpectedSkillCount,
+			detectedSkillCount,
+			expectedCommandCount,
+			presentExpectedCommandCount,
+			detectedCommandCount,
+			missingSkillWorkflows,
+			missingCommandWorkflows,
+			unexpectedSkillWorkflows,
+			unexpectedCommandWorkflows
+		};
+	}));
+}
+
 //#endregion
 //#region src/dashboard-types.ts
 const DASHBOARD_METRIC_KEYS = [
@@ -4079,4 +4286,4 @@ const PtyServerMessageSchema = z.discriminatedUnion("type", [
 ]);
 
 //#endregion
-export { AI_TOOLS, ApplyInstructionsSchema, ApplyTaskSchema, ArtifactInstructionsSchema, ArtifactStatusSchema, CODE_EDITOR_THEME_VALUES, ChangeFileSchema, ChangeSchema, ChangeStatusSchema, CliExecutor, CodeEditorThemeSchema, ConfigManager, DASHBOARD_METRIC_KEYS, DEFAULT_CONFIG, DashboardConfigSchema, DeltaOperationType, DeltaSchema, DeltaSpecSchema, DependencyInfoSchema, MarkdownParser, OFFICIAL_APP_BASE_URL, OpenSpecAdapter, OpenSpecUIConfigSchema, OpenSpecWatcher, OpsxKernel, ProjectWatcher, PtyAttachMessageSchema, PtyBufferResponseSchema, PtyClientMessageSchema, PtyCloseMessageSchema, PtyCreateMessageSchema, PtyCreatedResponseSchema, PtyErrorCodeSchema, PtyErrorResponseSchema, PtyExitResponseSchema, PtyInputMessageSchema, PtyListMessageSchema, PtyListResponseSchema, PtyOutputResponseSchema, PtyPlatformSchema, PtyResizeMessageSchema, PtyServerMessageSchema, PtyTitleResponseSchema, ReactiveContext, ReactiveState, RequirementSchema, SchemaArtifactSchema, SchemaDetailSchema, SchemaInfoSchema, SchemaResolutionSchema, SpecSchema, TaskSchema, TemplatesSchema, TerminalConfigSchema, TerminalRendererEngineSchema, VIRTUAL_PROJECT_DIRNAME, Validator, acquireWatcher, buildCliRunnerCandidates, buildHostedLaunchUrl, buildHostedVersionManifestUrl, clearCache, closeAllProjectWatchers, closeAllWatchers, contextStorage, createCleanCliEnv, createFileChangeObservable, getActiveWatcherCount, getAllToolIds, getAllTools, getAvailableToolIds, getAvailableTools, getCacheSize, getConfiguredTools, getDefaultCliCommand, getDefaultCliCommandString, getProjectWatcher, getToolById, getWatchedProjectDir, getWatcherRuntimeStatus, initWatcherPool, isGlobPattern, isHostedAppVersionManifest, isHostedBackendHealthResponse, isTerminalRendererEngine, isToolConfigured, isWatcherPoolInitialized, normalizeHostedAppBaseUrl, parseCliCommand, reactiveExists, reactiveReadDir, reactiveReadFile, reactiveStat, resolveHostedAppBaseUrl, resolveHostedChannelForVersion, sniffGlobalCli, toOpsxDisplayPath };
+export { AI_TOOLS, ApplyInstructionsSchema, ApplyTaskSchema, ArtifactInstructionsSchema, ArtifactStatusSchema, CODE_EDITOR_THEME_VALUES, ChangeFileSchema, ChangeSchema, ChangeStatusSchema, CliExecutor, CodeEditorThemeSchema, ConfigManager, DASHBOARD_METRIC_KEYS, DEFAULT_CONFIG, DashboardConfigSchema, DeltaOperationType, DeltaSchema, DeltaSpecSchema, DependencyInfoSchema, MarkdownParser, OFFICIAL_APP_BASE_URL, OpenSpecAdapter, OpenSpecUIConfigSchema, OpenSpecWatcher, OpsxKernel, ProjectWatcher, PtyAttachMessageSchema, PtyBufferResponseSchema, PtyClientMessageSchema, PtyCloseMessageSchema, PtyCreateMessageSchema, PtyCreatedResponseSchema, PtyErrorCodeSchema, PtyErrorResponseSchema, PtyExitResponseSchema, PtyInputMessageSchema, PtyListMessageSchema, PtyListResponseSchema, PtyOutputResponseSchema, PtyPlatformSchema, PtyResizeMessageSchema, PtyServerMessageSchema, PtyTitleResponseSchema, ReactiveContext, ReactiveState, RequirementSchema, SchemaArtifactSchema, SchemaDetailSchema, SchemaInfoSchema, SchemaResolutionSchema, SpecSchema, TOOL_WORKFLOW_TO_SKILL_DIR, TaskSchema, TemplatesSchema, TerminalConfigSchema, TerminalRendererEngineSchema, VIRTUAL_PROJECT_DIRNAME, Validator, acquireWatcher, buildCliRunnerCandidates, buildHostedLaunchUrl, buildHostedVersionManifestUrl, clearCache, closeAllProjectWatchers, closeAllWatchers, contextStorage, createCleanCliEnv, createFileChangeObservable, getActiveWatcherCount, getAllToolIds, getAllTools, getAvailableToolIds, getAvailableTools, getCacheSize, getConfiguredTools, getDefaultCliCommand, getDefaultCliCommandString, getDetectedProjectTools, getProjectWatcher, getToolById, getToolInitStates, getWatchedProjectDir, getWatcherRuntimeStatus, initWatcherPool, isGlobPattern, isHostedAppVersionManifest, isHostedBackendHealthResponse, isTerminalRendererEngine, isToolConfigured, isWatcherPoolInitialized, normalizeHostedAppBaseUrl, parseCliCommand, reactiveExists, reactiveReadDir, reactiveReadFile, reactiveStat, resolveHostedAppBaseUrl, resolveHostedChannelForVersion, sniffGlobalCli, toOpsxDisplayPath };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openspecui/core",
-  "version": "2.1.2",
+  "version": "2.1.3",
   "description": "Core OpenSpec adapter and parser",
   "type": "module",
   "main": "./dist/index.mjs",