@autopilot-agent/cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+<!-- 本文件用于 npm CLI 用户了解安装、配置和使用方式。 -->
+# @autopilot-agent/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Autopilot Agent 是一个在终端中使用的 AI 编程助手，可以运行在任何支持开启终端操作的IDE、ADE中；Autopilot 可以帮助你分析项目、修改代码、执行命令和管理会话。你可以通过权限设置和操作审批控制它对项目的访问。
+
+安装后使用 `ap` 或 `autopilot` 启动，两者功能相同。
+
+## 可以做什么
+
+- **理解项目**：阅读文件、按文件名或内容搜索代码，梳理项目结构、解释实现、定位问题。输入 `@src/index.ts` 这样的相对路径，可以把指定文件带入当前对话。
+- **编写和修改代码**：根据需求创建文件、修改已有代码，帮助修复 Bug、补充测试和整理文档；交互界面会展示文件修改信息。
+- **执行开发命令**：运行测试、构建和其他命令，根据输出继续排查；耗时命令可以作为后台任务运行，随时查看输出或请求停止。
+- **跟踪任务进度**：将复杂需求拆成待办事项，在执行过程中更新完成状态；任务运行时也可以排队提交下一条需求。
+- **继续已有对话**：保存并管理项目会话，在已有会话中继续提问；中断后可恢复的任务可以通过 `ap resume` 继续。
+- **管理上下文**：查看当前上下文用量，手动压缩对话；具备有效上下文预算时，也会按阈值自动压缩，帮助继续较长的任务。
+- **控制操作权限**：确认项目是否可信，选择权限模式，并审批需要确认的操作；通过 `/undo` 预览并撤销当前会话最近一轮可撤销的文件修改。
+- **扩展工具和工作流程**：加载已安装的 Skills，通过 `/skill` 选择使用；配置并授权 MCP 服务后，可以调用其提供的工具。
+- **查资料和分析图片**：配置搜索服务后可以联网搜索、读取网页；配置可用的视觉模型后，可以分析项目中的图片，例如界面截图。
+
+你可以直接用自然语言提出需求，例如：
+
+```text
+分析这个项目的入口和主要模块，先不要修改文件。
+查找登录失败的原因，修复后运行相关测试。
+根据这张UI设计图片，还原设计稿。
+```
+
+## 常用交互命令
+
+启动 `ap` 后，输入 `/` 可以查看命令建议。
+
+| 命令 | 用途 |
+|---|---|
+| `/model`、`/effort` | 选择后续任务使用的模型和思考强度 |
+| `/skill` | 查看并选择已安装的 Skills |
+| `/permissions` | 查看或切换当前会话的权限模式 |
+| `/context`、`/context all` | 查看上下文用量，或展开详细信息 |
+| `/compact` | 手动压缩当前上下文 |
+| `/jobs` | 查看后台任务，也可查看输出或请求停止 |
+| `/queue <需求>` | 将下一条需求加入队列 |
+| `/undo` | 预览最近一轮可撤销的文件修改，再确认是否撤销 |
+| `/cancel`、`/exit` | 取消当前任务，或退出 CLI |
+
+## 安装
+
+请先安装 **Node.js >=20.11.0 且 <22** 和 npm，再运行以下命令。安装时需要联网。
+
+```bash
+npm install -g autopilot-agent
+ap --help
+```
+
+只需安装 `autopilot-agent`，所需依赖会自动安装。
+
+## 配置 settings.json
+
+首次使用前，需要填写模型服务地址、API 密钥和模型名称。请在以下位置创建或编辑 `settings.json`：
+
+| 系统 | 配置文件位置 |
+|---|---|
+| Windows | `%USERPROFILE%\.autopilot\settings.json` |
+| macOS | `~/.autopilot/settings.json` |
+
+ `.autopilot` 目录会随 Autopilot Cli首次启动自动创建，如果 `.autopilot` 目录不存在，可先自行创建。配置文件使用标准 JSON，不支持注释或末尾多余的逗号。按下面的示例填写即可，不添加 `schemaVersion` 字段。
+
+### 使用 Anthropic 或兼容服务
+
+如果服务支持 Anthropic Messages 协议，使用以下配置，将 `YOUR_API_KEY` 和 `YOUR_MODEL_ID` 替换为你的密钥和模型名称。使用兼容服务时，也需要替换服务地址。
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
+    "ANTHROPIC_API_KEY": "YOUR_API_KEY"
+  },
+  "model": "YOUR_MODEL_ID"
+}
+```
+
+如果服务要求使用 `ANTHROPIC_AUTH_TOKEN`，请用它替换 `ANTHROPIC_API_KEY`，不要同时填写两者。服务地址不要追加 `/v1/messages`，也不要包含用户名、密码、查询参数或 `#` 后的内容。
+
+### 使用 OpenAI Chat Completions 兼容服务
+
+如果服务支持 OpenAI Chat Completions 协议，使用下面的配置。替换密钥、`baseUrl` 和两处 `YOUR_MODEL_ID`；其余字段可以保留示例写法。
+
+```json
+{
+  "env": { "USER_SETTINGS_CUSTOM_API_KEY": "YOUR_API_KEY" },
+  "providerRoutes": {
+    "custom": {
+      "id": "custom",
+      "apiProtocol": "openai-chat-completions",
+      "baseUrl": "https://api.example.com/v1",
+      "credentialRef": { "provider": "custom", "key": "USER_SETTINGS_CUSTOM_API_KEY" },
+      "models": [{ "id": "YOUR_MODEL_ID" }]
+    }
+  },
+  "model": "custom/YOUR_MODEL_ID"
+}
+```
+
+不要同时设置 `env.ANTHROPIC_MODEL`，以免覆盖这里选择的模型。
+
+需要配置多个服务时，可以在 `providerRoutes` 中增加其他条目。每个条目的名称、`id` 和 `credentialRef.provider` 应一致；`credentialRef.key` 对应 `env` 中的密钥名称。`model` 使用 `服务名称/模型名称` 的形式，模型必须列在对应服务的 `models` 中。协议只支持 `anthropic-messages` 和 `openai-chat-completions`。
+
+### 常用可选参数
+
+| 字段 | 用途与写法 |
+|---|---|
+| `model` | 使用的模型名称，或上面示例中的 `服务名称/模型名称`；建议填写服务商提供的完整模型名称 |
+| `availableModels` | 默认连接允许使用的模型列表，例如 `["MODEL_A", "MODEL_B"]`；不能为空、不能重复，当前模型也需要在列表中 |
+| `effortLevel` | 思考强度，可选 `"low"`、`"medium"`、`"high"`，具体效果取决于模型支持情况 |
+| `alwaysThinkingEnabled` | 是否启用思考，填写 `true` 或 `false`，不要加引号；需要模型支持 |
+| `maxOutputTokens` | 单次输出的 token 上限，填写 1–1,000,000 的整数；不是上下文大小 |
+| `env.API_TIMEOUT_MS` | 默认模型连接的请求超时，单位毫秒，填写 1,000–600,000 的整数字符串，例如 `"60000"` |
+| `visionModel` | 图片分析使用的模型，填写已配置的 Chat Completions 服务中的 `服务名称/模型名称`；`false` 关闭，省略时使用主模型 |
+| `webSearch` | `false` 关闭模型联网搜索；启用时需另行配置搜索服务 |
+
+`env` 中的值都需要写成字符串。填写模型名称和密钥时，避免带入首尾空格或换行。建议通过顶层 `model` 和 `effortLevel` 设置模型与思考强度；`env.ANTHROPIC_MODEL` 和 `env.CLAUDE_CODE_EFFORT_LEVEL` 会覆盖对应设置。
+
+服务地址、密钥、模型列表等连接设置请放在上面的个人配置文件中，不要把密钥提交到项目或版本控制。项目也可以提供 `.autopilot/settings.json` 和 `.autopilot/settings.local.json`，在你信任该项目后应用允许的设置；项目设置不能替换个人配置中的连接信息。
+
+### 修改配置
+
+直接编辑个人 `settings.json` 可以修改完整配置。简单配置也可以通过以下命令修改模型、思考强度和可用模型列表：
+
+```bash
+ap config set model YOUR_MODEL_ID --scope user
+ap config set effortLevel high --scope user
+ap config set availableModels MODEL_A,MODEL_B --scope user
+```
+
+命令中的模型列表用逗号分隔，配置文件中则使用 JSON 数组。如果文件中配置了自定义服务的 `credentialRef`、`maxOutputTokens` 等字段，当前版本可能拒绝上述修改命令，请直接编辑文件。修改后用 `ap doctor` 检查配置。
+
+## 开始使用
+
+进入要处理的项目目录后运行：
+
+```bash
+ap
+```
+
+首次打开项目时，按提示确认是否信任该项目。确认后，可以检查配置和模型连接：
+
+```bash
+ap doctor
+ap doctor --connectivity
+```
+
+`ap doctor` 检查本地配置，`--connectivity` 还会联网检查模型服务。未信任项目时，部分检查会跳过。
+
+`ap` 会进入交互模式，你可以直接输入需求。也可以提交一次任务：
+
+```bash
+ap chat "分析当前项目结构，不修改文件"
+```
+
+常用管理命令：
+
+```bash
+ap session list
+ap trust status
+ap sandbox status
+```
+
+查看各命令的具体参数与限制：`ap --help`。更新和卸载：
+
+```bash
+npm install -g autopilot-agent@latest
+npm uninstall -g autopilot-agent
+```
+
+卸载后，个人配置和会话数据仍会保留。
+
+## 当前限制
+
+- 当前提供终端使用方式，暂不包含图形界面、内置浏览器预览、自动长期记忆或私有知识库搜索。
+- 沙箱功能需要额外的平台支持，可通过 `ap doctor` 和 `ap sandbox status` 查看状态。MCP 工具默认在本机运行，不提供操作系统级隔离。
+- Windows 后台任务的子进程可能无法全部停止；沙箱中的 MCP 工具也可能遇到输入无法转发的问题。需要可靠停止的长任务，建议先在测试项目中验证。
+- macOS 尚未完成完整功能验证，Linux 暂未验证。模型服务的可用性、限额和费用以服务商为准。
+- 当前为早期版本，处理重要项目时，请保留版本控制或备份。

package/dist/activity-animation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * CLI TUI 活动状态与离散动画。
+ *
+ * 状态由安全事件类型归约得到，动画只消费显式状态和共享时钟；稳定文案始终
+ * 可见。活动 glyph 采用 Claude Code 的单字符 ping-pong 形式，不把状态包装成
+ * 调试风格的进度条。
+ */
+import { type ReactNode } from "react";
+import type { CliTurnStatus } from "./types.js";
+import type { TuiAnimationClock } from "./animation-clock.js";
+export type CliActivityPhase = "requesting" | "thinking" | "waiting" | "transition" | "responding" | "stalled" | "terminal";
+export interface CliActivityState {
+    phase: CliActivityPhase;
+    lastProgressAt: number;
+    transitionStartedAt?: number;
+    hasActiveTool: boolean;
+    stallable: boolean;
+}
+export interface CliActivityView {
+    phase: CliActivityPhase;
+    label: string;
+    frame: string;
+}
+interface CliActivityEventLike {
+    type: string;
+}
+export declare const CLI_ACTIVITY_STALLED_AFTER_MS = 20000;
+export declare const CLI_ACTIVITY_TRANSITION_MS = 2000;
+/** 与 CC SpinnerGlyph 一致，glyph 每 120ms 前进一格；共享时钟仍可用 50ms tick。 */
+export declare const CLI_ACTIVITY_SPINNER_FRAME_MS = 120;
+/** 创建一个等待 Provider 首个事件的初始活动状态。 */
+export declare function createInitialCliActivityState(now: number): CliActivityState;
+/** 按安全事件类型归约活动状态，不读取事件文案或模型原始输出。 */
+export declare function reduceCliActivityState(previous: CliActivityState, event: CliActivityEventLike, now: number): CliActivityState;
+/** 把投影终态映射为不会继续驱动动画的活动状态。 */
+export declare function settleCliActivityState(previous: CliActivityState, status: CliTurnStatus, now: number): CliActivityState;
+/** 返回指定活动阶段对应的单 glyph 帧；外层 Box 负责固定占位宽度。 */
+export declare function getCliActivityFrame(phase: CliActivityPhase, now: number): string;
+/** 根据当前时间解析过场、stalled 和审批等待，形成最终可见活动状态。 */
+export declare function resolveCliActivityView(input: {
+    activity: CliActivityState;
+    status: CliTurnStatus;
+    now: number;
+    waitingForApproval?: boolean;
+}): CliActivityView | undefined;
+/** 渲染稳定活动文案和可选的固定宽度离散帧。 */
+export declare function TuiActivityLine(props: {
+    activity: CliActivityState;
+    status: CliTurnStatus;
+    waitingForApproval: boolean;
+    useColor: boolean;
+    screenReader: boolean;
+    reducedMotion: boolean;
+    animationActive: boolean;
+    clock: TuiAnimationClock;
+}): ReactNode;
+export {};

package/dist/activity-animation.js

@@ -0,0 +1,145 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * CLI TUI 活动状态与离散动画。
+ *
+ * 状态由安全事件类型归约得到，动画只消费显式状态和共享时钟；稳定文案始终
+ * 可见。活动 glyph 采用 Claude Code 的单字符 ping-pong 形式，不把状态包装成
+ * 调试风格的进度条。
+ */
+import { useEffect, useState } from "react";
+import { Box, Text } from "ink";
+export const CLI_ACTIVITY_STALLED_AFTER_MS = 20_000;
+export const CLI_ACTIVITY_TRANSITION_MS = 2_000;
+/** CC v2.1.88 的默认 spinner glyph；首尾重复保证 ping-pong 转向自然。 */
+const CLI_ACTIVITY_SPINNER_FRAMES = ["·", "✢", "*", "✶", "✻", "✽", "✽", "✻", "✶", "*", "✢", "·"];
+/** 与 CC SpinnerGlyph 一致，glyph 每 120ms 前进一格；共享时钟仍可用 50ms tick。 */
+export const CLI_ACTIVITY_SPINNER_FRAME_MS = 120;
+/** 创建一个等待 Provider 首个事件的初始活动状态。 */
+export function createInitialCliActivityState(now) {
+    return {
+        phase: "requesting",
+        lastProgressAt: now,
+        hasActiveTool: false,
+        stallable: true,
+    };
+}
+/** 将活动状态推进到指定稳定阶段，并记录本次可观察进展时间。 */
+function advanceCliActivityState(previous, phase, now, options = {}) {
+    return {
+        ...previous,
+        phase,
+        lastProgressAt: now,
+        hasActiveTool: options.hasActiveTool ?? previous.hasActiveTool,
+        stallable: options.stallable ?? previous.stallable,
+        transitionStartedAt: options.transitionStartedAt,
+    };
+}
+/** 按安全事件类型归约活动状态，不读取事件文案或模型原始输出。 */
+export function reduceCliActivityState(previous, event, now) {
+    switch (event.type) {
+        case "turn_started":
+            return createInitialCliActivityState(now);
+        case "reasoning_summary":
+        case "reasoning_hidden":
+        case "model_recovery":
+        case "context_overflow":
+        case "context_compact_started":
+        case "context_compacted":
+            return advanceCliActivityState(previous, "thinking", now, { hasActiveTool: false, stallable: true });
+        case "tool_started":
+            return advanceCliActivityState(previous, "transition", now, { hasActiveTool: true, stallable: false, transitionStartedAt: now });
+        case "tool_result":
+            return advanceCliActivityState(previous, "transition", now, { hasActiveTool: false, stallable: true, transitionStartedAt: now });
+        case "approval_required":
+            return advanceCliActivityState(previous, "waiting", now, { hasActiveTool: false, stallable: false });
+        case "answer_delta":
+            return advanceCliActivityState(previous, "responding", now, { hasActiveTool: false, stallable: true });
+        case "status":
+            return previous;
+        default:
+            return previous;
+    }
+}
+/** 把投影终态映射为不会继续驱动动画的活动状态。 */
+export function settleCliActivityState(previous, status, now) {
+    if (status === "idle" || status === "running" || status === "waiting_approval")
+        return previous;
+    return advanceCliActivityState(previous, "terminal", now, { hasActiveTool: false, stallable: false });
+}
+/** 返回指定活动阶段对应的单 glyph 帧；外层 Box 负责固定占位宽度。 */
+export function getCliActivityFrame(phase, now) {
+    if (phase === "terminal")
+        return "";
+    return CLI_ACTIVITY_SPINNER_FRAMES[Math.floor(Math.max(0, now) / CLI_ACTIVITY_SPINNER_FRAME_MS) % CLI_ACTIVITY_SPINNER_FRAMES.length] ?? "·";
+}
+function formatCliActivityElapsed(durationMs) {
+    const totalSeconds = Math.max(1, Math.floor(Math.max(0, durationMs) / 1_000));
+    if (totalSeconds < 60)
+        return `${totalSeconds}s`;
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    if (minutes < 60)
+        return `${minutes}m ${String(seconds).padStart(2, "0")}s`;
+    return `${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m ${String(seconds).padStart(2, "0")}s`;
+}
+/** 返回活动阶段的稳定文案，供动画降级和 screen reader 使用。 */
+function getCliActivityLabel(phase, input = {}) {
+    switch (phase) {
+        case "requesting": return "Preparing · waiting for first event";
+        case "thinking": return "Thinking · planning next step";
+        case "waiting": return input.hasActiveTool ? "Waiting · tool result" : "Waiting · provider response";
+        case "transition": return "Running action · starting tool";
+        case "responding": return "Answering · receiving output";
+        case "stalled": return `Still working · no new event for ${formatCliActivityElapsed(input.idleForMs ?? 0)}`;
+        case "terminal": return "Completed";
+    }
+}
+/** 根据当前时间解析过场、stalled 和审批等待，形成最终可见活动状态。 */
+export function resolveCliActivityView(input) {
+    const { activity, status, now } = input;
+    if (status === "idle")
+        return undefined;
+    if (status !== "running" && status !== "waiting_approval")
+        return { phase: "terminal", label: status, frame: "" };
+    if (input.waitingForApproval || status === "waiting_approval") {
+        return { phase: "waiting", label: "Waiting for approval", frame: getCliActivityFrame("waiting", now) };
+    }
+    let phase = activity.phase;
+    if (phase === "transition" && activity.transitionStartedAt !== undefined && now - activity.transitionStartedAt >= CLI_ACTIVITY_TRANSITION_MS) {
+        phase = activity.hasActiveTool ? "waiting" : "thinking";
+    }
+    if (activity.hasActiveTool && phase !== "transition")
+        phase = "waiting";
+    if (activity.stallable && !activity.hasActiveTool && phase !== "waiting" && now - activity.lastProgressAt >= CLI_ACTIVITY_STALLED_AFTER_MS) {
+        phase = "stalled";
+    }
+    return {
+        phase,
+        label: getCliActivityLabel(phase, { idleForMs: Math.max(0, now - activity.lastProgressAt), hasActiveTool: activity.hasActiveTool }),
+        frame: getCliActivityFrame(phase, now),
+    };
+}
+/** 渲染稳定活动文案和可选的固定宽度离散帧。 */
+export function TuiActivityLine(props) {
+    const [clockTime, setClockTime] = useState(props.clock.now());
+    const view = resolveCliActivityView({ activity: props.activity, status: props.status, now: clockTime, waitingForApproval: props.waitingForApproval });
+    const shouldAnimate = props.animationActive && !props.screenReader && !props.reducedMotion && view !== undefined && view.phase !== "terminal";
+    useEffect(function subscribeActivityClock() {
+        props.clock.setActive(shouldAnimate);
+        if (!shouldAnimate) {
+            setClockTime(props.clock.now());
+            return;
+        }
+        setClockTime(props.clock.now());
+        return props.clock.subscribe(function updateActivityClock(time) {
+            setClockTime(time);
+        });
+    }, [props.clock, shouldAnimate]);
+    if (!view)
+        return null;
+    if (view.phase === "terminal")
+        return null;
+    const frame = shouldAnimate ? view.frame : "·";
+    const isStalled = view.phase === "stalled";
+    return (_jsxs(Box, { flexDirection: "row", children: [_jsx(Box, { width: 3, flexShrink: 0, children: _jsx(Text, { bold: isStalled, color: props.useColor ? "ansi256(208)" : undefined, children: frame }) }), _jsx(Text, { bold: isStalled, dimColor: props.useColor && !isStalled, children: view.label })] }));
+}

package/dist/animation-clock.d.ts

@@ -0,0 +1,22 @@
+/**
+ * CLI TUI 共享动画时钟。
+ *
+ * 时钟只负责向订阅者发出当前时间，不持有任何业务状态；终端活动区不可见、
+ * screen reader、reduced-motion 或终态时可以停止订阅，测试也可以注入时间和调度器。
+ */
+export interface TuiAnimationClock {
+    now(): number;
+    subscribe(listener: (time: number) => void): () => void;
+    setActive(active: boolean): void;
+    tick(): void;
+    dispose(): void;
+}
+/** 共享时钟可注入的调度器配置，避免动画单测依赖真实 setInterval。 */
+export interface TuiAnimationClockOptions {
+    now?: () => number;
+    frameMs?: number;
+    schedule?: (listener: () => void, frameMs: number) => unknown;
+    cancel?: (handle: unknown) => void;
+}
+/** 创建可暂停、可注入且只在有订阅者时运行的 TUI 时钟。 */
+export declare function createTuiAnimationClock(options?: TuiAnimationClockOptions): TuiAnimationClock;

package/dist/animation-clock.js

@@ -0,0 +1,76 @@
+/**
+ * CLI TUI 共享动画时钟。
+ *
+ * 时钟只负责向订阅者发出当前时间，不持有任何业务状态；终端活动区不可见、
+ * screen reader、reduced-motion 或终态时可以停止订阅，测试也可以注入时间和调度器。
+ */
+/** 使用 Node 默认定时器启动一枚共享时钟任务。 */
+function scheduleDefaultTimer(listener, frameMs) {
+    return setInterval(listener, frameMs);
+}
+/** 清理由 Node 默认定时器创建的共享时钟任务。 */
+function cancelDefaultTimer(handle) {
+    clearInterval(handle);
+}
+/** 创建可暂停、可注入且只在有订阅者时运行的 TUI 时钟。 */
+export function createTuiAnimationClock(options = {}) {
+    const now = options.now ?? function readCurrentTime() { return Date.now(); };
+    const frameMs = Math.max(16, options.frameMs ?? 50);
+    const schedule = options.schedule ?? scheduleDefaultTimer;
+    const cancel = options.cancel ?? cancelDefaultTimer;
+    const listeners = new Set();
+    let timer;
+    let active = true;
+    let disposed = false;
+    /** 停止当前定时器，确保没有订阅者或时钟暂停时不继续唤醒进程。 */
+    function stopTimer() {
+        if (timer === undefined)
+            return;
+        cancel(timer);
+        timer = undefined;
+    }
+    /** 根据订阅者和 active 状态启动唯一的共享定时器。 */
+    function ensureTimer() {
+        if (disposed || !active || listeners.size === 0 || timer !== undefined)
+            return;
+        timer = schedule(function emitScheduledTick() { clock.tick(); }, frameMs);
+    }
+    const clock = {
+        now,
+        subscribe(listener) {
+            if (disposed)
+                return function ignoreDisposedSubscription() { };
+            listeners.add(listener);
+            ensureTimer();
+            return function unsubscribe() {
+                listeners.delete(listener);
+                if (listeners.size === 0)
+                    stopTimer();
+            };
+        },
+        setActive(nextActive) {
+            if (disposed || active === nextActive)
+                return;
+            active = nextActive;
+            if (!active)
+                stopTimer();
+            else
+                ensureTimer();
+        },
+        tick() {
+            if (disposed || !active)
+                return;
+            const time = now();
+            for (const listener of [...listeners])
+                listener(time);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            stopTimer();
+            listeners.clear();
+        },
+    };
+    return clock;
+}

package/dist/composition-root.d.ts

@@ -0,0 +1,105 @@
+/**
+ * CLI Composition Root。
+ *
+ * 负责选择 Core 默认 Runtime、共享 Node Adapter、canonical workspaceRoot、
+ * trust policy 和显式 stateRoot；不负责命令解析、事件投影或 Runtime 状态机。
+ */
+import { type AgentRuntime, type CapabilityLoader, type CreateRuntimeBootstrapServiceOptions, type RuntimeBootstrapService, type SafeBootstrapConfig, type SandboxCapabilityReport, type WorkspaceTrustEntry, type WorkspaceTrustPolicy } from "@autopilot-agent/core";
+import type { CliRuntimeStatusDefaults, CliSkillSummary } from "./types.js";
+import { type WorkspaceRegistryEntry, type NodeCapabilityLoader, type NodeSettingsLoader } from "@autopilot-agent/adapters";
+import type { AutopilotSettingsScope } from "@autopilot-agent/core";
+/** Doctor 单项结果；只含状态和脱敏摘要，绝不包含路径、凭据或 Provider 正文。 */
+export interface CliDoctorCheck {
+    name: string;
+    status: "PASS" | "WARN" | "FAIL" | "SKIP";
+    detail: string;
+}
+/** CLI Composition Root 的装配选项。 */
+export interface CreateCliCompositionRootOptions {
+    config?: SafeBootstrapConfig;
+    stateRoot?: string;
+    trustRoot?: string;
+    workspaceRoot?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    trustPolicy?: WorkspaceTrustPolicy;
+    capabilityLoader?: CliCapabilityLoader;
+    defaultRunConfig?: CreateRuntimeBootstrapServiceOptions["defaultRunConfig"];
+    /** 已信任 settings Loader 的测试 seam；生产默认创建 Node Loader。 */
+    settingsLoader?: NodeSettingsLoader;
+    /** Doctor 连通性探测的测试 seam；生产默认使用全局 fetch。 */
+    connectivityFetch?: typeof fetch;
+    /** Web Search 请求的 fake HTTP 测试 seam；生产默认使用平台原生 fetch。 */
+    webSearchFetch?: typeof fetch;
+}
+/** CLI 能力加载器：沿用 Node 的开发能力，但禁止 RAG loader 进入 CLI 装配边界。 */
+export type CliCapabilityLoader = CapabilityLoader & Partial<Pick<NodeCapabilityLoader, "probeWebSearchConnectivity">>;
+/** CLI Composition Root 对外暴露的启动边界。 */
+export interface CliCompositionRoot {
+    readonly stateRoot: string;
+    /** 仅由已解析的业务命令调用，保障当前用户配置根存在且安全。 */
+    ensureUserConfigDirectory(): void;
+    /** Trust 成功后创建当前项目的 .autopilot 与临时文件目录，不生成 settings 文件。 */
+    ensureProjectAutopilotDirectory(workspaceRoot: string): void;
+    establishTrust(): Promise<{
+        workspaceRoot: string;
+        trustEntry: WorkspaceTrustEntry;
+    }>;
+    /** Trust 前解析 canonical 工作区并读取信任状态；未信任时返回记录而不抛 WorkspaceTrustError。 */
+    resolveTrust(): Promise<{
+        workspaceRoot: string;
+        trustEntry: WorkspaceTrustEntry;
+    }>;
+    /** 授予精确 canonical 工作区信任并返回持久化后的记录。 */
+    grantTrust(workspaceRoot: string): Promise<WorkspaceTrustEntry>;
+    /** 读取指定工作区的当前信任状态。 */
+    getTrustStatus(workspaceRoot: string): Promise<WorkspaceTrustEntry>;
+    /** 撤销当前 canonical workspace 的 Trust；调用后不得继续创建 Runtime。 */
+    revokeTrust(workspaceRoot: string): Promise<WorkspaceTrustEntry>;
+    /** 读取宿主级工作区索引；不会扫描磁盘或创建状态根。 */
+    listWorkspaceRegistry(): WorkspaceRegistryEntry[];
+    /** 仅注销 Registry 索引条目，不删除任何工作区数据。 */
+    removeWorkspaceRegistry(workspaceId: string): boolean;
+    /** 读取显式 scope 的脱敏 settings。 */
+    showConfig(scope: AutopilotSettingsScope, workspaceRoot: string): Record<string, unknown>;
+    /** 读取显式 scope 下允许公开的单个 settings 值。 */
+    getConfig(scope: AutopilotSettingsScope, key: string, workspaceRoot: string): unknown;
+    /** 写入显式 scope 下允许公开的单个 settings 值。 */
+    setConfig(scope: AutopilotSettingsScope, key: string, value: string, workspaceRoot: string): Record<string, unknown>;
+    /** 执行默认离线或显式受限连通性 Doctor 检查。 */
+    doctor(workspaceRoot: string, connectivity: boolean): Promise<CliDoctorCheck[]>;
+    /** 读取当前平台沙箱能力报告（脱敏）；绑定传入的 canonical workspace。 */
+    sandboxStatus(workspaceRoot: string): Promise<SandboxCapabilityReport>;
+    /** 显式触发沙箱 setup（Windows UAC 安装；macOS 仅返回当前能力报告）。 */
+    sandboxSetup(workspaceRoot: string): Promise<SandboxCapabilityReport>;
+    createRuntime(workspaceRoot: string): Promise<AgentRuntime>;
+    bootstrap(): Promise<AgentRuntime>;
+    getBootstrapService(): RuntimeBootstrapService;
+    /** 只向 Controller 暴露可安全显示的已热更新 settings 默认值。 */
+    getRuntimeStatusDefaults(): CliRuntimeStatusDefaults;
+    /** 返回不含凭据的首次运行配置诊断；undefined 表示可继续启动。 */
+    getStartupConfigurationError(): string | undefined;
+    listSkills(): Promise<CliSkillSummary[]>;
+    resolveSkill(skill: string): Promise<{
+        skillId: string;
+        contentHash: string;
+    }>;
+    /** 返回不含环境变量的 MCP server 审批摘要与执行隔离事实。 */
+    listMcp(workspaceRoot: string): Promise<Array<{
+        serverName: string;
+        program: string;
+        args: string[];
+        cwd: string;
+        approved: boolean;
+        executionMode: "sandbox" | "host";
+        isolation: "sandboxed" | "unisolated";
+    }>>;
+    /** 保存精确 configHash 绑定的 workspace grant；调用方必须已完成 CLI 确认。 */
+    approveMcp(workspaceRoot: string, serverName: string): Promise<{
+        serverName: string;
+    }>;
+    /** 删除 server 当前 configHash 对应的 workspace grant。 */
+    revokeMcp(workspaceRoot: string, serverName: string): Promise<boolean>;
+}
+/** 创建 CLI Composition Root；只有 Runtime bootstrap 的 trust 成功阶段才初始化状态 manifest。 */
+export declare function createCliCompositionRoot(options?: CreateCliCompositionRootOptions): CliCompositionRoot;