@oyasmi/pipiclaw 0.5.5 → 0.5.7

package/README.md

@@ -11,6 +11,7 @@ npm package: [`@oyasmi/pipiclaw`](https://www.npmjs.com/package/@oyasmi/pipiclaw
 - 配置手册：[docs/configuration.md](./docs/configuration.md)
 - 事件与子代理使用指南：[docs/events-and-sub-agents.md](./docs/events-and-sub-agents.md)
 - 部署与运维指南：[docs/deployment-and-operations.md](./docs/deployment-and-operations.md)
+- 安全文档：[docs/security.md](./docs/security.md)
 
 ## 功能特性（Features）
 
@@ -22,6 +23,20 @@ npm package: [`@oyasmi/pipiclaw`](https://www.npmjs.com/package/@oyasmi/pipiclaw
 - 支持预定义子代理（sub-agent）和临时内联子代理（inline sub-agent）
 - 支持立即、单次、周期三类事件调度
 - 支持自定义模型提供方（provider）和模型（model）配置
+- 内置工具层安全防护：`bash` 命令守卫、文件路径守卫、敏感路径拒绝、阻断审计日志
+
+## 安全说明（Security）
+
+Pipiclaw 当前已经内置一轮工具层安全增强：
+
+- `bash` 会拦截明显高风险命令
+- `read` / `write` / `edit` / `attach` 会做统一路径检查
+- 默认允许访问用户主目录中的普通工作文件，但会拒绝常见凭据、私钥、浏览器资料、系统敏感文件等位置
+- 可通过 `~/.pi/pipiclaw/security.json` 做实例级策略调整
+
+如果你要了解默认策略、已知边界、推荐模板和完整配置示例，请直接看：
+
+- [docs/security.md](./docs/security.md)
 
 ## 快速开始（Quickstart）
 
@@ -146,6 +161,14 @@ pipiclaw
     └── sub-agents/
 ```
 
+默认 app home 是 `~/.pi/pipiclaw/`。如果你希望把 Pipiclaw 的所有配置和运行文件放到别处，可以在启动前设置：
+
+```bash
+export PIPICLAW_HOME=/your/custom/pipiclaw-home
+```
+
+设置后，`channel.json`、`auth.json`、`models.json`、`settings.json` 和整个 `workspace/` 都会改为从这个目录读取和写入。
+
 如果 `channel.json` 仍然是初始化模板，程序会提示你补全配置后再启动。这是正常行为。
 
 #### 4. 创建钉钉应用（Create a DingTalk App）
@@ -304,6 +327,9 @@ pipiclaw
 
 确认当前可见模型和默认模型都符合预期后，再发送一条普通消息，例如：
 
+- `/model` 会列出当前模型和可用模型
+- 切换时支持精确的 `provider/modelId`、精确的 `modelId`，以及能唯一命中的片段字符串，例如 `/model turbo`
+
 ```text
 请介绍一下你自己，并说明你现在能做什么
 ```
@@ -327,6 +353,8 @@ pipiclaw
 
 ### 配置文件（Config Files）
 
+默认根目录是 `~/.pi/pipiclaw/`；如果设置了 `PIPICLAW_HOME`，下面这些路径都会切换到该目录下。
+
 | 文件 | 用途 |
 |------|------|
 | `~/.pi/pipiclaw/channel.json` | 钉钉应用配置 |
@@ -339,6 +367,7 @@ pipiclaw
 | 变量 | 用途 |
 |----------|------|
 | `ANTHROPIC_API_KEY` | Anthropic API Key |
+| `PIPICLAW_HOME` | 覆盖默认的 `~/.pi/pipiclaw/` 根目录 |
 | `PIPICLAW_DEBUG` | 调试模式，会把上下文写到 `last_prompt.json` |
 | `DINGTALK_FORCE_PROXY` | 设为 `true` 时保留 axios 代理设置 |
 
@@ -368,9 +397,22 @@ Pipiclaw 有两层命令。
 | `/new` | 开启一个新的会话 |
 | `/compact [instructions]` | 手动压缩当前会话上下文，可附带额外说明 |
 | `/session` | 查看当前会话状态、消息统计、token 使用量和当前模型 |
-| `/model [provider/modelId|modelId]` | 查看当前模型，或切换到指定模型 |
+| `/model [provider/modelId|modelId|substring]` | 查看当前模型，或切换到指定模型 |
+
+`/model` 的匹配顺序是：
+
+1. 精确匹配 `provider/modelId`
+2. 精确匹配 `modelId`
+3. 对完整的 `provider/modelId` 做子字符串匹配
 
-`/model` 只支持精确匹配切换。
+只有当片段字符串能唯一命中一个可用模型时才会切换。例如：
+
+- `/model qwen`
+- `/model k2.5`
+- `/model turbo`
+- `/model zpai`
+
+像 `/model glm5` 这种不构成子字符串的输入不会命中。
 
 ## 工作区结构（Workspace Layout）
 
@@ -476,7 +518,7 @@ Pipiclaw 不会把所有历史对话无上限地塞进 prompt，而是按层管
 - 如果是 OpenAI-compatible 服务，是否需要：
   - `"supportsDeveloperRole": false`
   - `"supportsReasoningEffort": false`
-- 给机器人发送 `/model`，确认当前可见模型和默认模型是否正确
+- 给机器人发送 `/model`，确认当前可见模型和默认模型是否正确；如需切换，也可以用唯一命中的片段，例如 `/model turbo`
 
 ### 机器人能收到消息，但没有回复（The Bot Receives Messages but Does Not Reply）
 
@@ -512,8 +554,17 @@ npm run check
 
 - `npm run typecheck`
 - `npm run test`
+- `npm run test:e2e`
 - `npm run check`
 
+端到端测试说明：
+
+- `npm run test:e2e` 会运行“除钉钉渠道外”的完整 E2E
+- 它会使用真实 runtime、真实 `ChannelStore`、真实工具/记忆/Sidecar/LLM
+- 只 mock 钉钉传输层，不连接真实钉钉 Stream
+- 运行前需要可用模型凭据：优先读取 `${PIPICLAW_HOME:-~/.pi/pipiclaw}/auth.json`，否则回退到 `ANTHROPIC_API_KEY`
+- E2E 默认不包含在 `npm run test` 中，避免日常测试被真实 LLM 依赖和调用成本影响
+
 ## 许可证（License）
 
 Apache License 2.0. See [LICENSE](./LICENSE).

package/dist/agent/channel-runner.d.ts

@@ -30,6 +30,7 @@ export declare class ChannelRunner implements AgentRunner {
     handleBuiltinCommand(ctx: DingTalkContext, command: BuiltInCommand): Promise<void>;
     queueSteer(text: string, userName?: string): Promise<void>;
     queueFollowUp(text: string, userName?: string): Promise<void>;
+    flushMemoryForShutdown(): Promise<void>;
     abort(): Promise<void>;
     private sendCommandReply;
     private requireQueuedMessage;

package/dist/agent/channel-runner.js

@@ -323,6 +323,9 @@ export class ChannelRunner {
     async queueFollowUp(text, userName) {
         await this.queueBusyMessage("followUp", this.requireQueuedMessage(text, "followup"), userName);
     }
+    async flushMemoryForShutdown() {
+        await this.memoryLifecycle.flushForShutdown();
+    }
     async abort() {
         await this.session.abort();
     }

package/dist/agent/command-extension.js

@@ -1,5 +1,5 @@
 import { basename } from "path";
-import { findExactModelReferenceMatch, formatModelList, formatModelReference } from "../models/utils.js";
+import { findModelReferenceMatch, formatModelList, formatModelReference } from "../models/utils.js";
 export const COMMAND_RESULT_CUSTOM_TYPE = "pipiclaw.command_result";
 function buildSessionText(stats, currentModel, thinkingLevel) {
     const modelText = currentModel ? `\`${formatModelReference(currentModel)}\`` : "(none)";
@@ -43,7 +43,7 @@ export function createCommandExtension(options) {
             },
         });
         pi.registerCommand("model", {
-            description: "Show the current model or switch models using an exact match",
+            description: "Show the current model or switch models using an exact or uniquely matching substring",
             handler: async (args) => {
                 const availableModels = await options.getAvailableModels();
                 const currentModel = options.getCurrentModel();
@@ -54,13 +54,13 @@ export function createCommandExtension(options) {
 
 Current model: ${current}
 
-Use \`/model <provider/modelId>\` or \`/model <modelId>\` to switch. Bare model IDs must resolve uniquely.
+Use \`/model <provider/modelId>\`, \`/model <modelId>\`, or any uniquely matching substring to switch.
 
 Available models:
 ${available}`);
                     return;
                 }
-                const match = findExactModelReferenceMatch(args, availableModels);
+                const match = findModelReferenceMatch(args, availableModels);
                 const available = availableModels.length > 0 ? formatModelList(availableModels, currentModel, 10) : "- (none)";
                 if (match.match) {
                     await options.switchModel(match.match);
@@ -68,13 +68,13 @@ ${available}`);
                     return;
                 }
                 if (match.ambiguous) {
-                    sendCommandResult(pi, `未切换模型：\`${args.trim()}\` 匹配到多个模型。请改用精确的 \`provider/modelId\` 形式。
+                    sendCommandResult(pi, `未切换模型：\`${args.trim()}\` 匹配到多个模型。请提供更精确的 \`provider/modelId\`、\`modelId\` 或更长的片段。
 
 Available models:
 ${available}`);
                     return;
                 }
-                sendCommandResult(pi, `未找到模型 \`${args.trim()}\`。请使用精确的 \`provider/modelId\` 或唯一的 \`modelId\`。
+                sendCommandResult(pi, `未找到模型 \`${args.trim()}\`。请使用精确的 \`provider/modelId\`、唯一的 \`modelId\`，或能唯一命中的片段字符串。
 
 Available models:
 ${available}`);

package/dist/agent/commands.js

@@ -29,7 +29,7 @@ These are handled inside the Pipiclaw session layer:
   Show current session state, message stats, token usage, and model info
   Example: \`/session\`
 - \`/model [provider/modelId|modelId]\`
-  Show the current model, or switch models using an exact match
+  Show the current model, or switch models using an exact match or a uniquely matching substring
   Example: \`/model\`
   Example: \`/model anthropic/claude-opus-4-6\`
 - \`/new\`

package/dist/agent/runner-factory.d.ts

@@ -1,3 +1,5 @@
 import type { SandboxConfig } from "../sandbox.js";
 import type { AgentRunner } from "./types.js";
 export declare function getOrCreateRunner(sandboxConfig: SandboxConfig, channelId: string, channelDir: string): AgentRunner;
+export declare function resetRunner(channelId: string): void;
+export declare function resetAllRunners(): void;

package/dist/agent/runner-factory.js

@@ -8,3 +8,9 @@ export function getOrCreateRunner(sandboxConfig, channelId, channelDir) {
     channelRunners.set(channelId, runner);
     return runner;
 }
+export function resetRunner(channelId) {
+    channelRunners.delete(channelId);
+}
+export function resetAllRunners() {
+    channelRunners.clear();
+}

package/dist/agent/types.d.ts

@@ -10,6 +10,7 @@ export interface AgentRunner {
     handleBuiltinCommand(ctx: DingTalkContext, command: BuiltInCommand): Promise<void>;
     queueSteer(text: string, userName?: string): Promise<void>;
     queueFollowUp(text: string, userName?: string): Promise<void>;
+    flushMemoryForShutdown(): Promise<void>;
     abort(): Promise<void>;
 }
 export type FinalOutcome = {

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export { type RecalledMemory, type RecallRequest, type RecallResult, recallRelev
 export { renderSessionMemory, type SessionMemoryState, type SessionMemoryUpdateOptions, updateChannelSessionMemory, } from "./memory/session.js";
 export { runSidecarTask, type SidecarResult, type SidecarTask, } from "./memory/sidecar-worker.js";
 export { getApiKeyForModel } from "./models/api-keys.js";
-export { findExactModelReferenceMatch, formatModelList, formatModelReference, resolveInitialModel, } from "./models/utils.js";
+export { findExactModelReferenceMatch, findModelReferenceMatch, formatModelList, formatModelReference, resolveInitialModel, } from "./models/utils.js";
 export { APP_HOME_DIR, APP_NAME, AUTH_CONFIG_PATH, CHANNEL_CONFIG_PATH, MODELS_CONFIG_PATH, SETTINGS_CONFIG_PATH, SUB_AGENTS_DIR, SUB_AGENTS_DIR_NAME, WORKSPACE_DIR, } from "./paths.js";
 export { ensureChannelDir, getChannelDir, getChannelDirName, } from "./runtime/channel-paths.js";
 export { createDingTalkContext } from "./runtime/delivery.js";

package/dist/index.js

@@ -11,7 +11,7 @@ export { recallRelevantMemory, } from "./memory/recall.js";
 export { renderSessionMemory, updateChannelSessionMemory, } from "./memory/session.js";
 export { runSidecarTask, } from "./memory/sidecar-worker.js";
 export { getApiKeyForModel } from "./models/api-keys.js";
-export { findExactModelReferenceMatch, formatModelList, formatModelReference, resolveInitialModel, } from "./models/utils.js";
+export { findExactModelReferenceMatch, findModelReferenceMatch, formatModelList, formatModelReference, resolveInitialModel, } from "./models/utils.js";
 export { APP_HOME_DIR, APP_NAME, AUTH_CONFIG_PATH, CHANNEL_CONFIG_PATH, MODELS_CONFIG_PATH, SETTINGS_CONFIG_PATH, SUB_AGENTS_DIR, SUB_AGENTS_DIR_NAME, WORKSPACE_DIR, } from "./paths.js";
 export { ensureChannelDir, getChannelDir, getChannelDirName, } from "./runtime/channel-paths.js";
 export { createDingTalkContext } from "./runtime/delivery.js";

package/dist/memory/lifecycle.d.ts

@@ -2,7 +2,7 @@ import type { AgentMessage } from "@mariozechner/pi-agent-core";
 import type { Api, Model } from "@mariozechner/pi-ai";
 import type { ExtensionFactory, SessionEntry } from "@mariozechner/pi-coding-agent";
 import type { PipiclawSessionMemorySettings } from "../settings.js";
-export type ConsolidationReason = "compaction" | "new-session" | "idle";
+export type ConsolidationReason = "compaction" | "new-session" | "idle" | "shutdown";
 export interface MemoryLifecycleOptions {
     channelId: string;
     channelDir: string;
@@ -33,6 +33,7 @@ export declare class MemoryLifecycle {
     noteUserTurnStarted(): void;
     noteToolCall(): void;
     noteCompletedAssistantTurn(): void;
+    flushForShutdown(): Promise<void>;
     private clearIdleConsolidationTimer;
     private shouldForceRefreshFor;
     private refreshSessionMemory;

package/dist/memory/lifecycle.js

@@ -73,6 +73,18 @@ export class MemoryLifecycle {
         }
         this.scheduleIdleConsolidation();
     }
+    async flushForShutdown() {
+        this.clearIdleConsolidationTimer();
+        const run = async () => {
+            if (!this.hasPendingAssistantSnapshot()) {
+                return;
+            }
+            await this.runPreflightConsolidation("shutdown");
+        };
+        const resultPromise = this.backgroundQueue.then(run, run);
+        this.backgroundQueue = resultPromise.then(() => undefined, () => undefined);
+        await resultPromise;
+    }
     clearIdleConsolidationTimer() {
         if (!this.idleConsolidationTimer) {
             return;
@@ -84,7 +96,13 @@ export class MemoryLifecycle {
         if (!settings.enabled) {
             return false;
         }
-        return reason === "compaction" ? settings.forceRefreshBeforeCompact : settings.forceRefreshBeforeNewSession;
+        if (reason === "compaction") {
+            return settings.forceRefreshBeforeCompact;
+        }
+        if (reason === "new-session") {
+            return settings.forceRefreshBeforeNewSession;
+        }
+        return false;
     }
     async refreshSessionMemory(request) {
         const settings = this.options.getSessionMemorySettings();

package/dist/models/utils.d.ts

@@ -6,5 +6,9 @@ export declare function findExactModelReferenceMatch(modelReference: string, ava
     match?: Model<Api>;
     ambiguous: boolean;
 };
+export declare function findModelReferenceMatch(modelReference: string, availableModels: Model<Api>[]): {
+    match?: Model<Api>;
+    ambiguous: boolean;
+};
 export declare function formatModelList(models: Model<Api>[], currentModel: Model<Api> | undefined, limit?: number): string;
 export declare function resolveInitialModel(modelRegistry: ModelRegistry, settingsManager: PipiclawSettingsManager): Model<Api>;

package/dist/models/utils.js

@@ -38,6 +38,21 @@ export function findExactModelReferenceMatch(modelReference, availableModels) {
     }
     return { ambiguous: idMatches.length > 1 };
 }
+export function findModelReferenceMatch(modelReference, availableModels) {
+    const exactMatch = findExactModelReferenceMatch(modelReference, availableModels);
+    if (exactMatch.match || exactMatch.ambiguous) {
+        return exactMatch;
+    }
+    const normalizedReference = modelReference.trim().toLowerCase();
+    if (!normalizedReference) {
+        return { ambiguous: false };
+    }
+    const substringMatches = availableModels.filter((model) => formatModelReference(model).toLowerCase().includes(normalizedReference));
+    if (substringMatches.length === 1) {
+        return { match: substringMatches[0], ambiguous: false };
+    }
+    return { ambiguous: substringMatches.length > 1 };
+}
 export function formatModelList(models, currentModel, limit = 20) {
     const refs = models
         .slice()

package/dist/paths.js

@@ -1,7 +1,7 @@
 import { homedir } from "os";
 import { join } from "path";
 export const APP_NAME = "pipiclaw";
-export const APP_HOME_DIR = join(homedir(), ".pi", APP_NAME);
+export const APP_HOME_DIR = process.env.PIPICLAW_HOME ?? join(homedir(), ".pi", APP_NAME);
 export const WORKSPACE_DIR = join(APP_HOME_DIR, "workspace");
 export const SUB_AGENTS_DIR_NAME = "sub-agents";
 export const SUB_AGENTS_DIR = join(WORKSPACE_DIR, SUB_AGENTS_DIR_NAME);

package/dist/runtime/bootstrap.d.ts

@@ -1,5 +1,5 @@
 import { type SandboxConfig } from "../sandbox.js";
-import { DingTalkBot, type DingTalkConfig } from "./dingtalk.js";
+import { DingTalkBot, type DingTalkConfig, type DingTalkHandler } from "./dingtalk.js";
 import { ChannelStore } from "./store.js";
 export interface BootstrapPaths {
     appName: string;
@@ -33,6 +33,11 @@ export interface AppContext {
     store: ChannelStore;
     shutdown: () => Promise<void>;
 }
+export interface RuntimeContext {
+    handler: DingTalkHandler;
+    store: ChannelStore;
+    shutdown: (reason?: NodeJS.Signals | "manual") => Promise<void>;
+}
 export declare const DEFAULT_BOOTSTRAP_PATHS: BootstrapPaths;
 export declare class BootstrapExitError extends Error {
     readonly code: number;
@@ -44,4 +49,20 @@ export declare function bootstrapAppHome(paths?: BootstrapPaths): BootstrapResul
 export declare function printBootstrapSummary(result: BootstrapResult, io?: BootstrapIO, paths?: BootstrapPaths): void;
 export declare function loadConfig(paths?: BootstrapPaths, io?: BootstrapIO): DingTalkConfig;
 export declare function parseArgs(argv: string[], paths?: BootstrapPaths, io?: BootstrapIO): ParsedArgs;
+interface RuntimeContextOptions {
+    paths: BootstrapPaths;
+    sandbox: SandboxConfig;
+    dingtalkConfig: DingTalkConfig;
+    createBot?: (handler: DingTalkHandler, config: DingTalkConfig) => DingTalkBot;
+    createEventsWatcher?: (workspaceDir: string, bot: DingTalkBot) => {
+        start(): void;
+        stop(): void;
+    };
+    startServices?: boolean;
+    registerSignalHandlers?: boolean;
+}
+export declare function createRuntimeContext(options: RuntimeContextOptions): RuntimeContext & {
+    bot: DingTalkBot;
+};
 export declare function bootstrap(argv: string[], options?: BootstrapOptions): Promise<AppContext>;
+export {};

package/dist/runtime/bootstrap.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
 import { parseBuiltInCommand } from "../agent/commands.js";
 import { getOrCreateRunner } from "../agent/index.js";
+import { resetRunner } from "../agent/runner-factory.js";
 import * as log from "../log.js";
 import { ensureChannelMemoryFilesSync } from "../memory/files.js";
 import { APP_HOME_DIR, APP_NAME, AUTH_CONFIG_PATH, CHANNEL_CONFIG_PATH, MODELS_CONFIG_PATH, SETTINGS_CONFIG_PATH, WORKSPACE_DIR, } from "../paths.js";
@@ -99,6 +100,7 @@ const CHANNEL_CONFIG_TEMPLATE = {
 };
 const MODELS_CONFIG_TEMPLATE = { providers: {} };
 const SHUTDOWN_WAIT_MS = 15000;
+const SHUTDOWN_FLUSH_WAIT_MS = 25000;
 const SHUTDOWN_ABORT_WAIT_MS = 5000;
 export const DEFAULT_BOOTSTRAP_PATHS = {
     appName: APP_NAME,
@@ -269,25 +271,22 @@ function waitForTasks(tasks, timeoutMs) {
         }),
     ]);
 }
-export async function bootstrap(argv, options = {}) {
-    const env = options.env ?? process.env;
-    const io = options.io ?? console;
-    const paths = options.paths ?? DEFAULT_BOOTSTRAP_PATHS;
-    const registerSignalHandlers = options.registerSignalHandlers ?? true;
-    const startServices = options.startServices ?? true;
-    sanitizeProxyEnv(env);
-    const parsedArgs = parseArgs(argv, paths, io);
-    const sandbox = parsedArgs.sandbox;
-    const bootstrapResult = bootstrapAppHome(paths);
-    printBootstrapSummary(bootstrapResult, io, paths);
-    if (bootstrapResult.channelTemplateCreated) {
-        io.error(`Fill in ${paths.channelConfigPath} and run \`${paths.appName}\` again.`);
-        throw new BootstrapExitError(1);
+function flushInactiveChannelMemory(channelStates) {
+    const flushes = [];
+    for (const [channelId, state] of channelStates) {
+        if (state.running) {
+            continue;
+        }
+        flushes.push(state.runner.flushMemoryForShutdown().catch((err) => {
+            log.logWarning(`[${channelId}] Failed to flush memory during shutdown`, err instanceof Error ? err.message : String(err));
+        }));
     }
-    const dingtalkConfig = loadConfig(paths, io);
-    dingtalkConfig.stateDir = paths.workspaceDir;
-    await validateSandbox(sandbox);
-    const store = new ChannelStore({ workingDir: paths.workspaceDir });
+    return flushes;
+}
+export function createRuntimeContext(options) {
+    const startServices = options.startServices ?? true;
+    const registerSignalHandlers = options.registerSignalHandlers ?? true;
+    const store = new ChannelStore({ workingDir: options.paths.workspaceDir });
     const channelStates = new Map();
     const activeTasks = new Set();
     let shuttingDown = false;
@@ -295,11 +294,11 @@ export async function bootstrap(argv, options = {}) {
     const getState = (channelId) => {
         let state = channelStates.get(channelId);
         if (!state) {
-            const channelDir = ensureChannelDir(paths.workspaceDir, channelId);
+            const channelDir = ensureChannelDir(options.paths.workspaceDir, channelId);
             ensureChannelMemoryFilesSync(channelDir);
             state = {
                 running: false,
-                runner: getOrCreateRunner(sandbox, channelId, channelDir),
+                runner: getOrCreateRunner(options.sandbox, channelId, channelDir),
                 stopRequested: false,
             };
             channelStates.set(channelId, state);
@@ -405,10 +404,13 @@ export async function bootstrap(argv, options = {}) {
             }
         },
     };
-    log.logStartup(paths.workspaceDir, sandbox.type === "host" ? "host" : `docker:${sandbox.container}`);
-    const bot = new DingTalkBot(handler, dingtalkConfig);
-    const eventsWatcher = createEventsWatcher(paths.workspaceDir, bot);
-    const shutdownWithReason = async (reason) => {
+    const bot = options.createBot
+        ? options.createBot(handler, options.dingtalkConfig)
+        : new DingTalkBot(handler, options.dingtalkConfig);
+    const eventsWatcher = options.createEventsWatcher
+        ? options.createEventsWatcher(options.paths.workspaceDir, bot)
+        : createEventsWatcher(options.paths.workspaceDir, bot);
+    const shutdownWithReason = async (reason = "manual") => {
         if (shutdownPromise) {
             return shutdownPromise;
         }
@@ -443,6 +445,17 @@ export async function bootstrap(argv, options = {}) {
                     }
                 }
             }
+            const flushes = flushInactiveChannelMemory(channelStates);
+            if (flushes.length > 0) {
+                log.logInfo(`Flushing memory for ${flushes.length} inactive channel(s) before shutdown`);
+                const flushed = await waitForTasks(flushes, SHUTDOWN_FLUSH_WAIT_MS);
+                if (!flushed) {
+                    log.logWarning(`Shutdown memory flush exceeded ${SHUTDOWN_FLUSH_WAIT_MS}ms`);
+                }
+            }
+            for (const channelId of channelStates.keys()) {
+                resetRunner(channelId);
+            }
         })();
         return shutdownPromise;
     };
@@ -463,10 +476,43 @@ export async function bootstrap(argv, options = {}) {
         void bot.start();
     }
     return {
-        bot,
+        handler,
         store,
+        bot,
+        shutdown: shutdownWithReason,
+    };
+}
+export async function bootstrap(argv, options = {}) {
+    const env = options.env ?? process.env;
+    const io = options.io ?? console;
+    const paths = options.paths ?? DEFAULT_BOOTSTRAP_PATHS;
+    const registerSignalHandlers = options.registerSignalHandlers ?? true;
+    const startServices = options.startServices ?? true;
+    sanitizeProxyEnv(env);
+    const parsedArgs = parseArgs(argv, paths, io);
+    const sandbox = parsedArgs.sandbox;
+    const bootstrapResult = bootstrapAppHome(paths);
+    printBootstrapSummary(bootstrapResult, io, paths);
+    if (bootstrapResult.channelTemplateCreated) {
+        io.error(`Fill in ${paths.channelConfigPath} and run \`${paths.appName}\` again.`);
+        throw new BootstrapExitError(1);
+    }
+    const dingtalkConfig = loadConfig(paths, io);
+    dingtalkConfig.stateDir = paths.workspaceDir;
+    await validateSandbox(sandbox);
+    log.logStartup(paths.workspaceDir, sandbox.type === "host" ? "host" : `docker:${sandbox.container}`);
+    const runtime = createRuntimeContext({
+        paths,
+        sandbox,
+        dingtalkConfig,
+        registerSignalHandlers,
+        startServices,
+    });
+    return {
+        bot: runtime.bot,
+        store: runtime.store,
         shutdown: async () => {
-            await shutdownWithReason("manual");
+            await runtime.shutdown("manual");
         },
     };
 }

package/dist/security/command-guard.d.ts

@@ -0,0 +1,16 @@
+import type { CommandGuardResult, SecurityConfig } from "./types.js";
+interface ParsedCommand {
+    command: string;
+    args: string[];
+    normalized: string;
+}
+declare function splitCommandChain(command: string): string[];
+declare function parseShellWords(command: string): string[];
+declare function parseCommand(command: string): ParsedCommand | null;
+export declare function guardCommand(command: string, config: SecurityConfig["commandGuard"]): CommandGuardResult;
+export declare const internalCommandGuard: {
+    parseShellWords: typeof parseShellWords;
+    parseCommand: typeof parseCommand;
+    splitCommandChain: typeof splitCommandChain;
+};
+export {};