@gird/ccli 2.15.0 → 2.18.0

package/dist/harness/index.js

@@ -0,0 +1,334 @@
+/**
+ * CCLI Harness 边界。
+ *
+ * 这一层先做薄封装：把配置解析、AI client、MCP/skill 工具注册、记忆注入、
+ * hooks 与 runAgentTurn 入口收拢起来。CLI 仍负责 readline、确认弹窗和渲染，
+ * 后续 Web / Server / SDK 可从这里继续扩展，而不是直接耦合 cli/run。
+ */
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { NAME, VERSION } from '../version.js';
+import { createAIClient, } from '../agent/ai.js';
+import { McpClientManager } from '../agent/mcp.js';
+import { DEFAULT_SYSTEM_PROMPT, getRolePrompt, loadConfig, resolveMaxStepsPerTurn, } from '../config/config.js';
+import { loadEnvFile } from '../config/env.js';
+import { appendMemories, loadMemories } from '../config/memory.js';
+import { loadSkills } from '../config/skills.js';
+import { makeSkillTool } from '../tools/skill-tool.js';
+import { registerMcpTools, registerTool, resetTools, } from '../tools/index.js';
+import { runAgentTurn, runOnce as runOnceTurn, } from '../cli/run/index.js';
+import { runHooks, runUserPromptHooks, } from '../cli/run/hooks.js';
+import { defaultName } from '../cli/session/index.js';
+import { defaultRecordsDir, pruneRecordsDir, RecordsWriter, } from './records.js';
+export class CcliHarness {
+    /** Harness 绑定的工作目录；配置、记忆、技能、MCP 环境变量都以它为基准解析。 */
+    cwd;
+    /** 是否忽略配置文件里的 hooks；用于 `--no-hooks` 这类安全逃生场景。 */
+    noHooks;
+    /** 启动时扫描到的技能列表；REPL 用它做 `/skill` 补全与手动技能展开。 */
+    skills;
+    /** MCP server 启动时的连接错误；调用方负责决定如何展示给用户。 */
+    mcpErrors;
+    /** 当前生效配置；`reloadConfig()` 后会被替换为最新配置。 */
+    config;
+    /** 当前 AI client；切换/重载配置后会按新配置重新创建。 */
+    ai;
+    /** 当前注入 system prompt 的记忆快照；`refreshMemories()` 会重新读取。 */
+    memories;
+    /** 当前 MCP manager；没有 MCP 配置时为 null，退出时由 `close()` 统一清理。 */
+    mcpManager;
+    /** 当前会话 ID（用于快照备份与 records 文件命名）。 */
+    sessionId;
+    /** 会话事件记录目录。 */
+    recordsDir;
+    /** 解析并获取当前应生效的快照备份基准目录。 */
+    get checkpointsDir() {
+        const mode = this.config.checkpoint?.mode ?? 'local';
+        const customPath = this.config.checkpoint?.path;
+        if (customPath) {
+            return resolve(this.cwd, customPath);
+        }
+        if (mode === 'global') {
+            return join(homedir(), '.ccli', 'checkpoints');
+        }
+        return this.cwd
+            ? join(this.cwd, '.ccli', 'checkpoints')
+            : join(homedir(), '.ccli', 'checkpoints');
+    }
+    /**
+     * 构造一个已初始化好的 Harness 实例。
+     *
+     * 一般业务代码应使用 `createCcliHarness()`，因为它会负责读取配置、连接 MCP、
+     * 扫描技能和加载记忆；构造函数主要给测试或未来更底层的组合场景使用。
+     */
+    constructor(options) {
+        this.cwd = options.cwd;
+        this.noHooks = options.noHooks;
+        this.config = options.config;
+        this.ai = options.ai;
+        this.skills = options.skills;
+        this.memories = options.memories;
+        this.mcpManager = options.mcpManager;
+        this.mcpErrors = options.mcpErrors;
+        this.sessionId = options.sessionId ?? 'test-session';
+        this.recordsDir = options.recordsDir ?? defaultRecordsDir();
+    }
+    /**
+     * 记录一条会话事件到 records（~/.ccli/records/<sessionId>.jsonl）。
+     * 每次调用按当前 sessionId 现取 writer（sessionId 可能被 /session 换掉）；
+     * 写入失败在 RecordsWriter 内部静默，绝不打断会话。
+     */
+    recordEvent(event) {
+        new RecordsWriter(this.recordsDir, this.sessionId).write(event);
+    }
+    /**
+     * 返回当前应生效的 hooks。
+     *
+     * 如果启动时指定了 `--no-hooks`，这里固定返回 `undefined`，让调用方无需重复判断。
+     */
+    get hooks() {
+        return this.noHooks ? undefined : this.config.hooks;
+    }
+    /**
+     * 根据角色名查找配置或内置角色的 system prompt。
+     *
+     * 只负责“查找”，找不到时返回 undefined；需要兜底默认提示词时用 `roleBasePrompt()`。
+     */
+    getRolePrompt(role) {
+        return getRolePrompt(role, this.config.roles);
+    }
+    /**
+     * 获取某个角色最终用于对话的基础提示词。
+     *
+     * 若角色不存在，则回退到 `DEFAULT_SYSTEM_PROMPT`。这一步还不注入记忆。
+     */
+    roleBasePrompt(role) {
+        return this.getRolePrompt(role) ?? DEFAULT_SYSTEM_PROMPT;
+    }
+    /**
+     * 构造最终 system prompt：基础提示词 + 当前记忆分层。
+     *
+     * REPL 切换角色或 `#` 写入记忆后，会用这个方法刷新 `history[0]`。
+     */
+    buildSystemPrompt(basePrompt = DEFAULT_SYSTEM_PROMPT) {
+        return appendMemories(basePrompt, this.memories);
+    }
+    /**
+     * 创建一个新的会话历史数组。
+     *
+     * 返回值第一条固定是带记忆的 system 消息；后续 user / assistant / tool 消息由调用方追加。
+     */
+    createHistory(role = 'default') {
+        return [
+            {
+                role: 'system',
+                content: this.buildSystemPrompt(this.roleBasePrompt(role)),
+            },
+        ];
+    }
+    /**
+     * 重新读取全局 / 项目 / 子目录记忆，并更新 Harness 内部快照。
+     *
+     * 典型场景是用户在 REPL 里输入 `# xxx` 动态写入项目记忆后，立即让当前会话生效。
+     */
+    refreshMemories() {
+        this.memories = loadMemories(this.cwd);
+        return this.memories;
+    }
+    /**
+     * 解析当前配置里的单回合工具调用上限。
+     *
+     * 封装这层后，CLI 不需要知道 `maxStepsPerTurn` 的默认值和 `0=不限` 规则。
+     */
+    maxStepsPerTurn() {
+        return resolveMaxStepsPerTurn(this.config);
+    }
+    /**
+     * 执行一个交互式用户回合。
+     *
+     * 这是 `runAgentTurn()` 的 Harness 门面：自动注入当前 AI client、工具轮数上限和 hooks；
+     * CLI 仍传入 history、confirm、stats、permission 等交互态对象。
+     */
+    async runTurn(options) {
+        await runAgentTurn({
+            ...options,
+            sessionId: this.sessionId,
+            checkpointsDir: this.checkpointsDir,
+            ai: this.ai,
+            cwd: this.cwd,
+            configMaxSteps: options.configMaxSteps ?? this.maxStepsPerTurn(),
+            hooks: options.hooks ?? this.hooks,
+            record: options.record ?? ((e) => this.recordEvent(e)),
+        });
+    }
+    /**
+     * 执行一个交互式用户回合，并把输出转成结构化事件。
+     *
+     * 这是给未来 Web / Server / SDK 使用的旁路 API：文本输出走 `text_delta`，
+     * 工具调用走 `tool_call`，工具完成走 `tool_result`。终端 CLI 仍继续用 `runTurn()`。
+     */
+    async runTurnWithEvents(options) {
+        try {
+            await this.runTurn({
+                ...options,
+                print: (text) => options.emit({ type: 'text_delta', text }),
+                onReasoning: (text) => options.emit({ type: 'reasoning_delta', text }),
+                onHookOutput: (text) => options.emit({ type: 'hook_output', text }),
+                onPermissionRequest: (info) => options.emit({ type: 'permission_request', ...info }),
+                onToolCall: (toolCall) => options.emit({ type: 'tool_call', toolCall }),
+                onToolResult: (toolCall, result) => options.emit({ type: 'tool_result', toolCall, result }),
+            });
+        }
+        catch (e) {
+            // 回合异常也作为结构化事件抛出，便于前端渲染错误卡片；同时向上抛保留原有控制流
+            options.emit({ type: 'turn_error', error: e?.message ?? String(e) });
+            throw e;
+        }
+    }
+    /**
+     * 执行一次非交互式请求。
+     *
+     * 用于 `ccli "prompt"` / stdin 管道模式。Harness 负责注入 AI、system prompt、hooks 和轮数上限；
+     * 调用方只需要提供 prompt、确认策略和可选输出函数。
+     */
+    async runOnce(options) {
+        return runOnceTurn({
+            sessionId: options.sessionId ?? this.sessionId,
+            checkpointsDir: options.checkpointsDir ?? this.checkpointsDir,
+            ai: this.ai,
+            prompt: options.prompt,
+            confirm: options.confirm,
+            print: options.print,
+            cwd: this.cwd,
+            systemPrompt: options.systemPrompt ?? this.buildSystemPrompt(),
+            configMaxSteps: this.maxStepsPerTurn(),
+            hooks: this.hooks,
+            record: (e) => this.recordEvent(e),
+        });
+    }
+    /**
+     * 执行一次非交互式请求，并把输出转成结构化事件。
+     *
+     * 与 `runOnce()` 的用户语义相同，但输出不直接绑定终端文本；CLI / Web / Server
+     * 可以各自传入不同的 `emit` 消费事件。
+     */
+    async runOnceWithEvents(options) {
+        const history = [
+            {
+                role: 'system',
+                content: options.systemPrompt ?? this.buildSystemPrompt(),
+            },
+            { role: 'user', content: options.prompt },
+        ];
+        await this.runTurnWithEvents({
+            history,
+            confirm: options.confirm,
+            stats: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            emit: options.emit,
+        });
+    }
+    /**
+     * 触发 SessionStart hooks。
+     *
+     * `source` 用来区分 REPL 会话和非交互单次调用，便于用户 hook 脚本做不同处理。
+     */
+    runSessionStart(source) {
+        return runHooks(this.hooks, 'SessionStart', {
+            cwd: this.cwd,
+            source,
+        });
+    }
+    /**
+     * 触发 SessionEnd hooks。
+     *
+     * 退出清理阶段也会尽量调用；如果 hooks 被禁用，则底层会直接返回空结果。
+     */
+    runSessionEnd() {
+        return runHooks(this.hooks, 'SessionEnd', { cwd: this.cwd });
+    }
+    /**
+     * 运行 UserPromptSubmit hooks，并返回可能被补充上下文后的 prompt。
+     *
+     * hook 可以拦截本次输入，也可以把 stdout 追加为“hook 补充上下文”。
+     */
+    runUserPromptHooks(prompt) {
+        return runUserPromptHooks(this.hooks, this.cwd, prompt);
+    }
+    /**
+     * 重新读取配置并刷新 Harness 中的 config 与 AI client。
+     *
+     * 注意：这个方法只负责配置和模型客户端；MCP server 的重连仍由 `/reload` / `/mcp reload`
+     * 走既有的 `reloadMcpServers()`，避免本步改变用户可见行为。
+     */
+    reloadConfig() {
+        const result = loadConfig(this.cwd);
+        if (!result.ok)
+            return result;
+        this.config = result.config;
+        this.ai = createAIClient(this.config);
+        return { ok: true, config: this.config };
+    }
+    /**
+     * 关闭 Harness 持有的外部资源。
+     *
+     * 目前主要是关闭 MCP 连接；未来如果引入 server、records writer 或 telemetry flush，
+     * 也应统一收口到这里。
+     */
+    async close() {
+        await this.mcpManager?.closeAll();
+    }
+}
+/**
+ * 创建并初始化 CCLI Harness。
+ *
+ * 这是 CLI / 未来 Server 的统一入口：读取配置、加载 `.env`、连接 MCP、注册 MCP/skill 工具、
+ * 加载记忆并创建 AI client。失败时返回 `{ ok:false }`，不直接退出进程，方便不同前端自行处理。
+ */
+export async function createCcliHarness(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const result = loadConfig(cwd);
+    if (!result.ok)
+        return result;
+    const config = result.config;
+    const dotenv = loadEnvFile(join(cwd, '.env'));
+    const envLookup = (name) => process.env[name] ?? dotenv[name];
+    const mcpErrors = [];
+    let mcpManager = null;
+    if (config.mcpServers && Object.keys(config.mcpServers).length > 0) {
+        resetTools();
+        mcpManager = new McpClientManager(config.mcpServers, { name: NAME, version: VERSION }, envLookup);
+        const errors = await mcpManager.connectAll();
+        mcpErrors.push(...errors);
+        for (const error of errors) {
+            options.onMcpError?.(error);
+        }
+        await registerMcpTools(mcpManager);
+    }
+    const skills = loadSkills(cwd);
+    const skillTool = makeSkillTool(skills);
+    if (skillTool)
+        registerTool(skillTool);
+    // records 轮转清理：每次启动删一次过期/超量文件，失败静默（不挡启动）
+    try {
+        pruneRecordsDir(options.recordsDir ?? defaultRecordsDir());
+    }
+    catch {
+        // 清理失败不影响启动
+    }
+    return {
+        ok: true,
+        harness: new CcliHarness({
+            cwd,
+            noHooks: options.noHooks ?? false,
+            config,
+            ai: createAIClient(config),
+            skills,
+            memories: loadMemories(cwd),
+            mcpManager,
+            mcpErrors,
+            sessionId: defaultName(),
+            recordsDir: options.recordsDir,
+        }),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/harness/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/harness/index.ts"],"names":[],"mappings":"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"}

package/dist/harness/records.js

@@ -0,0 +1,98 @@
+/**
+ * 会话事件记录（records）。
+ *
+ * 把每个回合的结构化事件以「一行一个 JSON」追加到
+ * `~/.ccli/records/<sessionId>.jsonl`，面向复盘执行过程：
+ * 用户在什么时候说了什么、模型每轮回答了什么、调了哪些工具、
+ * 工具返回了什么、回合怎么结束的。
+ *
+ * 与 ~/.ccli/sessions/*.json（对话快照，供 /save、/load）互补：
+ * 快照用于恢复对话，records 用于还原「执行过程」（带时间戳与单轮边界）。
+ *
+ * 底线：记录是旁观者——任何写入失败都静默吞掉，绝不能打断会话。
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** 默认记录目录：~/.ccli/records。 */
+export function defaultRecordsDir() {
+    return join(homedir(), '.ccli', 'records');
+}
+/** sessionId 用作文件名：非字母数字字符转成 _，避免路径问题。 */
+function safeFileName(sessionId) {
+    return sessionId.replace(/[^a-zA-Z0-9._-]/g, '_') || 'session';
+}
+/**
+ * 某个会话的记录写入器。
+ * 每次 write 直接 appendFileSync（操作系统负责追加原子性），失败静默。
+ */
+export class RecordsWriter {
+    dir;
+    sessionId;
+    constructor(dir, sessionId) {
+        this.dir = dir;
+        this.sessionId = sessionId;
+    }
+    get filePath() {
+        return join(this.dir, `${safeFileName(this.sessionId)}.jsonl`);
+    }
+    /** 追加一条事件；任何失败（磁盘满、权限等）都不抛出。 */
+    write(event) {
+        try {
+            mkdirSync(this.dir, { recursive: true });
+            const line = JSON.stringify({ ts: new Date().toISOString(), ...event }) +
+                '\n';
+            appendFileSync(this.filePath, line, 'utf8');
+        }
+        catch {
+            // 记录绝不能打断会话
+        }
+    }
+}
+/** records 保留上限：最近多少个会话文件。 */
+export const MAX_RECORD_FILES = 50;
+/** records 保留上限：多少天内没更新过的文件删除。 */
+export const MAX_RECORD_AGE_DAYS = 30;
+/**
+ * 轮转清理 records 目录（启动时调用一次）：
+ * 先删超过 maxAgeDays 没更新的 jsonl，再按数量上限从最旧的开始删。
+ * 任何异常（目录不存在、权限问题）都静默，返回实际删除的文件数。
+ */
+export function pruneRecordsDir(dir, options = {}) {
+    const maxFiles = options.maxFiles ?? MAX_RECORD_FILES;
+    const maxAgeDays = options.maxAgeDays ?? MAX_RECORD_AGE_DAYS;
+    const now = options.now ?? Date.now();
+    try {
+        if (!existsSync(dir))
+            return 0;
+        const files = readdirSync(dir)
+            .filter((f) => f.endsWith('.jsonl'))
+            .map((f) => {
+            const path = join(dir, f);
+            return { path, mtime: statSync(path).mtime.getTime() };
+        });
+        const ageLimit = maxAgeDays * 24 * 60 * 60 * 1000;
+        const fresh = files.filter((f) => now - f.mtime <= ageLimit);
+        const doomed = new Set(files.filter((f) => now - f.mtime > ageLimit).map((f) => f.path));
+        // 数量仍超限 → 从最旧的继续删
+        const byAge = [...fresh].sort((a, b) => a.mtime - b.mtime);
+        for (let i = 0; i < Math.max(0, byAge.length - maxFiles); i++) {
+            doomed.add(byAge[i].path);
+        }
+        let deleted = 0;
+        for (const path of doomed) {
+            try {
+                unlinkSync(path);
+                deleted++;
+            }
+            catch {
+                // 单个删除失败不影响其它
+            }
+        }
+        return deleted;
+    }
+    catch {
+        return 0;
+    }
+}
+//# sourceMappingURL=records.js.map

package/dist/harness/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../../src/harness/records.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -12,20 +12,15 @@
  *   ccli                       启动交互式会话
  */
 import { parseArgs } from './cli/args/index.js';
-import { join } from 'node:path';
 import { NAME, VERSION } from './version.js';
 import { startRepl } from './cli/repl/index.js';
 import { style } from './cli/style.js';
-import { printConfig, loadConfig, getRolePrompt, DEFAULT_SYSTEM_PROMPT, resolveMaxStepsPerTurn, } from './config/config.js';
-import { loadEnvFile } from './config/env.js';
-import { loadMemories, appendMemories } from './config/memory.js';
-import { loadSkills } from './config/skills.js';
-import { registerTool } from './tools/index.js';
-import { makeSkillTool } from './tools/skill-tool.js';
-import { createAIClient } from './agent/ai.js';
-import { McpClientManager } from './agent/mcp.js';
-import { runOnce } from './cli/run/index.js';
+import { printConfig } from './config/config.js';
+import { printPlugins, installPlugin, uninstallPlugin, setPluginEnabled, } from './config/plugins.js';
+import { createCcliHarness } from './harness/index.js';
 import { injectFileReferences } from './cli/file-reference.js';
+import { extractImageReferences, buildUserContent, } from './cli/image-reference.js';
+import { createHarnessEventRenderer } from './cli/run/event-renderer.js';
 const HELP = `${NAME} v${VERSION}
 
 用法:
@@ -33,6 +28,7 @@ const HELP = `${NAME} v${VERSION}
 
 命令:
   config          打印当前解析出的配置（诊断用，密钥打码）
+  plugin          插件包管理：list / install <目录> [--project] / uninstall <名> / enable <名> / disable <名>
 
 选项:
   -v, --version        打印版本号
@@ -40,10 +36,16 @@ const HELP = `${NAME} v${VERSION}
   -y, --yes            非交互式模式下自动确认破坏性工具调用
   -r, --role <name>    非交互式模式下使用的系统提示词角色（默认 default）
       --no-hooks       禁用所有生命周期钩子（忽略配置中的 hooks）
+      --project        插件安装到项目级 .ccli/plugins/（配合 plugin install）
 
 示例:
   ccli                              启动交互式对话
   ccli config                       查看当前生效的后端 / 模型 / 密钥来源
+  ccli plugin                       查看已安装的插件包
+  ccli plugin install ./my-plugin   安装一个插件包到 ~/.ccli/plugins/
+  ccli plugin install ./p --project 安装到项目级 .ccli/plugins/
+  ccli plugin uninstall my-plugin   卸载某个插件
+  ccli plugin disable my-plugin     停用某个插件
   ccli --version                    查看版本
   ccli "解释这段报错"                非交互式单次调用
   cat file.ts | ccli "给这段代码加注释"  从 stdin 读取上下文
@@ -89,65 +91,108 @@ async function main() {
     if (command === 'config') {
         process.exit(printConfig());
     }
+    if (command === 'plugin' || command === 'plugins') {
+        const sub = args.positionals[1];
+        const arg = args.positionals[2];
+        if (!sub || sub === 'list') {
+            process.exit(printPlugins());
+        }
+        if (sub === 'install') {
+            if (!arg) {
+                console.error(style.error('用法：ccli plugin install <目录> [--project]'));
+                process.exit(1);
+            }
+            const r = installPlugin(arg, { project: args.project });
+            console.log(r.ok ? style.success(r.message) : style.error(r.message));
+            process.exit(r.ok ? 0 : 1);
+        }
+        if (sub === 'uninstall' || sub === 'remove') {
+            if (!arg) {
+                console.error(style.error(`用法：ccli plugin ${sub} <名称>`));
+                process.exit(1);
+            }
+            const r = uninstallPlugin(arg);
+            console.log(r.ok ? style.success(r.message) : style.error(r.message));
+            process.exit(r.ok ? 0 : 1);
+        }
+        if (sub === 'enable' || sub === 'disable') {
+            if (!arg) {
+                console.error(style.error(`用法：ccli plugin ${sub} <名称>`));
+                process.exit(1);
+            }
+            const r = setPluginEnabled(arg, sub === 'enable');
+            console.log(r.ok ? style.success(r.message) : style.error(r.message));
+            process.exit(r.ok ? 0 : 1);
+        }
+        console.error(style.error(`未知子命令：plugin ${sub}`));
+        console.error(style.muted('可用：list（默认） / install <目录> [--project] / uninstall <名> / enable <名> / disable <名>'));
+        process.exit(1);
+    }
     const promptFromArgs = args.positionals.join(' ').trim();
     const stdinText = (await readStdin()).trim();
-    const prompt = injectFileReferences(buildPrompt(promptFromArgs, stdinText), process.cwd());
+    // 先抽取 @图片（走多模态），再对剩余文本做 @文件 注入
+    const extracted = extractImageReferences(buildPrompt(promptFromArgs, stdinText), process.cwd());
+    for (const e of extracted.errors)
+        console.error(style.warn(e));
+    for (const n of extracted.notes)
+        console.error(style.muted(`（${n}）`));
+    const prompt = injectFileReferences(extracted.text, process.cwd());
     // 有 prompt 或 stdin 时，走非交互式单次调用
     if (prompt) {
-        const result = loadConfig();
+        const result = await createCcliHarness({ noHooks: args.noHooks });
         if (!result.ok) {
             console.error(style.error(result.message));
             process.exit(1);
         }
-        const { config } = result;
-        const ai = createAIClient(config);
+        const { harness } = result;
+        if (harness.mcpErrors.length > 0) {
+            console.error(style.error('部分 MCP server 连接失败：'));
+            for (const e of harness.mcpErrors) {
+                console.error(style.muted(`  ${e}`));
+            }
+        }
         const rolePrompt = args.role
-            ? getRolePrompt(args.role, config.roles)
+            ? harness.getRolePrompt(args.role)
             : undefined;
-        const systemPrompt = appendMemories(rolePrompt ?? DEFAULT_SYSTEM_PROMPT, loadMemories(process.cwd()));
-        // 把可供模型调用的技能注册成 skill 工具（技能 v3）
-        const skillTool = makeSkillTool(loadSkills(process.cwd()));
-        if (skillTool)
-            registerTool(skillTool);
+        const systemPrompt = harness.buildSystemPrompt(rolePrompt ?? harness.roleBasePrompt('default'));
         if (args.role &&
             rolePrompt === undefined &&
             args.role !== 'default') {
             console.error(style.warn(`未知角色：${args.role}，使用默认角色。`));
         }
-        // 连接 MCP server
-        const dotenv = loadEnvFile(join(process.cwd(), '.env'));
-        const envLookup = (name) => process.env[name] ?? dotenv[name];
-        let mcp = null;
-        if (config.mcpServers && Object.keys(config.mcpServers).length > 0) {
-            mcp = new McpClientManager(config.mcpServers, { name: NAME, version: VERSION }, envLookup);
-            const errors = await mcp.connectAll();
-            if (errors.length > 0) {
-                console.error(style.error('部分 MCP server 连接失败：'));
-                for (const e of errors)
-                    console.error(style.muted(`  ${e}`));
-            }
-        }
         const confirm = args.yes
             ? () => Promise.resolve('yes')
             : async (preview) => {
                 console.error(style.warn(`\n[非交互式模式] 需要确认以下操作，请添加 --yes 自动批准：\n${preview}`));
                 return 'no';
             };
+        // SessionStart hook：仅观察
+        const started = await harness.runSessionStart('once');
+        if (started.output)
+            console.log(started.output);
+        // UserPromptSubmit hook：可拦截输入；放行时 stdout 作为补充上下文追加
+        const submitted = await harness.runUserPromptHooks(prompt);
+        if (submitted.blocked) {
+            console.error(style.error(`输入被 UserPromptSubmit hook 拦截：${submitted.reason ?? ''}`));
+            process.exit(1);
+        }
+        const content = buildUserContent(submitted.prompt, extracted.images, harness.ai.supportsVision(), harness.ai.getModel());
         try {
-            await runOnce({
-                ai,
-                prompt,
+            await harness.runOnceWithEvents({
+                prompt: content,
                 confirm,
-                mcpManager: mcp ?? undefined,
                 systemPrompt,
-                configMaxSteps: resolveMaxStepsPerTurn(config),
-                hooks: args.noHooks ? undefined : config.hooks,
+                emit: createHarnessEventRenderer({
+                    print: process.stdout.write.bind(process.stdout),
+                }),
             });
         }
         finally {
-            if (mcp) {
-                await mcp.closeAll();
-            }
+            // SessionEnd hook：仅观察（出错也尽量触发）
+            const ended = await harness.runSessionEnd();
+            if (ended.output)
+                console.log(ended.output);
+            await harness.close();
         }
         return;
     }