@shareai-lab/kode-sdk 2.7.1 → 2.7.3

package/README.md

@@ -142,9 +142,12 @@ See [docs/en/guides/architecture.md](./docs/en/guides/architecture.md) for detai
 | **Guides** | |
 | [Events](./docs/en/guides/events.md) | Three-channel event system |
 | [Tools](./docs/en/guides/tools.md) | Built-in tools & custom tools |
+| [Skills](./docs/en/guides/skills.md) | Skills system for reusable prompts |
 | [Providers](./docs/en/guides/providers.md) | Model provider configuration |
 | [Database](./docs/en/guides/database.md) | SQLite/PostgreSQL persistence |
 | [Resume & Fork](./docs/en/guides/resume-fork.md) | Crash recovery & branching |
+| **Project** | |
+| [Contribution Guide](./docs/en/contribution.md) | How to contribute |
 | **Reference** | |
 | [API Reference](./docs/en/reference/api.md) | Complete API documentation |
 | [Examples](./docs/en/examples/playbooks.md) | All examples explained |

package/README.zh-CN.md

@@ -102,9 +102,12 @@ npm run example:room               # 多Agent协作
 | **使用指南** | |
 | [事件系统](./docs/zh-CN/guides/events.md) | 三通道事件系统 |
 | [工具系统](./docs/zh-CN/guides/tools.md) | 内置工具与自定义工具 |
+| [Skills 系统](./docs/zh-CN/guides/skills.md) | Skills 可复用提示词系统 |
 | [Provider 配置](./docs/zh-CN/guides/providers.md) | 模型 Provider 配置 |
 | [数据库存储](./docs/zh-CN/guides/database.md) | SQLite/PostgreSQL 持久化 |
 | [恢复与分叉](./docs/zh-CN/guides/resume-fork.md) | 崩溃恢复与分支 |
+| **项目** | |
+| [贡献指南](./docs/zh-CN/contribution.md) | 提交 PR 的要求与流程 |
 | **参考** | |
 | [API 参考](./docs/zh-CN/reference/api.md) | 完整 API 文档 |
 | [示例集](./docs/zh-CN/examples/playbooks.md) | 所有示例详解 |

package/dist/core/agent/breakpoint-manager.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BreakpointManager = void 0;
+class BreakpointManager {
+    constructor(onChange) {
+        this.onChange = onChange;
+        this.current = 'READY';
+        this.history = [];
+    }
+    getCurrent() {
+        return this.current;
+    }
+    getHistory() {
+        return this.history;
+    }
+    set(state, note) {
+        if (this.current === state)
+            return;
+        const entry = {
+            state,
+            timestamp: Date.now(),
+            note,
+        };
+        const previous = this.current;
+        this.current = state;
+        this.history.push(entry);
+        if (this.onChange) {
+            this.onChange(previous, state, entry);
+        }
+    }
+    reset(state = 'READY') {
+        this.current = state;
+        this.history = [];
+    }
+}
+exports.BreakpointManager = BreakpointManager;

package/dist/core/agent/message-queue.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MessageQueue = void 0;
+const logger_1 = require("../../utils/logger");
+const errors_1 = require("../errors");
+class MessageQueue {
+    constructor(options) {
+        this.options = options;
+        this.pending = [];
+    }
+    send(content, opts = {}) {
+        const kind = opts.kind ?? 'user';
+        const isText = typeof content === 'string';
+        if (kind === 'reminder' && !isText) {
+            throw new errors_1.MultimodalValidationError('Reminder messages must be plain text.');
+        }
+        const payload = isText
+            ? kind === 'reminder'
+                ? this.options.wrapReminder(content, opts.reminder)
+                : content
+            : content;
+        const id = `msg-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        this.pending.push({
+            message: {
+                role: 'user',
+                content: isText ? [{ type: 'text', text: payload }] : payload,
+            },
+            kind,
+            metadata: { id, ...(opts.metadata || {}) },
+        });
+        if (kind === 'user') {
+            this.options.ensureProcessing();
+        }
+        return id;
+    }
+    async flush() {
+        if (this.pending.length === 0)
+            return;
+        const queue = this.pending;
+        try {
+            // 先添加到消息历史
+            for (const entry of queue) {
+                this.options.addMessage(entry.message, entry.kind);
+            }
+            // 持久化成功后才清空队列
+            await this.options.persist();
+            // 成功：从队列中移除已处理的消息
+            this.pending = this.pending.filter(item => !queue.includes(item));
+        }
+        catch (err) {
+            // 失败：保留队列，下次重试
+            logger_1.logger.error('[MessageQueue] Flush failed, messages retained:', err);
+            throw err; // 重新抛出让调用者知道失败
+        }
+    }
+}
+exports.MessageQueue = MessageQueue;

package/dist/core/agent/permission-manager.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionManager = void 0;
+const permission_modes_1 = require("../permission-modes");
+class PermissionManager {
+    constructor(config, descriptors) {
+        this.config = config;
+        this.descriptors = descriptors;
+    }
+    evaluate(toolName) {
+        if (this.config.denyTools?.includes(toolName)) {
+            return 'deny';
+        }
+        if (this.config.allowTools && this.config.allowTools.length > 0 && !this.config.allowTools.includes(toolName)) {
+            return 'deny';
+        }
+        if (this.config.requireApprovalTools?.includes(toolName)) {
+            return 'ask';
+        }
+        const handler = permission_modes_1.permissionModes.get(this.config.mode || 'auto') || permission_modes_1.permissionModes.get('auto');
+        if (!handler) {
+            return 'allow';
+        }
+        const context = {
+            toolName,
+            descriptor: this.descriptors.get(toolName),
+            config: this.config,
+        };
+        return handler(context);
+    }
+}
+exports.PermissionManager = PermissionManager;

package/dist/core/agent/todo-manager.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TodoManager = void 0;
+class TodoManager {
+    constructor(opts) {
+        this.opts = opts;
+        this.stepsSinceReminder = 0;
+    }
+    get enabled() {
+        return !!this.opts.service && !!this.opts.config?.enabled;
+    }
+    list() {
+        return this.opts.service ? this.opts.service.list() : [];
+    }
+    async setTodos(todos) {
+        if (!this.opts.service)
+            throw new Error('Todo service not enabled for this agent');
+        const prev = this.opts.service.list();
+        await this.opts.service.setTodos(todos);
+        this.publishChange(prev, this.opts.service.list());
+    }
+    async update(todo) {
+        if (!this.opts.service)
+            throw new Error('Todo service not enabled for this agent');
+        const prev = this.opts.service.list();
+        await this.opts.service.update(todo);
+        this.publishChange(prev, this.opts.service.list());
+    }
+    async remove(id) {
+        if (!this.opts.service)
+            throw new Error('Todo service not enabled for this agent');
+        const prev = this.opts.service.list();
+        await this.opts.service.delete(id);
+        this.publishChange(prev, this.opts.service.list());
+    }
+    handleStartup() {
+        if (!this.enabled || !this.opts.config?.reminderOnStart)
+            return;
+        const todos = this.list().filter((todo) => todo.status !== 'completed');
+        if (todos.length === 0) {
+            this.sendEmptyReminder();
+        }
+        else {
+            this.sendReminder(todos, 'startup');
+        }
+    }
+    onStep() {
+        if (!this.enabled)
+            return;
+        if (!this.opts.config?.remindIntervalSteps)
+            return;
+        if (this.opts.config.remindIntervalSteps <= 0)
+            return;
+        this.stepsSinceReminder += 1;
+        if (this.stepsSinceReminder < this.opts.config.remindIntervalSteps)
+            return;
+        const todos = this.list().filter((todo) => todo.status !== 'completed');
+        if (todos.length === 0)
+            return;
+        this.sendReminder(todos, 'interval');
+    }
+    publishChange(previous, current) {
+        if (!this.opts.events)
+            return;
+        this.stepsSinceReminder = 0;
+        this.opts.events.emitMonitor({ channel: 'monitor', type: 'todo_changed', previous, current });
+        if (current.length === 0) {
+            this.sendEmptyReminder();
+        }
+    }
+    sendReminder(todos, reason) {
+        this.stepsSinceReminder = 0;
+        this.opts.events.emitMonitor({ channel: 'monitor', type: 'todo_reminder', todos, reason });
+        this.opts.remind(this.formatTodoReminder(todos), { category: 'todo', priority: 'medium' });
+    }
+    sendEmptyReminder() {
+        this.opts.remind('当前 todo 列表为空，如需跟踪任务请使用 todo_write 建立清单。', {
+            category: 'todo',
+            priority: 'low',
+        });
+    }
+    formatTodoReminder(todos) {
+        const bulletList = todos
+            .slice(0, 10)
+            .map((todo, index) => `${index + 1}. [${todo.status}] ${todo.title}`)
+            .join('\n');
+        const more = todos.length > 10 ? `\n… 还有 ${todos.length - 10} 项` : '';
+        return `Todo 列表仍有未完成项：\n${bulletList}${more}\n请结合 todo_write 及时更新进度，不要向用户直接提及本提醒。`;
+    }
+}
+exports.TodoManager = TodoManager;

package/dist/core/agent/tool-runner.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRunner = void 0;
+class ToolRunner {
+    constructor(concurrency) {
+        this.concurrency = concurrency;
+        this.active = 0;
+        this.queue = [];
+        if (!Number.isFinite(concurrency) || concurrency <= 0) {
+            throw new Error('ToolRunner requires a positive concurrency limit');
+        }
+    }
+    run(task) {
+        return new Promise((resolve, reject) => {
+            const execute = () => {
+                this.active += 1;
+                task()
+                    .then(resolve, reject)
+                    .finally(() => {
+                    this.active -= 1;
+                    this.flush();
+                });
+            };
+            if (this.active < this.concurrency) {
+                execute();
+            }
+            else {
+                this.queue.push(execute);
+            }
+        });
+    }
+    clear() {
+        this.queue.length = 0;
+    }
+    flush() {
+        if (this.queue.length === 0)
+            return;
+        if (this.active >= this.concurrency)
+            return;
+        const next = this.queue.shift();
+        if (next)
+            next();
+    }
+}
+exports.ToolRunner = ToolRunner;

package/dist/core/agent.d.ts

@@ -9,6 +9,7 @@ import { SandboxFactory } from '../infra/sandbox-factory';
 import { ModelProvider, ModelConfig } from '../infra/provider';
 import { ToolRegistry, ToolInstance, ToolDescriptor } from '../tools/registry';
 import { ContextManagerOptions } from './context-manager';
+import { ResumeError } from './errors';
 import { SendOptions as QueueSendOptions } from './agent/message-queue';
 export interface ModelFactory {
     (config: ModelConfig): ModelProvider;
@@ -180,6 +181,12 @@ export declare class Agent {
         strategy?: ResumeStrategy;
         overrides?: Partial<AgentConfig>;
     }): Promise<Agent>;
+    static resumeOrCreate(agentId: string, config: AgentConfig, deps: AgentDependencies, opts?: {
+        autoRun?: boolean;
+        strategy?: ResumeStrategy;
+        overrides?: Partial<AgentConfig>;
+        onCorrupted?: (agentId: string, error: ResumeError) => Promise<void> | void;
+    }): Promise<Agent>;
     private ensureProcessing;
     private runStep;
     private executeTools;