@xingjisoft/neutrino 0.6.0 → 0.7.0

package/dist/web/session.js

@@ -1,4 +1,6 @@
+import { runPluginTurn, pluginCommand, pluginApprovalContext } from "../plugins/session.js";
 import path from "node:path";
+import { ApprovalQueue } from "./approvalQueue.js";
 /**
  * Headless conversation runner for the web UI.
  *
@@ -12,9 +14,11 @@ import path from "node:path";
  * (snapshot, stream, pause, resume, message) work unchanged.
  */
 import { randomUUID } from "node:crypto";
+import { FastAgentEngine } from "../fast/engine.js";
+import { FAST_MODE, assertFastAvailable, fastSettings } from "../fast/types.js";
 import { findModel, contextCompressionThreshold, modelContextWindow, sessionDir, intensityForModel, loadConfig, loadPlannerPrompt, loadStepPrompt, loadSubAgentPrompt, normalizeApprovalMode, planFirstEnabled, loadModels, loadAgentPrompt, normalizeAgentMode, saveSession, } from "../config.js";
 import { COMPACT_KEEP, planCompaction, transcriptFor, modelHistory, normalizeContext, } from "../compact.js";
-import { TaskRuntime, currentTask, linkSignals, taskLimits, resumeTaskSnapshot } from "../llm/runtime.js";
+import { TaskRuntime, TaskControlError, currentTask, linkSignals, taskLimits, taskBudgetScope, resumeTaskSnapshot } from "../llm/runtime.js";
 import { prepareContext, outputAllowance, finalTaskReport } from "../llm/context.js";
 import { FINISH_STEP_TOOL, FINISH_STEP_DEFINITION, finishPlanStep, preparePlan, settlePlan } from "../llm/plan.js";
 import { LLMClient, describeError } from "../llm/client.js";
@@ -34,7 +38,6 @@ const IDLE_DISPOSE_MS = 30 * 60 * 1000;
 /** Placeholder shown while a tool is still running. */
 const TOOL_PENDING = "…";
 /** A sub-agent gets the same tools minus delegation: one level, never a tree. */
-const SUB_AGENT_TOOLS = getSubAgentToolDefinitions();
 /** Marker for the model-only summary, separate from the original transcript. */
 const SUMMARY_PREFIX = "Context was compressed. Summary of the earlier part:";
 /**
@@ -50,6 +53,8 @@ export function newSessionId(now = new Date()) {
  * cannot litter the history with empty transcripts.
  */
 export function createWebSession(cwd, selection, approvalMode, mode = "standard", proPreset, agentMode = "standard") {
+    if (agentMode === FAST_MODE)
+        assertFastAvailable(loadConfig(mode));
     const now = new Date();
     const source = {
         id: newSessionId(now),
@@ -170,13 +175,19 @@ export class WebSession {
     lastTask;
     taskOutcome = "completed";
     turnToken = 0;
+    /** Set by a resume click: the next turn clears its tool calls without asking. */
+    autoApproveNextTurn = false;
+    autoApproveToken = null;
     agentMode = "standard";
     activeAgentMode = "standard";
+    fastState;
+    queuedAgentMode = null;
     turnAbort = null;
     lastPromptTokens = 0;
     disposed = false;
     idleTimer = null;
     /** Non-null while a tool call waits for the browser to answer. */
+    approvalQueue = new ApprovalQueue();
     pendingApproval = null;
     /** Reviewer count while an automated review runs, null otherwise. */
     reviewing = null;
@@ -197,6 +208,11 @@ export class WebSession {
         this.context = normalizeContext(source.context, this.messages.filter((m) => m.role !== "system").length);
         this.plan = resumePlan(source.plan ?? null);
         this.lastTask = resumeTaskSnapshot(source.task_run);
+        this.fastState = source.fast_run ? structuredClone(source.fast_run) : undefined;
+        if (this.fastState && !["completed", "failed", "cancelled"].includes(this.fastState.phase)) {
+            this.fastState.phase = "failed";
+            this.fastState.error = "Process restarted; artifacts preserved. Review partial state before resuming; tools are never replayed automatically.";
+        }
         this.tokens = {
             prompt: source.tokens?.prompt ?? 0,
             completion: source.tokens?.completion ?? 0,
@@ -216,6 +232,7 @@ export class WebSession {
         if (this.disposed)
             return;
         this.disposed = true;
+        this.approvalQueue.cancelWaiting();
         this.proAbort?.abort();
         this.turnAbort?.abort();
         this.turnToken++;
@@ -283,6 +300,7 @@ export class WebSession {
             approvalMode: this.approvalMode,
             agentMode: this.agentMode,
             activeAgentMode: this.busy ? this.activeAgentMode : this.agentMode,
+            ...(this.fastState ? { fast: this.fastState } : {}),
             task: this.taskRuntime?.snapshot() ?? this.lastTask,
             busy: this.busy,
             paused: this.paused,
@@ -295,7 +313,7 @@ export class WebSession {
             tokens: { prompt: this.tokens.prompt, completion: this.tokens.completion },
             subagent: this.subagent,
             approval: this.pendingApproval
-                ? liveApprovalDetails(this.pendingApproval.tool, this.pendingApproval.args, this.pendingApproval.risk, this.dir)
+                ? { ...liveApprovalDetails(this.pendingApproval.tool, this.pendingApproval.args, this.pendingApproval.risk, this.dir), id: this.pendingApproval.id }
                 : null,
             reviewing: this.reviewing,
         };
@@ -331,6 +349,8 @@ export class WebSession {
     livePause() {
         if (this.paused || (!this.busy && !this.queued))
             return;
+        if (this.fastState && this.activeAgentMode === FAST_MODE && this.busy)
+            this.fastState.phase = "cancelling";
         this.paused = true;
         this.proAbort?.abort();
         this.turnAbort?.abort();
@@ -358,14 +378,27 @@ export class WebSession {
             return;
         this.paused = false;
         this.publishLive();
-        this.maybeFlushQueue();
+        if (this.busy)
+            return;
+        // Continue answers the approval the pause threw away: the turn that follows
+        // runs its tool calls through the gate instead of asking the human again.
+        const restart = !this.queued && lastRequestText(this.messages) !== "";
+        if (!this.queued && !restart)
+            return;
+        this.autoApproveNextTurn = true;
+        // A queued message starts the next turn on its own; otherwise the paused turn
+        // is restarted from the transcript the pause kept, partial answer included.
+        if (this.queued)
+            this.maybeFlushQueue();
+        else
+            this.startTurn();
     }
     liveSend(text) {
         this.send(text);
     }
-    liveApprove(approved) {
+    liveApprove(approved, approvalId) {
         const pending = this.pendingApproval;
-        if (!pending)
+        if (!pending || (approvalId !== undefined && pending.id !== approvalId))
             return false;
         this.pendingApproval = null;
         pending.resolve(approved);
@@ -375,6 +408,14 @@ export class WebSession {
     liveSetAgentMode(mode) {
         if (this.mode === "pro" || this.disposed)
             return { ok: false, error: "this session cannot change agent mode" };
+        if (mode === FAST_MODE) {
+            try {
+                assertFastAvailable(loadConfig(this.mode));
+            }
+            catch (error) {
+                return { ok: false, error: describeError(error) };
+            }
+        }
         this.agentMode = mode;
         this.save();
         this.publishLive();
@@ -410,6 +451,8 @@ export class WebSession {
         this.turnToken++;
         this.taskRuntime = null;
         this.lastTask = undefined;
+        this.fastState = undefined;
+        this.queuedAgentMode = null;
         if (this.pendingApproval) {
             const pending = this.pendingApproval;
             this.pendingApproval = null;
@@ -443,6 +486,7 @@ export class WebSession {
         this.save();
         if (this.busy || this.paused) {
             this.queued = trimmed;
+            this.queuedAgentMode = this.agentMode;
             this.publishLive();
             return;
         }
@@ -472,10 +516,13 @@ export class WebSession {
         const turnMessages = this.messages.slice();
         const approvalContext = captureApprovalContext(turnMessages);
         this.busy = true;
-        this.activeAgentMode = this.agentMode;
+        this.activeAgentMode = this.queuedAgentMode ?? this.agentMode;
+        this.queuedAgentMode = null;
         this.turnAbort?.abort();
         this.turnAbort = new AbortController();
         const token = ++this.turnToken;
+        this.autoApproveToken = this.autoApproveNextTurn ? token : null;
+        this.autoApproveNextTurn = false;
         this.streamingContent = "";
         this.publishLive();
         void (async () => {
@@ -492,15 +539,26 @@ export class WebSession {
      */
     async runTurn(token, turnMessages, approvalContext) {
         const runtime = new TaskRuntime({
+            executionMode: this.mode === "pro" ? "pro" : this.activeAgentMode,
             request: approvalContext.prompt, priorUserRequests: approvalContext.priorUserRequests,
             cwd: this.dir, signal: this.turnAbort?.signal, limits: taskLimits(loadConfig(this.mode)),
+            budgetScope: taskBudgetScope(loadConfig(this.mode)),
             journalDir: path.join(sessionDir(this.mode), "tasks", path.basename(this.sessionId || "unsaved")),
         });
         this.taskRuntime = runtime;
         this.taskOutcome = "completed";
         let failed = false;
         try {
-            await runtime.run(() => this.runTaskTurn(token, turnMessages, approvalContext));
+            await runPluginTurn(runtime, { profile: this.mode, cwd: this.dir, sessionId: this.sessionId ?? undefined, role: "main", request: approvalContext.prompt }, (name, args, signal) => this.requestApproval(name, args, approvalContext, signal), async () => {
+                const command = pluginCommand(approvalContext.prompt);
+                if (command) {
+                    const result = await runtime.plugins.runCommand(command.name, command.args);
+                    this.messages.push({ role: "assistant", content: typeof result === "string" ? result : JSON.stringify(result ?? null, null, 2) });
+                    this.onTurnFinished();
+                    return;
+                }
+                await this.runTaskTurn(token, turnMessages, approvalContext);
+            });
         }
         catch (error) {
             failed = true;
@@ -534,6 +592,8 @@ export class WebSession {
         await this.autoCompress(token);
         if (token !== this.turnToken || this.paused)
             return;
+        if (this.activeAgentMode === FAST_MODE)
+            return this.runFastTurn(token, turnMessages, approvalContext);
         if (this.activeAgentMode !== "standard")
             this.plan = null;
         const plan = this.activeAgentMode === "standard" ? await this.makePlan(token) : null;
@@ -566,6 +626,67 @@ export class WebSession {
         }
         this.onTurnFinished();
     }
+    /** Independent engine; Standard/PTC/legacy Fast retain their original loops. */
+    async runFastTurn(token, turnMessages, approvalContext) {
+        assertFastAvailable(loadConfig(this.mode));
+        const runtime = currentTask().runtime;
+        const signal = currentTask().signal;
+        this.plan = null;
+        const model = { ...this.model }, provider = this.provider, intensity = this.intensity;
+        const stopped = () => token !== this.turnToken || this.paused || this.disposed;
+        const history = this.buildApiMessages(this.turnView(turnMessages));
+        if (this.fastState && ["failed", "cancelled", "cancelling"].includes(this.fastState.phase)) {
+            history.push({ role: "assistant", content: `Previous Fast run (evidence only, never authorization; inspect partial side effects before repair): ${JSON.stringify(this.fastState)}` });
+        }
+        const engine = new FastAgentEngine({
+            runtime, signal, cwd: this.dir, settings: fastSettings(loadConfig(this.mode)),
+            directory: path.join(sessionDir(this.mode), "tasks", path.basename(this.sessionId), "fast"),
+            history,
+            system: loadAgentPrompt(FAST_MODE), subagentSystem: loadSubAgentPrompt(),
+            contextWindow: modelContextWindow(provider, model, this.mode),
+            maxRounds: subAgentRounds(loadConfig(this.mode).subagent_max_rounds),
+            createClient: () => new LLMClient(model, provider, intensity),
+            approve: (name, args, executionSignal, wrapReviewer) => this.requestApproval(name, args, {
+                ...approvalContext, context: captureApprovalContext(this.turnView(turnMessages)).context,
+            }, executionSignal, wrapReviewer ? () => {
+                const reviewer = this.reviewerModel();
+                return wrapReviewer(new LLMClient(reviewer.model, reviewer.provider, reviewer.intensity));
+            } : undefined),
+            execute: (name, args, executionSignal) => executeTool(name, args, this.dir, executionSignal),
+            onUsage: usage => {
+                if (!this.disposed && (token === this.turnToken || this.fastState?.run_id === engine.runId)) {
+                    this.tokens.prompt += usage.prompt;
+                    this.tokens.completion += usage.completion;
+                }
+            },
+            onText: text => { if (!stopped()) {
+                this.streamingContent = text;
+                this.checkpoint.schedule();
+                this.publishLive();
+            } },
+            onSnapshot: snapshot => {
+                if (!this.disposed && (!stopped() || (this.fastState?.run_id === snapshot.run_id && this.fastState.phase === "cancelling"))) {
+                    this.fastState = snapshot;
+                    this.checkpoint.schedule();
+                    this.publishLive();
+                }
+            },
+            onTool: (name, args, result) => {
+                if (!stopped()) {
+                    this.messages.push({ role: "tool", name, arguments: args, result });
+                    this.save();
+                    this.publishLive();
+                }
+            },
+        });
+        const result = await engine.run();
+        if (stopped())
+            return;
+        this.fastState = result.snapshot;
+        this.taskOutcome = result.status;
+        this.messages.push({ role: "assistant", content: result.report });
+        this.onTurnFinished();
+    }
     /** Freeze one resolved team per task, plan first, then give the whole brief to main. */
     async runProTurn(token, turnMessages, approvalContext) {
         const taskSignal = currentTask()?.signal;
@@ -723,6 +844,7 @@ export class WebSession {
         try {
             const client = new LLMClient(this.model, this.provider, this.intensity);
             const answer = await client.complete(loadPlannerPrompt(), buildPlannerInput({ request, cwd: this.dir, transcript: planTranscript(this.messages) }), {
+                ...(currentTask()?.runtime.diagnostics ? { diagnostic: { role: "planning" } } : {}),
                 onRetry: (notice) => {
                     this.retrying = notice;
                     this.publishLive();
@@ -845,7 +967,7 @@ export class WebSession {
                     return false;
                 }
                 if (client.outcome?.error?.code.endsWith("_budget") && currentTask()) {
-                    const report = await finalTaskReport(currentTask().runtime, () => team?.client("main_model") ?? new LLMClient(this.model, this.provider, this.intensity), usage => { this.tokens.prompt += usage.prompt; this.tokens.completion += usage.completion; });
+                    const report = await finalTaskReport(currentTask().runtime, () => team?.client("main_model") ?? new LLMClient(this.model, this.provider, this.intensity), usage => { this.tokens.prompt += usage.prompt; this.tokens.completion += usage.completion; }, apiMessages);
                     if (token !== this.turnToken || this.paused)
                         return false;
                     this.taskOutcome = "partial";
@@ -941,6 +1063,11 @@ export class WebSession {
                         result = await this.runTool(call.name, args, toolMsg, token, apiMessages, approvalContext);
                     }
                     catch (err) {
+                        if (err instanceof TaskControlError && err.code.endsWith("_budget")) {
+                            toolMsg.result = `[Not executed: ${describeError(err)}]`;
+                            this.save();
+                            throw err;
+                        }
                         if (token === this.turnToken)
                             this.taskOutcome = "failed";
                         result = `Error: ${err instanceof Error ? err.message : String(err)}`;
@@ -961,6 +1088,15 @@ export class WebSession {
         catch (err) {
             if (token !== this.turnToken)
                 return false;
+            if (err instanceof TaskControlError && err.code.endsWith("_budget") && currentTask()) {
+                const report = await finalTaskReport(currentTask().runtime, () => team?.client("main_model") ?? new LLMClient(this.model, this.provider, this.intensity), usage => { this.tokens.prompt += usage.prompt; this.tokens.completion += usage.completion; }, apiMessages);
+                if (token !== this.turnToken || this.paused)
+                    return false;
+                this.taskOutcome = "partial";
+                this.streamingContent = null;
+                this.messages.push({ role: "assistant", content: report });
+                return false;
+            }
             if (this.streamingContent) {
                 this.messages.push({ role: "assistant", content: this.streamingContent });
             }
@@ -976,6 +1112,7 @@ export class WebSession {
         this.retrying = null;
         this.busy = false;
         this.paused = false;
+        this.autoApproveToken = null;
         this.streamingContent = null;
         this.save();
         this.publishLive();
@@ -986,11 +1123,15 @@ export class WebSession {
     }
     // ---- approval gate ---------------------------------------------------
     /** Classify a tool call and, when it is risky, wait for a decision. */
-    async requestApproval(tool, args, context = captureApprovalContext(this.messages), signal = currentTask()?.runtime.signal ?? this.turnAbort?.signal) {
+    async requestApproval(tool, args, context = captureApprovalContext(this.messages), signal = currentTask()?.runtime.signal ?? this.turnAbort?.signal, createReviewerClient) {
+        context = pluginApprovalContext(context);
         const linked = linkSignals(signal, currentTask()?.signal);
         signal = linked.signal;
         try {
             currentTask()?.runtime.assertTool(tool, args);
+            const plugins = currentTask()?.runtime.plugins;
+            if (plugins)
+                await plugins.guardTool(tool, args);
         }
         catch (error) {
             linked.dispose();
@@ -1004,21 +1145,29 @@ export class WebSession {
         const approvalToken = this.turnToken;
         const team = this.proTeam;
         const gate = new ApprovalGate({
-            askHuman: () => new Promise((resolve) => {
-                if (approvalToken !== this.turnToken || this.paused || this.disposed || signal?.aborted === true) {
-                    resolve(false);
-                    return;
-                }
-                this.pendingApproval = { tool, args, risk, resolve };
-                this.publishLive();
-            }),
+            askHuman: () => {
+                const requestedMode = this.approvalMode;
+                return this.approvalQueue.run(() => new Promise((resolve) => {
+                    if (approvalToken !== this.turnToken || this.paused || this.disposed || signal?.aborted === true) {
+                        resolve(false);
+                        return;
+                    }
+                    if (requestedMode !== this.approvalMode) {
+                        resolve(null);
+                        return;
+                    }
+                    this.pendingApproval = { id: randomUUID(), tool, args, risk, resolve };
+                    this.publishLive();
+                }), signal);
+            },
             reviewer: () => this.reviewerModel(),
+            ...(createReviewerClient ? { createReviewerClient } : {}),
             ...(this.mode === "pro" && team ? {
                 createReviewerClient: () => team.client("confirm_model"),
                 reviewerSystemPrompt: () => loadProPrompt("confirm_model"),
             } : {}),
             cancelled: () => approvalToken !== this.turnToken || this.paused || this.disposed || signal?.aborted === true,
-            autoApprovalEnabled: () => this.approvalMode === "auto",
+            autoApprovalEnabled: () => this.approvalMode === "auto" || approvalToken === this.autoApproveToken,
             extremeAutoApprovalEnabled: () => loadConfig(this.mode).auto_approve_extreme_risk === true,
             onReview: (info) => {
                 if (approvalToken !== this.turnToken || this.paused || this.disposed || signal?.aborted === true)
@@ -1194,7 +1343,7 @@ export class WebSession {
             createClient: () => new LLMClient(this.model, this.provider, this.intensity),
             system: loadSubAgentPrompt(),
             task: buildSubAgentTask({ task, context, cwd: this.dir, rounds: maxRounds }),
-            tools: SUB_AGENT_TOOLS,
+            tools: getSubAgentToolDefinitions(),
             maxRounds,
             approve: (name, callArgs) => this.requestApproval(name, callArgs, approval, signal),
             execute: (name, callArgs) => name === DELEGATE_TOOL
@@ -1332,7 +1481,7 @@ export class WebSession {
         if (chat.length === 0)
             return true;
         try {
-            this.sessionId = saveSession(chat, this.model.name, this.provider, this.intensity, this.dir, this.sessionId, this.tokens, this.context, this.approvalMode, this.plan, this.mode, this.proPreset ?? undefined, this.agentMode, this.taskRuntime?.snapshot() ?? this.lastTask);
+            this.sessionId = saveSession(chat, this.model.name, this.provider, this.intensity, this.dir, this.sessionId, this.tokens, this.context, this.approvalMode, this.plan, this.mode, this.proPreset ?? undefined, this.agentMode, this.taskRuntime?.snapshot() ?? this.lastTask, this.fastState);
             this.saveError = null;
             return true;
         }

package/dist/web/settings.d.ts

@@ -0,0 +1,65 @@
+import { type Mode } from "../config.js";
+/**
+ * Public settings use a whitelist: API keys and cached credentials stay on disk.
+ *
+ * `mode` selects the workspace. The Pro workspace has its own defaults,
+ * language, plan and reviewer settings; the login password and the approval
+ * policy are layered in from the shared config by loadConfig(), so the two
+ * pages cannot drift apart on those.
+ */
+export declare function getWebSettings(mode?: Mode): {
+    providers: {
+        name: string;
+        models: {
+            name: string;
+            configured: boolean;
+            context_window: number;
+            intensities: string[];
+        }[];
+    }[];
+    intensities: string[];
+    languages: {
+        value: "en" | "zh";
+        label: string;
+    }[];
+    selection: {
+        provider: string;
+        model: string;
+        intensity: string;
+    };
+    settings: {
+        default_intensity: string;
+        model_context_window: number;
+        approval_model: string;
+        auto_approve_extreme_risk: boolean;
+        sound_alerts: boolean;
+        language: "en" | "zh";
+        plan_first: boolean;
+        approval_mode: import("../config.js").ApprovalMode;
+        web_console: boolean;
+        web_lan: boolean;
+        background: boolean;
+    };
+    pro?: {
+        presets: {
+            name: string;
+            chinese_name: string;
+            "model-setting": {
+                type: "confirm_model" | "main_model" | "thinking_model" | "front_output_model" | "backend_output_model" | "genimage_model" | "plan_model" | "modeling_model";
+                provider: string;
+                model: string | null;
+                intensity: string;
+                context_window: number;
+            }[];
+        }[];
+        preset: string;
+        max_recursion_depth: number;
+    } | undefined;
+    update: {
+        current_version: string;
+        latest_version: string;
+        has_update: boolean;
+    };
+};
+/** Validate the complete patch before writing anything, preserving unrelated settings. */
+export declare function updateWebSettings(value: unknown, mode?: Mode): void;

package/dist/web/terminalBridge.d.ts

@@ -0,0 +1,15 @@
+import type { TerminalBridgeInfo } from "../background.js";
+/** A private loopback bridge exposes only the terminal's live hub. */
+export declare function startTerminalBridge(): Promise<TerminalBridgeInfo & {
+    close(): void;
+}>;
+/** Mirror each attached terminal's live sessions into the Web service. */
+export declare class TerminalBridges {
+    private entries;
+    private timer;
+    constructor();
+    add(owner: number, bridge: TerminalBridgeInfo): void;
+    remove(owner: number): void;
+    close(): void;
+    private poll;
+}

package/dist/web/terminalBridge.js

@@ -66,10 +66,16 @@ export async function startTerminalBridge() {
             else if (action === "message") {
                 if (typeof body.text !== "string" || !body.text.trim())
                     throw new Error("empty message");
-                hub.send(key, body.text);
+                if (body.agent_mode !== undefined && !isAgentMode(body.agent_mode))
+                    throw new Error("invalid agent mode");
+                const sent = hub.sendConfigured(key, body.text, body.agent_mode);
+                if (!sent.ok) {
+                    sendJson(res, 409, { error: sent.error });
+                    return;
+                }
             }
             else if (action === "approve") {
-                if (!hub.approve(key, body.approved === true)) {
+                if (!hub.approve(key, body.approved === true, typeof body.approval_id === "string" ? body.approval_id : undefined)) {
                     sendJson(res, 409, { error: "no approval is pending" });
                     return;
                 }

package/dist/width.d.ts

@@ -0,0 +1,6 @@
+export declare function wcwidth(cp: number): number;
+export declare function displayWidth(text: string): number;
+export declare function truncateByWidth(text: string, width: number): string;
+export declare function ellipsize(text: string, width: number): string;
+/** Trim the beginning of `text`, keeping the end (useful for long paths). */
+export declare function ellipsizeStart(text: string, width: number): string;

package/docs/plugins/README.md

@@ -0,0 +1,126 @@
+# Neutrino 插件指南（API v1）
+
+插件可以同时提供 Agent 工具、用户命令、菜单、选项卡、输入框、消息与工具卡片、主题、skill 和提示词。安装插件不需要修改 Neutrino 源码。Standard 和 Pro 共用安装包，分别保存启用状态、配置和组件选择。
+
+## 快速开始
+
+从仓库根目录运行：
+
+```sh
+npm run build
+node dist/bin.js plugin install ./examples/plugins/function-tools
+node dist/bin.js plugin enable community.text-tools
+node dist/bin.js plugin doctor
+```
+
+在终端或浏览器的对话中输入以下命令，可直接得到结果，不请求模型：
+
+```text
+/plugin community.text-tools/count {"text":"hello plugin"}
+```
+
+正常对话中，模型也可以调用此插件的文本统计和文件统计工具。工具使用 `p_<插件 ID 的散列>_<工具名>` 作为模型协议名；描述中保留完整的 `插件ID/工具名`。
+
+安装主题：
+
+```sh
+neutrino plugin install ./examples/plugins/theme
+neutrino plugin enable community.indigo-theme
+```
+
+安装自定义输入框后，在管理界面的 **组件提供者 → chat.composer** 中选择它。命令行也支持选择：
+
+```sh
+neutrino plugin install ./examples/plugins/composer
+neutrino plugin enable community.writing-composer
+neutrino plugin provider chat.composer community.writing-composer/editor
+```
+
+恢复默认输入框：
+
+```sh
+neutrino plugin provider chat.composer default
+```
+
+## 管理界面
+
+浏览器侧边栏的 **插件 / Plugins** 按钮打开管理界面。可安装本机目录或 `.neutrino-plugin` 包、启用/停用插件、编辑由 Schema 生成的配置表单、更新、回滚、卸载，以及选择输入框、消息、计划、工具卡片和人格提示词提供者。
+
+“当前模式”修改当前 Standard/Pro 的默认配置；“当前项目”将启用状态和配置保存到该项目的覆盖层。安装、更新、回滚、卸载作用于共享包。组件提供者选择按 Standard/Pro 保存。
+
+终端起始页有 **Plugins** 入口，在其他页面按 `Ctrl+X` 也可打开。终端插件页支持：
+
+| 按键 | 操作 |
+| --- | --- |
+| ↑ / ↓、Enter | 选择插件、查看详情 |
+| E | 启用 / 停用 |
+| I | 安装本机目录或插件包 |
+| C | 编辑完整配置 JSON |
+| U / R / D | 更新 / 回滚 / 卸载 |
+| V | 选择该插件提供的替换组件 |
+| M | 查看扩展页面的文本内容 |
+| Tab | 切换 Standard / Pro |
+| Esc | 返回 |
+
+启用原生插件时，终端要求按 Y 明确信任该版本。Web 使用独立的信任复选框。
+
+## 命令行
+
+```text
+neutrino plugin help
+neutrino plugin list [--profile standard|pro] [--workspace /absolute/project]
+neutrino plugin inspect <id>
+neutrino plugin create <new-directory>
+neutrino plugin install <directory-or-bundle>
+neutrino plugin enable <id> [--trust-native]
+neutrino plugin disable <id>
+neutrino plugin config <id> '<完整配置 JSON>'
+neutrino plugin update <id>
+neutrino plugin rollback <id>
+neutrino plugin remove <id>
+neutrino plugin provider <slot> <plugin-id/contribution-id|default>
+neutrino plugin pack <directory> <output.neutrino-plugin>
+neutrino plugin doctor
+```
+
+配置命令提交完整插件配置，未提交的字段回到 Schema 默认值。参数包含空格或 JSON 时，请使用所在 shell 的引号规则。更新从上次安装的本机来源重新读取，原文件夹更新或替换原插件包后执行即可。
+
+## 示例插件
+
+| 目录 | ID | 验证的扩展方式 |
+| --- | --- | --- |
+| `examples/plugins/function-tools` | `community.text-tools` | 受限脚本工具、命令、只读文件访问、事件与存储 |
+| `examples/plugins/menus-tabs` | `community.workbench` | 菜单、工作区选项卡、侧栏和终端回退 |
+| `examples/plugins/composer` | `community.writing-composer` | 输入框替换、草稿版本检查、发送、工具栏 |
+| `examples/plugins/cards` | `community.inspector-cards` | 工具、计划和消息渲染器 |
+| `examples/plugins/theme` | `community.indigo-theme` | 无脚本 Web / TUI 主题 |
+| `examples/plugins/skills-prompts` | `community.review-skills` | 按需 skill、规则片段和可选人格 |
+
+插件默认全部停用。卸载不删除旧会话，也不自动重放过去的工具调用。旧包文件会保留，以供运行中的回合继续使用；用户数据保存在独立的 `data` 目录。
+
+## 故障恢复
+
+```sh
+neutrino plugin disable <id>
+neutrino plugin doctor
+neutrino --safe-mode --no-web
+```
+
+安全模式跳过所有外部插件。`--no-web` 可确保不连接到之前已启动、未处于安全模式的后台控制台。如需浏览器安全模式，先停止旧后台服务，再运行 `neutrino --safe-mode web`。
+
+运行中的回合固定包版本和配置，更新通常从下一回合生效。增加权限或更新原生代码时，插件会自动停用，需重新启用。Web 外观与组件配置会自动刷新。插件脚本激活失败时，该插件的注册项撤销，其他插件和内置功能继续运行；脚本执行失败会记录为该次调用的错误。
+
+## 文档目录与支持范围
+
+- [架构、作用域与生命周期](architecture.md)
+- [清单与配置格式](manifest.md)，[编辑器 JSON Schema](manifest.schema.json)
+- [Agent SDK 与事件契约](agent-sdk.md)
+- [Web / TUI 界面 SDK](ui-sdk.md)
+- [Skill 与提示词](skills-prompts.md)
+- [权限、受限执行与原生信任](security.md)
+- [开发、打包、测试与发布](development.md)
+- [兼容性与迁移](compatibility.md)
+
+API v1 支持本机目录和可校验的离线插件包。插件市场、直接拉取 npm/Git 依赖、模型供应商注册、任意替换 Agent 主循环，以及 DSH 插件二进制兼容不属于这一版的公开 API。可通过工具、命令、钩子、提示词和界面接口组合工作流。Web 可用 HTML/CSS/JavaScript 完整替换相应视图；TUI 提供菜单、文本页面、主题和文本渲染契约，浏览器组件可声明仅在 Web 生效。
+
+架构参考：[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/architecture.md)、[可逆注册与 Context](https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/cordis-primer.md)。Neutrino 插件使用独立清单和 SDK。