mocode-ai 0.4.7 → 0.4.9

package/dist/memory/store.d.ts

@@ -0,0 +1,124 @@
+export type MemoryType = 'decision' | 'fact' | 'pitfall' | 'reference' | 'feedback';
+export type MemoryStatus = 'active' | 'superseded' | 'archived';
+export type MemoryScope = 'project' | 'global';
+export interface MemoryEntry {
+    id: string;
+    type: MemoryType;
+    name: string;
+    summary: string;
+    body: string;
+    createdAt: string;
+    updatedAt: string;
+    lastRecalledAt: string | null;
+    recallCount: number;
+    status: MemoryStatus;
+    supersededBy: string | null;
+    pinned: boolean;
+    scope: MemoryScope;
+    source: {
+        session?: string;
+        turn?: number;
+    } | null;
+    lastUpdateReason?: string;
+}
+/** 索引项(无 body,不进 history 也不占 token)。 */
+export interface MemoryIndexItem {
+    id: string;
+    name: string;
+    summary: string;
+    type: MemoryType;
+    status: MemoryStatus;
+}
+/** 加载全部(global + project),按文件归一化 scope(防旧条目缺字段 / 字段错)。 */
+export declare function loadAll(): MemoryEntry[];
+export interface SaveInput {
+    name: string;
+    summary: string;
+    body: string;
+    type?: MemoryType;
+    pinned?: boolean;
+    scope?: MemoryScope;
+    source?: {
+        session?: string;
+        turn?: number;
+    } | null;
+}
+export type SaveResult = {
+    ok: true;
+    id: string;
+} | {
+    ok: false;
+    exists: string;
+};
+/** 新建:id 全局唯一(跨两文件),撞库返 exists 让工具层提示用 memory_update。 */
+export declare function saveEntry(input: SaveInput): SaveResult;
+export interface SearchOpts {
+    type?: MemoryType;
+    status?: MemoryStatus | 'any';
+    limit?: number;
+}
+/** 关键词搜索:多词子串匹配(name 权重最高)。命中即 bump recallCount/lastRecalledAt 写回(遗忘衰减依据)。 */
+export declare function searchEntries(query: string, opts?: SearchOpts): MemoryEntry[];
+/** 索引(无 body、不 bump recall)。 */
+export declare function listEntries(opts?: {
+    type?: MemoryType;
+    status?: MemoryStatus | 'any';
+}): MemoryIndexItem[];
+export interface UpdatePatch {
+    name?: string;
+    summary?: string;
+    body?: string;
+    reason?: string;
+    pinned?: boolean;
+}
+export type UpdateResult = {
+    ok: true;
+} | {
+    ok: false;
+    notFound: true;
+};
+/** 原地改:id 不变(name 可改 → 但 id 仍是旧 slug,故 name 改不会触发重 slug);记 lastUpdateReason;pinned 可切换。 */
+export declare function updateEntry(id: string, patch: UpdatePatch): UpdateResult;
+export type ForgetResult = {
+    ok: true;
+    mode: string;
+} | {
+    ok: false;
+    notFound: true;
+} | {
+    ok: false;
+    pinned: true;
+};
+/** 归档(默认,可复活)/ 硬删;pinned 拒删。 */
+export declare function forgetEntry(id: string, mode?: 'archive' | 'delete'): ForgetResult;
+export interface GcResult {
+    decayed: number;
+    capped: number;
+    gced: number;
+}
+/**
+ * 遗忘策略(全同步,后台调):
+ *  ① archived 超 GC_DAYS → 硬删;
+ *  ② active + !pinned + (lastRecalledAt|createdAt) 早于 DECAY_DAYS → archived;
+ *  ③ active 数 > MAX_ACTIVE → 按 recallCount 低 × 最近未召回久 淘汰到 archived。
+ * pinned 豁免一切自动衰减。写回两文件(均按 scope 过滤)。
+ */
+export declare function gcMemories(): GcResult;
+/**
+ * active 条目按 updatedAt 降序,封顶 MAX_INDEX_ENTRIES,只注 id/name/summary/type。
+ * 无 active 返空串(零行为变化)。body 不注入——按需 memory_search 取。
+ *
+ * 索引策略(省 token):不全量塞进每轮 systemPrompt。
+ *  - pinned 永远包含(pinned = 用户明确想长期保留)
+ *  - recallCount ≥ 1 包含(被引用过,价值已验证)
+ *  - 否则仅当 (lastRecalledAt|createdAt) 近 RECENT_MS(=DECAY_DAYS×2) 内
+ * 排序:pinned 先 → recallCount 降 → updatedAt 降。
+ * 封顶 MAX_INDEX_ENTRIES;尾部标 hidden 数量,引导用 memory_list/memory_search 兜底。
+ * 真正「陈旧」被滤掉时也明示(让 LLM 知道有内容存在但被策略隐藏,而不是误以为空)。
+ *
+ * memoryEnabled=false 时(记忆子系统总开关关闭)直接返空串:Memory Index 段
+ * 不进系统提示,LLM 看不到工具使用提示;配合 tools/builtins 屏蔽 memory_* 工具,
+ * 实现「关闭时零侵入」(默认行为)。传参由 repl 的 buildSystemMessage 在拼装前调
+ * isMemoryEnabled() 注入(本文件是叶子,避免直接引 config 起环)。
+ */
+export declare function buildMemoryIndexSection(memoryEnabled?: boolean): string;

package/dist/permissions/index.js

@@ -0,0 +1,138 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promptIntervention } from '../ui/intervention.js';
+import { config } from '../config/index.js';
+/**
+ * 工具权限系统:基于 risk 字段在执行前拦截确认。
+ *
+ * 设计:
+ *  - safe      → 直接放行(只读工具,零交互)
+ *  - confirm   → 弹面板确认,同工具同会话缓存(避免重复打断)
+ *  - dangerous → 每次都弹(高风险,命令内容不可预测)
+ *
+ * 三层允许(优先级从高到低):
+ *  1. 永久允许(permanentAllow,跨会话持久化到 ~/.mocode/permissions.json)
+ *  2. 会话允许(approvedTools,本次进程内缓存)
+ *  3. 面板询问(promptIntervention,复用 ask_human UI)
+ *
+ * 复用 promptIntervention:统一 UI 面板,非 TTY 自动降级(第一项 = 允许)。
+ */
+/** 跨会话持久化允许列表路径 */
+const PERMISSIONS_PATH = path.join(os.homedir(), '.mocode', 'permissions.json');
+/** 永久允许:跨会话持久化(用户选了"以后不再询问此工具") */
+let permanentAllow = new Set();
+let permanentLoaded = false;
+/** 会话级缓存:confirm 级工具批准后,后续调用不再弹 */
+const approvedTools = new Set();
+/** 从磁盘加载永久允许列表(首调时触发,之后用内存缓存;文件不存在/解析失败返空集合) */
+function loadPermanent() {
+    if (permanentLoaded)
+        return permanentAllow;
+    permanentLoaded = true;
+    try {
+        const raw = fs.readFileSync(PERMISSIONS_PATH, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && Array.isArray(parsed.allowForever)) {
+            permanentAllow = new Set(parsed.allowForever.filter((x) => typeof x === 'string'));
+        }
+    }
+    catch {
+        // 文件不存在 / 解析失败 → 空集合(不阻断,用户首次使用或配置损坏均安全降级)
+    }
+    return permanentAllow;
+}
+/** 写入永久允许列表(覆盖写;失败静默,下次启动丢失但不阻断当前会话) */
+function savePermanent() {
+    try {
+        fs.mkdirSync(path.dirname(PERMISSIONS_PATH), { recursive: true });
+        fs.writeFileSync(PERMISSIONS_PATH, JSON.stringify({ allowForever: Array.from(permanentAllow) }, null, 2) + '\n', 'utf8');
+    }
+    catch {
+        // 写失败静默(与 updateConfigKey 一致:UI 偏好路径,不阻断 REPL)
+    }
+}
+/** 从 Tool 解析 risk,缺省返 'safe'(只读工具无需标注)。 */
+export function getToolRisk(tool) {
+    return tool.risk ?? 'safe';
+}
+/** 参数摘要:提取关键参数供确认面板展示(path / command 等)。 */
+function summarizeArgs(tool, args) {
+    const lines = [];
+    if (typeof args.path === 'string')
+        lines.push(`路径: ${args.path}`);
+    if (typeof args.command === 'string')
+        lines.push(`命令: ${args.command}`);
+    if (typeof args.prompt === 'string') {
+        const preview = String(args.prompt).slice(0, 100);
+        lines.push(`任务: ${preview}${String(args.prompt).length > 100 ? '…' : ''}`);
+    }
+    return lines.length > 0 ? lines.join('\n') : '(无参数)';
+}
+/**
+ * 检查权限:safe 直接放行;confirm/dangerous 弹面板让用户确认。
+ *
+ * 返回 'allow' = 放行, 'deny' = 拒绝(不执行,也不记回滚快照)。
+ * 非 TTY 环境(promptIntervention 内部处理):自动选第一项(允许)并打 stderr 日志,不阻塞。
+ */
+export async function checkPermission(tool, args, signal) {
+    // 总开关关闭 → 全部放行(零行为变化,向后兼容)
+    if (!config.permissionEnabled)
+        return 'allow';
+    const risk = getToolRisk(tool);
+    if (risk === 'safe')
+        return 'allow';
+    // 永久允许(跨会话):命中则放行,不弹面板
+    if (loadPermanent().has(tool.name))
+        return 'allow';
+    // 会话允许(confirm 级):同进程内缓存,命中则放行
+    if (risk === 'confirm' && approvedTools.has(tool.name))
+        return 'allow';
+    // 构建确认面板
+    const isDangerous = risk === 'dangerous';
+    const title = isDangerous
+        ? `⚠ 高风险操作: ${tool.name}`
+        : `确认执行: ${tool.name}`;
+    const detail = summarizeArgs(tool, args) + (isDangerous ? '\n\n⚠ 此操作可能产生不可逆副作用,请谨慎确认。' : '');
+    // 选项统一结构:dangerous 也提供"以后不再询问"(用户明确授权即尊重,即使 run_command)
+    const options = isDangerous
+        ? ['确认执行', '以后不再询问此工具', '拒绝']
+        : ['允许', '本次会话始终允许此工具', '以后不再询问此工具', '拒绝'];
+    // 弹面板(阻塞直到用户选择;signal 中断时 promptIntervention 内部处理)
+    const result = await promptIntervention({
+        type: 'choice',
+        title,
+        detail,
+        options,
+        allowCustom: false,
+    });
+    // 用户取消(Esc / Ctrl+C)→ 拒绝
+    if (result.action === 'cancelled')
+        return 'deny';
+    // 解析选择
+    const value = result.value ?? '';
+    if (value === '拒绝')
+        return 'deny';
+    // 永久允许:写入磁盘 + 加入内存集合(跨会话生效)
+    if (value === '以后不再询问此工具') {
+        permanentAllow.add(tool.name);
+        savePermanent();
+        return 'allow';
+    }
+    // 会话允许(confirm 级):加入内存缓存,本次进程内不再弹
+    if (!isDangerous && value === '本次会话始终允许此工具') {
+        approvedTools.add(tool.name);
+    }
+    return 'allow';
+}
+/** 移除工具的永久允许(撤销"以后不再询问"授权)。供未来 `/permissions` 管理命令使用。 */
+export function revokePermanentAllow(toolName) {
+    if (permanentAllow.has(toolName)) {
+        permanentAllow.delete(toolName);
+        savePermanent();
+    }
+}
+/** 列出所有永久允许的工具名(供未来 `/permissions` 管理命令使用)。 */
+export function listPermanentAllow() {
+    return Array.from(loadPermanent());
+}

package/dist/pet/bridge.d.ts

@@ -0,0 +1,73 @@
+import WebSocket from 'ws';
+import type { PetState, PetStateMeta, SkinListMessage } from './protocol.js';
+/** 默认端口;MOCODE_PET_PORT 环境变量覆盖(design.md 默认假设)。 */
+export declare const DEFAULT_PET_PORT = 47821;
+/**
+ * 探测本地端口是否已有 WS server 监听并可完成一次 WS 握手。
+ * 前置条件:port 为合法端口号。
+ * 后置条件:返回 true 表示 <timeoutMs> 内握手成功(桌宠已在跑);false 表示超时/拒绝连接。
+ * 无副作用(探测用的临时连接在返回前关闭)。
+ */
+export declare function probePort(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * 拉起独立 Electron 桌宠进程(detached,不随当前 mocode 进程退出而杀死)。
+ * 前置条件:调用方已确认端口未被占用(避免重复 spawn)。
+ * 后置条件:
+ *   - resolve() 表示 spawn 系统调用成功发出(不代表桌宠已可连接,调用方需配合 connectWithBackoff)。
+ *   - reject(err) 表示可执行文件不可解析(mocode-pet-app 未安装/安装失败)——降级路径。
+ */
+export declare function spawnPetProcess(): Promise<void>;
+/**
+ * 按退避序列重试连接,直到成功或耗尽重试次数。
+ * 前置条件:retryDelaysMs 非空、单调(本设计取 [200,400,800,1600,3200])。
+ * 后置条件:
+ *   - resolve(ws) 表示某次尝试内 probePort/connect 成功。
+ *   - reject(err) 表示所有尝试均失败,err 汇总最后一次失败原因。
+ * 循环不变量:每次尝试前 attempts < retryDelaysMs.length;每次失败后 attempts 严格 +1。
+ */
+export declare function connectWithBackoff(port: number, retryDelaysMs?: number[]): Promise<WebSocket>;
+/**
+ * 发送一次状态消息(经节流:与上次发送状态相同则跳过)。
+ * 前置条件:无(未连接时静默 no-op,不抛错、不阻塞 agent 主循环)。
+ * 后置条件:若 state !== lastSentState,构造并发送一条合法 StateMessage;否则无副作用。
+ */
+export declare function sendState(state: PetState, meta?: PetStateMeta): void;
+/** 当前是否已建立活跃连接。 */
+export declare function isConnected(): boolean;
+/** 主动断开连接(best-effort 发 bye 后 close code=1000)。 */
+export declare function disconnect(): void;
+/**
+ * 请求桌宠进程整体退出(方案C:CLI 侧退出入口;托盘图标是桌面侧的另一入口,见 packages/pet-app/src/main.ts)。
+ * 不要求本连接是活跃连接——任何已连接的 mocode 进程都可以关闭桌宠。
+ * 前置条件:当前进程已建立连接(未连接则先尝试探测端口直连,再发 shutdown)。
+ * 后置条件:发送 shutdown 消息后主动断开本地连接;不等待桌宠进程确认退出(best-effort,不阻塞 REPL)。
+ */
+export declare function killPetProcess(): Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+/**
+ * 请求当前可用皮肤列表(供 /pet skin 菜单展示)。
+ * 前置条件:当前进程已建立连接(未连接则先尝试探测端口直连;若桌宠未运行则失败)。
+ * 后置条件:resolve 桌宠回复的 SkinListMessage;超时(2s 内无回复)reject。
+ */
+export declare function listSkins(): Promise<SkinListMessage>;
+/**
+ * 请求桌宠切换皮肤(选宠物)。
+ * 前置条件:当前进程已建立连接(未连接则静默 no-op,与 sendState 的降级策略一致)。
+ * 后置条件:已连接时发送 set_skin 消息;未连接时不抛错、无副作用。
+ */
+export declare function setSkin(skinId: string): void;
+/**
+ * /pet 命令入口。
+ * 前置条件:REPL 主循环已初始化(不要求 agent 正在运行)。
+ * 后置条件:
+ *   - 若调用前无活跃连接:调用后 either 已建立连接(connected=true)
+ *     或已尝试 spawn+重试全部失败(connected=false,附错误原因)。
+ *   - 若调用前有活跃连接:调用后连接已关闭(connected=false)。
+ * 不抛异常(所有失败路径转为返回值,供 REPL 渲染提示行)。
+ */
+export declare function togglePet(): Promise<{
+    connected: boolean;
+    reason?: string;
+}>;

package/dist/pet/protocol.d.ts

@@ -0,0 +1,83 @@
+/** 桌宠状态集合。子 agent(task 工具派生)永不产生这些状态——只在主 agent hooks 组装处广播。 */
+export type PetState = 'idle' | 'thinking' | 'speaking' | 'tool_call' | 'done' | 'aborted' | 'error' | 'waiting_human';
+/** 全部合法状态值(供运行时校验,如 Set 成员判断)。 */
+export declare const PET_STATES: readonly PetState[];
+/** 状态负载:随 state 消息携带的可选元数据。 */
+export interface PetStateMeta {
+    /** 仅 tool_call 状态携带:当前调用的工具名(如 "write_file")。 */
+    toolName?: string;
+    /** 仅 error 状态携带:简短错误摘要(截断,不含敏感路径/密钥)。 */
+    errorMessage?: string;
+}
+/** 每个 mocode 进程生成一次,进程存活期间稳定。 */
+export type ClientId = string;
+export interface HelloMessage {
+    type: 'hello';
+    clientId: ClientId;
+    pid: number;
+    cwd: string;
+    ts: number;
+}
+export interface StateMessage {
+    type: 'state';
+    clientId: ClientId;
+    state: PetState;
+    meta?: PetStateMeta;
+    ts: number;
+}
+export interface PingMessage {
+    type: 'ping';
+    ts: number;
+}
+export interface ByeMessage {
+    type: 'bye';
+    clientId: ClientId;
+    ts: number;
+}
+/** 主动请求桌宠进程整体退出(与 disconnect 不同:disconnect 只断开本连接,shutdown 让桌宠 app.quit()）。
+ *  不要求发送方是当前活跃连接——任何已连接的 mocode 进程都可以关闭桌宠(见 Requirement 补充:关闭桌宠)。 */
+export interface ShutdownMessage {
+    type: 'shutdown';
+    clientId: ClientId;
+    ts: number;
+}
+/** 请求切换桌宠皮肤(选宠物)。skinId 对应 assets/pets/manifest.json 里的 id,空字符串/'default' 表示恢复默认 mascot.svg。 */
+export interface SetSkinMessage {
+    type: 'set_skin';
+    clientId: ClientId;
+    skinId: string;
+    ts: number;
+}
+/** 请求当前可用皮肤列表(触发 server 回复 SkinListMessage)。 */
+export interface ListSkinsMessage {
+    type: 'list_skins';
+    ts: number;
+}
+export type ClientMessage = HelloMessage | StateMessage | PingMessage | ByeMessage | ShutdownMessage | SetSkinMessage | ListSkinsMessage;
+export interface WelcomeMessage {
+    type: 'welcome';
+    isActive: boolean;
+    ts: number;
+}
+export interface PongMessage {
+    type: 'pong';
+    ts: number;
+}
+/** 皮肤列表(供 /pet skin 菜单展示)。桌宠进程回复,ids 对应 assets/pets/ 下的候选素材。 */
+export interface SkinListMessage {
+    type: 'skin_list';
+    skins: {
+        id: string;
+        name: string;
+    }[];
+    currentSkinId: string;
+    ts: number;
+}
+export type ServerMessage = WelcomeMessage | PongMessage | SkinListMessage;
+/** 判断值是否为合法 PetState(供消息校验,非法值丢弃不崩)。 */
+export declare function isValidPetState(v: unknown): v is PetState;
+/** 校验并解析一条原始 JSON 字符串为 ClientMessage;失败(JSON 非法/缺字段/type 未知)返回 null。
+ *  永不抛错——调用方(bridge/server)据此静默丢弃畸形消息,不断开连接。 */
+export declare function parseClientMessage(raw: string): ClientMessage | null;
+/** 校验并解析一条原始 JSON 字符串为 ServerMessage;失败返回 null(同上,永不抛错)。 */
+export declare function parseServerMessage(raw: string): ServerMessage | null;

package/dist/pet/state.d.ts

@@ -0,0 +1,28 @@
+import type { AgentHooks } from '../agent/core.js';
+import type { PetState } from './protocol.js';
+import * as bridge from './bridge.js';
+/** AgentHooks 方法名(供 deriveState 的 event 参数类型与穷举测试)。 */
+export type AgentHookEventName = 'onStepStart' | 'onText' | 'onToolCall' | 'onToolStart' | 'onToolResult' | 'onDone' | 'onAbort' | 'onMaxSteps' | 'onChatDone' | 'onToolBatchEnd' | 'onNoReply';
+/** deriveState 的可选参数(按事件类型而异)。 */
+export interface DeriveStateArgs {
+    /** onToolCall / onToolStart 的工具名。 */
+    toolName?: string;
+    /** onToolResult 的输出(用于判断是否报错:以"错误"开头,参考 agent/index.ts writeToolResult)。 */
+    toolOutput?: string;
+}
+/**
+ * 纯函数:给定当前 hook 事件与其参数,推导下一个 PetState。
+ * 前置条件:event 是 AgentHooks 定义的方法名之一。
+ * 后置条件:返回值 ∈ PetState 枚举;对同一 (event, args) 输入,任意调用时刻返回值相同(确定性,可测)。
+ * 不依赖调用历史之外的隐藏状态——纯函数式转移表。
+ */
+export declare function deriveState(event: AgentHookEventName, args?: DeriveStateArgs): PetState;
+/**
+ * 把 AgentHooks 事件流映射为 PetState 变化并调用 bridge.sendState。
+ * 前置条件:传入的 sender 已存在(可能尚未连接,sendState 内部自行处理未连接情形——no-op)。
+ * 后置条件:返回的 AgentHooks 对象的每个方法都是纯粹的"状态推导 + 转发",
+ *   不修改 core.ts 的任何行为、不影响现有 TUI hooks 的调用结果。
+ */
+export declare function createPetHooks(sender?: {
+    sendState: typeof bridge.sendState;
+}): AgentHooks;

package/dist/plan/active.d.ts

@@ -0,0 +1,23 @@
+import type { Plan } from './store.js';
+export interface ActivePlanSnapshot {
+    id: string;
+    title: string;
+    status: Plan['status'];
+    done: number;
+    total: number;
+}
+type Listener = (snap: ActivePlanSnapshot | null) => void;
+/** 取当前活跃 plan(完整对象,工具用)。无 → null。 */
+export declare function getActivePlan(): Plan | null;
+/** 设活跃 plan。同一 id 重复设也走 listener(repl 借此刷 status 行——即使内容未变,显式刷新有助)。 */
+export declare function setActivePlan(plan: Plan | null): void;
+/** 清活跃 plan(plan finish/abandon 后由 repl/todolist 调)。 */
+export declare function clearActivePlan(): void;
+/** 注册活跃 plan 变更监听器。返注销函数(不常用,模式 listener 一次性常驻)。 */
+export declare function onActivePlanChange(cb: Listener): () => void;
+/** 是否有活跃 plan(in_progress 状态)。finished/abandoned 不算「活跃」。 */
+export declare function hasActivePlan(): boolean;
+/** 给 status 行用的极简摘要(避免调用方读 Plan 全字段)。无 → 空串。 */
+/** 状态行 chip 用的短摘要(无 ANSI 颜色,由 layout 上色)。maxWidth 默认 56,留 room 给右段。 */
+export declare function getActivePlanSummary(maxWidth?: number): string;
+export {};

package/dist/plan/index.d.ts

@@ -0,0 +1,13 @@
+export { type Plan, type PlanStep, type PlanStatus, type StepStatus, plansDir, archiveDir, planPath, ensurePlansDir, ensureArchiveDir, newPlanId, parsePlan, serializePlan, readPlan, writePlan, deletePlan, deletePlanAnywhere, updatePlan, listPlans, archivePlan, unarchivePlan, renderPlanForLLM, renderPlanChip, } from './store.js';
+export { type ActivePlanSnapshot, getActivePlan, setActivePlan, clearActivePlan, onActivePlanChange, hasActivePlan, getActivePlanSummary, } from './active.js';
+/**
+ * 拼给 systemPrompt 注入的活跃 plan 摘要段。
+ *  - 无活跃 plan → 空串(repl 直接跳过拼接,systemPrompt 长度不变)。
+ *  - 有 → 紧凑 markdown(目标 + 步骤 checkbox + 进度日志末 5 条),header + 内容。
+ *
+ * 触发:setActivePlan 后由 repl listener 调;也供 buildSystemMessage 直接同步取(repl 入口)。
+ * 上限:超 MAX_ACTIVE_PLAN_CHARS 截到尾部(罕见,plan 文件本身就小)。
+ */
+export declare function buildActivePlanSection(): string;
+/** 注入 systemPrompt 的活跃 plan 摘要上限(字符)。 */
+export declare const MAX_ACTIVE_PLAN_CHARS = 3000;

package/dist/plan/state.d.ts

@@ -0,0 +1,2 @@
+export type { ActivePlanSnapshot } from './active.js';
+export { getActivePlan, setActivePlan, clearActivePlan, onActivePlanChange, hasActivePlan, getActivePlanSummary, } from './active.js';

package/dist/plan/store.d.ts

@@ -0,0 +1,78 @@
+export type StepStatus = 'pending' | 'in_progress' | 'done' | 'skipped' | 'failed';
+export interface PlanStep {
+    /** 1-based 序号(在当前 plan 内稳定,即便中间 add_step 也不重用旧号——见 addStep)。 */
+    id: number;
+    title: string;
+    status: StepStatus;
+}
+export type PlanStatus = 'in_progress' | 'finished' | 'abandoned';
+export interface Plan {
+    id: string;
+    title: string;
+    status: PlanStatus;
+    created: string;
+    updated: string;
+    goal: string;
+    steps: PlanStep[];
+    /** 进度日志条目(时间戳 + 一行说明),append-only。 */
+    log: {
+        at: string;
+        text: string;
+    }[];
+}
+/** plans 目录:<sandboxRoot>/.mocode/plans/。无 sandboxRoot 退到 cwd(防御)。 */
+export declare function plansDir(): string;
+/** 归档目录:<root>/.mocode/plans/archive/。finish 自动归档、用户手动 unarchive 都走这里。 */
+export declare function archiveDir(): string;
+/** 单 plan 文件路径:<root>/.mocode/plans/<id>.md。可选 baseDir:默认 plans,也可指 archive。 */
+export declare function planPath(id: string, baseDir?: string): string;
+/** 确保 plans 目录存在(惰性,工具每次写前调)。 */
+export declare function ensurePlansDir(): void;
+/** 确保归档目录存在(惰性)。 */
+export declare function ensureArchiveDir(): void;
+/** 本地时间戳(无时区后缀),与 filename 的 YYYY-MM-DDTHH-mm-ss 风格一致。
+ *  例:2026-07-04T22:54:51.729(本地时,便于人对读 frontmatter / progress log,
+ *  且与同 plan id 文件名"2026-07-04T22-54-51"对应)。
+ *  不带 Z 后缀 → JS Date 解析会按本地时读(一致 round-trip);
+ *  反例:toISOString() 返 2026-07-04T14:54:51.729Z(UTC),跟用户当地差 8 小时,易误解。 */
+export declare function localIsoTimestamp(d?: Date): string;
+/** plan id:YYYY-MM-DDTHH-mm-ss-xxxxxx(本地时间,文件名安全)。xxxxxx = 4 字节随机 hex(防同秒并发撞)。 */
+export declare function newPlanId(now?: Date): string;
+/**
+ * 解析 plan 文件为 Plan 对象。失败(无 frontmatter / 段缺失 / 坏 checkbox)→ 退化:
+ *  - 无 frontmatter:把整文当 title 段
+ *  - 缺字段:空串 / 空数组
+ *  - 坏 checkbox:跳过该行,不污染好行
+ * 解析成功但 step id 缺序 / 重号:按出现顺序重排为 1..N(保稳定)。
+ */
+export declare function parsePlan(raw: string, fallbackId: string): Plan;
+/** 序列化为 markdown 文本。固定段序:frontmatter → 目标 → 步骤 → 进度日志。 */
+export declare function serializePlan(p: Plan): string;
+/** 读 plan 文件;不存在 → null,坏文件 → fallbackId 最小可用 Plan(不抛,工具契约)。
+ *  可选 baseDir:默认 plans,传 archiveDir() 可读归档。 */
+export declare function readPlan(id: string, baseDir?: string): Plan | null;
+/** 写 plan 文件(atomic:写 .tmp 再 rename)。返回是否成功。 */
+export declare function writePlan(p: Plan): boolean;
+/** 删 plan 文件;不存在静默 ok。可选 baseDir:默认 plans,传 archiveDir() 删归档。 */
+export declare function deletePlan(id: string, baseDir?: string): boolean;
+/**
+ * 原子读-改-写:读 → mutator 改 → 写。mutator 返回 false 视为"无改动",跳过写。
+ * mutator 抛错 → 写失败 → 返 null(不抛,工具契约)。
+ *
+ * mutator 同步:本 store 走同步 fs,mutator 必须同步(返 Promise 视为"无信号"——返原对象);
+ *  设计如此以避免把 fs API 改成 async(同步 fs 在 node 单 tick 原子,无需锁)。
+ */
+export declare function updatePlan(id: string, mutator: (p: Plan) => Plan | false): Plan | null;
+/** 列 plans 目录下所有 plan(按 updated 倒序,最新在前)。解析失败的跳过。
+ *  scope: 'active'(默认)=仅 plans/;'archived'=仅 archive/;'all'=合并(去重按 id)。 */
+export declare function listPlans(scope?: 'active' | 'archived' | 'all'): Plan[];
+/** 把 plans/<id>.md mv 到 plans/archive/<id>.md(atomic rename)。
+ *  源不存在 → false(已归档 / 删了 / 从未存在都算)。 */
+export declare function archivePlan(id: string): boolean;
+/** 把 plans/archive/<id>.md 还原到 plans/<id>.md。源不存在 → false。 */
+export declare function unarchivePlan(id: string): boolean;
+/** 任一处存在就都删(活跃 + 归档)。用于 todolist delete 不关心来源。 */
+export declare function deletePlanAnywhere(id: string): boolean;
+/** 把 Plan 渲成给 LLM 看的紧凑摘要(多行文本)。 */
+export declare function renderPlanForLLM(p: Plan): string;
+export declare function renderPlanChip(p: Plan | null, maxWidth?: number): string;