@oyasmi/pipiclaw 0.5.4 → 0.5.6

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）
 
@@ -140,11 +155,20 @@ pipiclaw
     ├── SOUL.md
     ├── AGENTS.md
     ├── MEMORY.md
+    ├── ENVIRONMENT.md
     ├── events/
     ├── skills/
     └── 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）
@@ -326,6 +350,8 @@ pipiclaw
 
 ### 配置文件（Config Files）
 
+默认根目录是 `~/.pi/pipiclaw/`；如果设置了 `PIPICLAW_HOME`，下面这些路径都会切换到该目录下。
+
 | 文件 | 用途 |
 |------|------|
 | `~/.pi/pipiclaw/channel.json` | 钉钉应用配置 |
@@ -338,6 +364,7 @@ pipiclaw
 | 变量 | 用途 |
 |----------|------|
 | `ANTHROPIC_API_KEY` | Anthropic API Key |
+| `PIPICLAW_HOME` | 覆盖默认的 `~/.pi/pipiclaw/` 根目录 |
 | `PIPICLAW_DEBUG` | 调试模式，会把上下文写到 `last_prompt.json` |
 | `DINGTALK_FORCE_PROXY` | 设为 `true` 时保留 axios 代理设置 |
 
@@ -385,6 +412,7 @@ Pipiclaw 的核心不是一个临时机器人实例，而是一组长期存在
     ├── SOUL.md
     ├── AGENTS.md
     ├── MEMORY.md
+    ├── ENVIRONMENT.md
     ├── events/
     ├── skills/
     ├── sub-agents/
@@ -395,8 +423,7 @@ Pipiclaw 的核心不是一个临时机器人实例，而是一组长期存在
     │   ├── .channel-meta.json
     │   ├── context.jsonl
     │   ├── log.jsonl
-    │   ├── subagent-runs.jsonl
-    │   └── skills/
+    │   └── subagent-runs.jsonl
     └── group_{conversationId}/
         └── ...
 ```
@@ -511,8 +538,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/prompt-builder.js

@@ -31,6 +31,7 @@ ${workspacePath}/
 ├── SOUL.md                      # Your identity/personality (read-only)
 ├── AGENTS.md                    # Custom behavior instructions (read-only)
 ├── MEMORY.md                    # Stable workspace memory (admin-managed, read on demand)
+├── ENVIRONMENT.md               # Environment facts and notable machine-level changes (read on demand)
 ├── sub-agents/                  # Predefined sub-agent definitions
 ├── skills/                      # Global CLI tools you create
 ├── events/                      # Scheduled events
@@ -39,9 +40,7 @@ ${workspacePath}/
     ├── MEMORY.md                # Channel durable memory (read on demand, runtime-managed)
     ├── HISTORY.md               # Channel summarized history (read on demand, runtime-managed)
     ├── log.jsonl                # Raw message archive (cold storage)
-    ├── context.jsonl            # Raw session archive (cold storage)
-    ├── scratch/                 # Your working directory
-    └── skills/                  # Channel-specific tools`);
+    └── context.jsonl            # Raw session archive (cold storage)`);
     sections.push(`## Events
 You can schedule events that wake you up at specific times or when external things happen. Events are JSON files in \`${workspacePath}/events/\`.
 
@@ -80,6 +79,8 @@ Memory files are not preloaded into session context. Read them explicitly when m
 ### Files
 - Workspace memory: ${workspacePath}/MEMORY.md
   Stable shared background memory. Admin-managed. Read on demand.
+- Workspace environment: ${workspacePath}/ENVIRONMENT.md
+  Durable environment facts and notable machine-level changes. Read on demand when environment state or prior machine changes matter.
 - Channel session memory: ${channelPath}/SESSION.md
   Current working state for this channel. Runtime-managed. Read on demand. Prefer this when current task state matters.
 - Channel memory: ${channelPath}/MEMORY.md
@@ -92,20 +93,21 @@ Memory files are not preloaded into session context. Read them explicitly when m
 - SESSION.md is the primary runtime-managed working-state artifact for current active work.
 - The runtime automatically consolidates channel MEMORY.md and HISTORY.md before compaction or session trimming.
 - Workspace MEMORY.md is not updated by normal runtime consolidation.
+- ENVIRONMENT.md is not normal conversational memory. Read it only when environment history or machine state matters.
 
 ### Cold Storage
 - ${channelPath}/log.jsonl is a raw archive. It is not normal memory and is not proactively loaded.
 - ${channelPath}/context.jsonl is a raw session archive. It is not normal memory and is not proactively loaded.
 
 When a task depends on prior decisions, preferences, or long-running work, prefer SESSION.md first for current state, then MEMORY.md, then HISTORY.md.`);
-    sections.push(`## System Configuration Log
-Maintain ${workspacePath}/SYSTEM.md to log all environment modifications:
-- Installed packages (apk add, npm install, pip install)
-- Environment variables set
-- Config files modified
-- Skill dependencies installed
-
-Update this file whenever you modify the environment.`);
+    sections.push(`## Environment Log
+Maintain ${workspacePath}/ENVIRONMENT.md to record durable environment changes when they matter:
+- Installed packages or tools that future work depends on
+- Important environment variables or credential sources
+- Config files modified outside normal project code
+- Runtime prerequisites that affect future sessions
+
+Keep it factual and concise. Do not use it for task progress or conversation summaries.`);
     sections.push(`## Tools
 - read: Read files
 - edit: Surgical file edits

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/agent/workspace-resources.d.ts

@@ -1,6 +1,6 @@
 /**
  * Workspace resource loaders for pipiclaw:
- * SOUL.md, AGENTS.md, and workspace/channel skills.
+ * SOUL.md, AGENTS.md, and workspace-level skills.
  */
 import { type Skill } from "@mariozechner/pi-coding-agent";
 /**
@@ -14,7 +14,6 @@ export declare function getSoul(workspaceDir: string): string;
  */
 export declare function getAgentConfig(channelDir: string): string;
 /**
- * Load skills from both workspace-level and channel-level skill directories.
- * Channel-level skills override global skills with the same name.
+ * Load skills from the workspace-level skill directory only.
  */
 export declare function loadPipiclawSkills(channelDir: string, workspacePath: string): Skill[];

package/dist/agent/workspace-resources.js

@@ -1,6 +1,6 @@
 /**
  * Workspace resource loaders for pipiclaw:
- * SOUL.md, AGENTS.md, and workspace/channel skills.
+ * SOUL.md, AGENTS.md, and workspace-level skills.
  */
 import { loadSkillsFromDir } from "@mariozechner/pi-coding-agent";
 import { existsSync, readFileSync } from "fs";
@@ -44,11 +44,9 @@ export function getAgentConfig(channelDir) {
     return "";
 }
 /**
- * Load skills from both workspace-level and channel-level skill directories.
- * Channel-level skills override global skills with the same name.
+ * Load skills from the workspace-level skill directory only.
  */
 export function loadPipiclawSkills(channelDir, workspacePath) {
-    const skillMap = new Map();
     const hostWorkspacePath = join(channelDir, "..");
     const translatePath = (hostPath) => {
         if (hostPath.startsWith(hostWorkspacePath)) {
@@ -56,19 +54,11 @@ export function loadPipiclawSkills(channelDir, workspacePath) {
         }
         return hostPath;
     };
-    // Load workspace-level skills (global)
     const workspaceSkillsDir = join(hostWorkspacePath, "skills");
-    for (const skill of loadSkillsFromDir({ dir: workspaceSkillsDir, source: "workspace" }).skills) {
+    const skills = loadSkillsFromDir({ dir: workspaceSkillsDir, source: "workspace" }).skills;
+    for (const skill of skills) {
         skill.filePath = translatePath(skill.filePath);
         skill.baseDir = translatePath(skill.baseDir);
-        skillMap.set(skill.name, skill);
     }
-    // Load channel-specific skills
-    const channelSkillsDir = join(channelDir, "skills");
-    for (const skill of loadSkillsFromDir({ dir: channelSkillsDir, source: "channel" }).skills) {
-        skill.filePath = translatePath(skill.filePath);
-        skill.baseDir = translatePath(skill.baseDir);
-        skillMap.set(skill.name, skill);
-    }
-    return Array.from(skillMap.values());
+    return skills;
 }

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { runSidecarTask, type SidecarResult, type SidecarTask, } from "./memory/
 export { getApiKeyForModel } from "./models/api-keys.js";
 export { findExactModelReferenceMatch, 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";
 export { type BusyMessageMode, DingTalkBot, type DingTalkConfig, type DingTalkContext, type DingTalkEvent, type DingTalkHandler, } from "./runtime/dingtalk.js";
 export { createEventsWatcher, EventsWatcher, type ImmediateEvent, type OneShotEvent, type PeriodicEvent, type ScheduledEvent, } from "./runtime/events.js";

package/dist/index.js

@@ -13,6 +13,7 @@ export { runSidecarTask, } from "./memory/sidecar-worker.js";
 export { getApiKeyForModel } from "./models/api-keys.js";
 export { findExactModelReferenceMatch, 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";
 export { DingTalkBot, } from "./runtime/dingtalk.js";
 export { createEventsWatcher, EventsWatcher, } from "./runtime/events.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/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,10 +2,12 @@ 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";
 import { parseSandboxArg, validateSandbox } from "../sandbox.js";
+import { ensureChannelDir } from "./channel-paths.js";
 import { createDingTalkContext } from "./delivery.js";
 import { DingTalkBot, } from "./dingtalk.js";
 import { createEventsWatcher } from "./events.js";
@@ -68,6 +70,26 @@ This file stores stable workspace-level memory.
 
 <!-- Put long-lived project facts here. -->
 `;
+const DEFAULT_ENVIRONMENT = `# Environment
+
+This file records durable environment facts and notable machine-level changes.
+
+- Record installed tools, runtime prerequisites, and important config changes here.
+- Keep entries concise and factual.
+- Do not use this file for task progress, conversation summaries, or project-specific decisions.
+
+## Environment Facts
+
+<!-- Put stable machine or runtime facts here. -->
+
+## Installed Tools
+
+<!-- Record durable tools or dependencies that were installed for this workspace. -->
+
+## Config Changes
+
+<!-- Record important config or environment changes that affect future work. -->
+`;
 const CHANNEL_CONFIG_TEMPLATE = {
     clientId: "your-dingtalk-client-id",
     clientSecret: "your-dingtalk-client-secret",
@@ -78,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,
@@ -139,6 +162,7 @@ export function bootstrapAppHome(paths = DEFAULT_BOOTSTRAP_PATHS) {
     writeTextFileIfMissing(join(paths.workspaceDir, "SOUL.md"), DEFAULT_SOUL, "workspace/SOUL.md", created);
     writeTextFileIfMissing(join(paths.workspaceDir, "AGENTS.md"), DEFAULT_AGENT, "workspace/AGENTS.md", created);
     writeTextFileIfMissing(join(paths.workspaceDir, "MEMORY.md"), DEFAULT_MEMORY, "workspace/MEMORY.md", created);
+    writeTextFileIfMissing(join(paths.workspaceDir, "ENVIRONMENT.md"), DEFAULT_ENVIRONMENT, "workspace/ENVIRONMENT.md", created);
     const channelTemplateCreated = writeJsonFileIfMissing(paths.channelConfigPath, CHANNEL_CONFIG_TEMPLATE, "channel.json", created);
     writeJsonFileIfMissing(paths.authConfigPath, {}, "auth.json", created);
     writeJsonFileIfMissing(paths.modelsConfigPath, MODELS_CONFIG_TEMPLATE, "models.json", created);
@@ -247,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;
@@ -273,11 +294,11 @@ export async function bootstrap(argv, options = {}) {
     const getState = (channelId) => {
         let state = channelStates.get(channelId);
         if (!state) {
-            const channelDir = join(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);
@@ -383,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;
         }
@@ -421,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;
     };
@@ -441,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/runtime/channel-paths.d.ts

@@ -0,0 +1,3 @@
+export declare function getChannelDirName(channelId: string): string;
+export declare function getChannelDir(baseDir: string, channelId: string): string;
+export declare function ensureChannelDir(baseDir: string, channelId: string): string;

package/dist/runtime/channel-paths.js

@@ -0,0 +1,13 @@
+import { mkdirSync } from "fs";
+import { join } from "path";
+export function getChannelDirName(channelId) {
+    return channelId.replaceAll("/", "__");
+}
+export function getChannelDir(baseDir, channelId) {
+    return join(baseDir, getChannelDirName(channelId));
+}
+export function ensureChannelDir(baseDir, channelId) {
+    const channelDir = getChannelDir(baseDir, channelId);
+    mkdirSync(channelDir, { recursive: true });
+    return channelDir;
+}

package/dist/runtime/dingtalk.js

@@ -14,6 +14,7 @@ import { dirname, join } from "path";
 import { parseBuiltInCommand, renderBuiltInHelp } from "../agent/commands.js";
 import * as log from "../log.js";
 import { isRecord } from "../shared/type-guards.js";
+import { getChannelDir } from "./channel-paths.js";
 class ChannelQueue {
     constructor() {
         this.queue = [];
@@ -761,6 +762,6 @@ export class DingTalkBot {
     getConversationMetaPath(channelId) {
         if (!this.config.stateDir)
             return null;
-        return join(this.config.stateDir, channelId, ".channel-meta.json");
+        return join(getChannelDir(this.config.stateDir, channelId), ".channel-meta.json");
     }
 }

package/dist/runtime/store.js

@@ -1,6 +1,7 @@
 import { closeSync, existsSync, mkdirSync, openSync, readSync, renameSync, statSync } from "fs";
 import { appendFile, writeFile } from "fs/promises";
 import { dirname, join } from "path";
+import { ensureChannelDir, getChannelDir } from "./channel-paths.js";
 const MAX_LOG_SIZE_BYTES = 1_000_000;
 const DEDUPE_TTL_MS = 60_000;
 const DEDUPE_CLEANUP_INTERVAL_MS = 30_000;
@@ -19,11 +20,7 @@ export class ChannelStore {
      * Get or create the directory for a channel/DM
      */
     getChannelDir(channelId) {
-        const dir = join(this.workingDir, channelId);
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
-        return dir;
+        return ensureChannelDir(this.workingDir, channelId);
     }
     /**
      * Log a message to the channel's log.jsonl raw archive.
@@ -102,7 +99,7 @@ export class ChannelStore {
      * Returns null if no log exists
      */
     getLastTimestamp(channelId) {
-        const logPath = join(this.workingDir, channelId, "log.jsonl");
+        const logPath = join(getChannelDir(this.workingDir, channelId), "log.jsonl");
         if (!existsSync(logPath)) {
             return null;
         }