@zhin.js/plugin-calendar 0.0.0-stage → 0.1.1

package/lib/token-manager.js

@@ -0,0 +1,239 @@
+/**
+ * In-memory OAuth access-token cache with proactive refresh, single-flight,
+ * refresh-token rotation handling, and clear invalid_grant errors.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+/** Chat command that (re-)authorizes a provider; shown in user-facing errors. */
+export function authCommandFor(provider) {
+    return `calendar auth ${provider}`;
+}
+export class OAuthTokenError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "OAuthTokenError";
+        this.code = code;
+    }
+}
+const DEFAULT_SKEW_MS = 5 * 60 * 1000;
+export class OAuthTokenManager {
+    #provider;
+    #clientId;
+    #clientSecret;
+    #tenant;
+    #tokenFile;
+    #fetch;
+    #now;
+    #logger;
+    #skewMs;
+    #refreshToken;
+    #accessToken = "";
+    #expiresAt = 0;
+    #inflight;
+    #tokenStore;
+    #onAuthorizationLost;
+    #authorizationLostMessage = "";
+    constructor(options) {
+        if (!options.clientId.trim()) {
+            throw new OAuthTokenError("config", `${options.provider}: 缺少 client_id`);
+        }
+        if (options.provider === "google" && !options.clientSecret?.trim()) {
+            throw new OAuthTokenError("config", "google: 缺少 client_secret");
+        }
+        this.#provider = options.provider;
+        this.#clientId = options.clientId.trim();
+        this.#clientSecret = (options.clientSecret ?? "").trim();
+        this.#tenant = (options.tenant ?? "common").trim() || "common";
+        this.#tokenFile = (options.tokenFile ?? "").trim();
+        this.#fetch = options.fetchImpl ?? fetch;
+        this.#now = options.now ?? Date.now;
+        this.#logger = options.logger ?? {
+            warn: (message) => console.warn(message),
+        };
+        this.#skewMs = options.skewMs ?? DEFAULT_SKEW_MS;
+        this.#refreshToken = (options.initialRefreshToken ?? "").trim();
+        this.#tokenStore = options.tokenStore;
+        this.#onAuthorizationLost = options.onAuthorizationLost;
+    }
+    get provider() {
+        return this.#provider;
+    }
+    /** Whether a refresh token is available (stored or from config). */
+    get hasRefreshToken() {
+        return this.#refreshToken !== "";
+    }
+    /** Whether the last refresh attempt was rejected with invalid_grant. */
+    get authorizationLost() {
+        return this.#authorizationLostMessage !== "";
+    }
+    /**
+     * Loads persisted tokens: token_file overlay first, then the token store,
+     * which takes precedence over config/env because it is written by chat auth.
+     */
+    async hydrate() {
+        await this.hydrateFromFile();
+        if (!this.#tokenStore) {
+            return;
+        }
+        const storedRefreshToken = (await this.#tokenStore.load())?.trim() ?? "";
+        if (storedRefreshToken) {
+            this.#refreshToken = storedRefreshToken;
+        }
+    }
+    /** Replaces the refresh token after a successful chat authorization. */
+    setRefreshToken(refreshToken) {
+        this.#refreshToken = refreshToken.trim();
+        this.#accessToken = "";
+        this.#expiresAt = 0;
+        this.#authorizationLostMessage = "";
+    }
+    /** Forgets all tokens held in memory (used by `calendar logout`). */
+    clearTokens() {
+        this.setRefreshToken("");
+    }
+    /** Current refresh token (may change after Microsoft rotation). */
+    get refreshToken() {
+        return this.#refreshToken;
+    }
+    /** Load optional token file overlay (rotated refresh / cached access). */
+    async hydrateFromFile() {
+        if (!this.#tokenFile)
+            return;
+        try {
+            const raw = await readFile(this.#tokenFile, "utf8");
+            const data = JSON.parse(raw);
+            if (typeof data.refresh_token === "string" && data.refresh_token.trim()) {
+                this.#refreshToken = data.refresh_token.trim();
+            }
+            if (typeof data.access_token === "string" &&
+                data.access_token.trim() &&
+                typeof data.expires_at === "number" &&
+                data.expires_at > this.#now() + this.#skewMs) {
+                this.#accessToken = data.access_token.trim();
+                this.#expiresAt = data.expires_at;
+            }
+        }
+        catch (error) {
+            const err = error;
+            if (err.code !== "ENOENT") {
+                this.#logger.warn(`[calendar] 读取 token_file 失败：${this.#tokenFile}（${err.message}）`);
+            }
+        }
+    }
+    async getAccessToken() {
+        if (this.#accessToken && this.#now() < this.#expiresAt - this.#skewMs) {
+            return this.#accessToken;
+        }
+        return this.#refreshSingleFlight();
+    }
+    /** Bypass cache (e.g. after HTTP 401). Still single-flight. */
+    async forceRefresh() {
+        this.#expiresAt = 0;
+        this.#accessToken = "";
+        return this.#refreshSingleFlight();
+    }
+    #refreshSingleFlight() {
+        if (this.#inflight)
+            return this.#inflight;
+        this.#inflight = this.#refresh().finally(() => {
+            this.#inflight = undefined;
+        });
+        return this.#inflight;
+    }
+    async #refresh() {
+        if (this.#authorizationLostMessage) {
+            throw new OAuthTokenError("invalid_grant", this.#authorizationLostMessage);
+        }
+        if (!this.#refreshToken) {
+            throw new OAuthTokenError("not_authorized", `${this.#provider}: 日历尚未授权。请 master 在聊天中发送「${authCommandFor(this.#provider)}」完成授权。`);
+        }
+        const body = new URLSearchParams({
+            client_id: this.#clientId,
+            refresh_token: this.#refreshToken,
+            grant_type: "refresh_token",
+        });
+        if (this.#clientSecret)
+            body.set("client_secret", this.#clientSecret);
+        if (this.#provider === "microsoft") {
+            body.set("scope", "offline_access Calendars.ReadWrite User.Read");
+        }
+        const url = this.#provider === "google"
+            ? "https://oauth2.googleapis.com/token"
+            : `https://login.microsoftonline.com/${this.#tenant}/oauth2/v2.0/token`;
+        const response = await this.#fetch(url, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body,
+        });
+        const text = await response.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            data = {};
+        }
+        if (!response.ok) {
+            const errCode = String(data.error ?? "");
+            const errDesc = String(data.error_description ?? text.slice(0, 200));
+            if (errCode === "invalid_grant" || /invalid_grant/i.test(errDesc)) {
+                const message = `${this.#provider}: 日历授权已失效或被撤销（invalid_grant）。请 master 在聊天中发送「${authCommandFor(this.#provider)}」重新授权。详情：${errDesc}`;
+                this.#authorizationLostMessage = message;
+                await this.#notifyAuthorizationLost(message);
+                throw new OAuthTokenError("invalid_grant", message);
+            }
+            throw new OAuthTokenError(errCode || "http_error", `${this.#provider}: token 刷新失败 HTTP ${response.status}：${errDesc || response.statusText}`);
+        }
+        const accessToken = String(data.access_token ?? "");
+        if (!accessToken) {
+            throw new OAuthTokenError("response", `${this.#provider}: 刷新响应缺少 access_token`);
+        }
+        const expiresIn = Number(data.expires_in ?? 3600);
+        this.#accessToken = accessToken;
+        this.#expiresAt = this.#now() + Math.max(60, expiresIn) * 1000;
+        const rotated = typeof data.refresh_token === "string" ? data.refresh_token.trim() : "";
+        if (rotated && rotated !== this.#refreshToken) {
+            this.#refreshToken = rotated;
+            if (this.#tokenStore) {
+                await this.#tokenStore.save(rotated);
+                this.#logger.warn(`[calendar] ${this.#provider}: 提供方返回了新的 refresh_token，已写入插件数据库`);
+            }
+            else if (this.#tokenFile) {
+                await this.#persist();
+                this.#logger.warn(`[calendar] ${this.#provider}: 提供方返回了新的 refresh_token，已写入 token_file：${this.#tokenFile}`);
+            }
+            else {
+                this.#logger.warn(`[calendar] ${this.#provider}: 提供方返回了新的 refresh_token。请立刻更新环境变量中的 refresh_token（当前未配置 token_file，内存中的新值进程重启后会丢失）：\n${rotated}`);
+            }
+        }
+        else if (this.#tokenFile) {
+            await this.#persist();
+        }
+        return this.#accessToken;
+    }
+    async #notifyAuthorizationLost(message) {
+        if (!this.#onAuthorizationLost) {
+            return;
+        }
+        try {
+            await this.#onAuthorizationLost(this.#provider, message);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            this.#logger.warn(`[calendar] 授权失效通知发送失败：${reason}`);
+        }
+    }
+    async #persist() {
+        if (!this.#tokenFile)
+            return;
+        const payload = {
+            refresh_token: this.#refreshToken,
+            access_token: this.#accessToken || undefined,
+            expires_at: this.#expiresAt || undefined,
+        };
+        await mkdir(path.dirname(this.#tokenFile), { recursive: true });
+        await writeFile(this.#tokenFile, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+    }
+}
+//# sourceMappingURL=token-manager.js.map

package/lib/token-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.js","sourceRoot":"","sources":["../src/token-manager.ts"],"names":[],"mappings":"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"}

package/lib/tool-errors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Runs a calendar tool body and turns OAuth authorization failures into a
+ * readable reply (e.g. "请 master 发送 calendar auth google") instead of a crash.
+ */
+export declare function runCalendarTool(operation: () => Promise<string>): Promise<string>;
+//# sourceMappingURL=tool-errors.d.ts.map

package/lib/tool-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-errors.d.ts","sourceRoot":"","sources":["../src/tool-errors.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAC/B,OAAO,CAAC,MAAM,CAAC,CASjB"}

package/lib/tool-errors.js

@@ -0,0 +1,17 @@
+import { OAuthTokenError } from "./token-manager.js";
+/**
+ * Runs a calendar tool body and turns OAuth authorization failures into a
+ * readable reply (e.g. "请 master 发送 calendar auth google") instead of a crash.
+ */
+export async function runCalendarTool(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof OAuthTokenError) {
+            return error.message;
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=tool-errors.js.map

package/lib/tool-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-errors.js","sourceRoot":"","sources":["../src/tool-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,SAAgC;IAEhC,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,EAAE,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;YACrC,OAAO,KAAK,CAAC,OAAO,CAAC;QACvB,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/lib/types.d.ts

@@ -0,0 +1,28 @@
+/** Calendar event as returned by every provider. */
+export interface CalendarEvent {
+    readonly id: string;
+    readonly title: string;
+    readonly start: string;
+    readonly end: string;
+    readonly location?: string;
+    readonly description?: string;
+    readonly all_day?: boolean;
+}
+export interface CreateEventInput {
+    readonly title: string;
+    readonly start: Date;
+    readonly end: Date;
+    readonly location?: string;
+    readonly description?: string;
+    readonly all_day?: boolean;
+}
+export interface FreeSlot {
+    readonly start: string;
+    readonly end: string;
+}
+export interface CalendarProvider {
+    readonly name: string;
+    listEvents(from: Date, to: Date, signal?: AbortSignal): Promise<CalendarEvent[]>;
+    createEvent(input: CreateEventInput, signal?: AbortSignal): Promise<CalendarEvent>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;IACnB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,UAAU,CACR,IAAI,EAAE,IAAI,EACV,EAAE,EAAE,IAAI,EACR,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC5B,WAAW,CACT,KAAK,EAAE,gBAAgB,EACvB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CAAC;CAC3B"}

package/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,115 @@
 {
   "name": "@zhin.js/plugin-calendar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "CalDAV / Google / Microsoft calendar tools for Zhin Agent",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "bin": {
+    "zhin-calendar-auth": "./lib/cli/auth.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "plugin.js",
+    "commands",
+    "src",
+    "lib",
+    "skills",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "zhin",
+    "zhin.js",
+    "plugin",
+    "calendar",
+    "caldav"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "lc-cn",
+    "email": "admin@liucl.cn",
+    "url": "https://github.com/lc-cn"
+  },
+  "dependencies": {
+    "@zhin.js/host-http": "1.1.4",
+    "@zhin.js/im-contract": "1.1.3"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3",
+    "@zhin.js/command": "1.1.5",
+    "@zhin.js/skill": "1.1.4",
+    "@zhin.js/tool": "1.1.4",
+    "zhin.js": "1.1.7"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0",
+    "@zhin.js/skill": "^1.1.4",
+    "@zhin.js/command": "^1.1.5",
+    "@zhin.js/tool": "^1.1.4",
+    "zhin.js": "^1.1.7"
+  },
+  "peerDependenciesMeta": {
+    "@zhin.js/command": {
+      "optional": true
+    },
+    "@zhin.js/skill": {
+      "optional": true
+    },
+    "@zhin.js/tool": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "plugins/utils/calendar"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "zhin": {
+    "protocol": 1,
+    "type": "plugin",
+    "entry": "./plugin.js",
+    "engine": "^1.0.0",
+    "runtime": "trusted",
+    "features": [
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/tool",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
+      }
+    ],
+    "plugins": []
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "tsc -p tsconfig.check.json",
+    "test": "vitest run --root ../../.. plugins/utils/calendar/tests",
+    "auth": "tsx src/cli/auth.ts"
+  }
 }

package/plugin.js

@@ -0,0 +1,72 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { databaseHostToken, definePlugin, outboundHostToken, } from "zhin.js";
+import { httpHostToken } from "@zhin.js/host-http";
+import { assertCalendarTimezone, calendarConfig, createCalendarProvider, createOAuthTokenManagers, } from "./lib/index.js";
+import { buildRedirectUri, CalendarAuthService, DEFAULT_OAUTH_CALLBACK_PATH, localOriginFromAddress, } from "./lib/chat-auth.js";
+import { CalendarCredentialStore, } from "./lib/credential-store.js";
+import { registerOAuthCallbackRoute } from "./lib/http-callback.js";
+import { calendarRuntimeToken } from "./lib/runtime.js";
+export default definePlugin({
+    name: "calendar",
+    config: calendarConfig,
+    metadata: { displayName: "日历" },
+    setup(context) {
+        const config = context.config.get();
+        assertCalendarTimezone(config.timezone);
+        const resources = context.resources;
+        const credentials = resources.has(databaseHostToken)
+            ? new CalendarCredentialStore(resources.use(databaseHostToken)
+                .state)
+            : undefined;
+        const outbound = resources.has(outboundHostToken)
+            ? resources.use(outboundHostToken)
+            : undefined;
+        const http = resources.has(httpHostToken)
+            ? resources.use(httpHostToken)
+            : undefined;
+        const notify = outbound?.sendTarget
+            ? async (target, text) => {
+                await outbound.sendTarget(target, text);
+            }
+            : undefined;
+        const callbackPath = config.oauth_callback_path?.trim() || DEFAULT_OAUTH_CALLBACK_PATH;
+        const resolveRedirectUri = () => {
+            const configuredBase = config.oauth_redirect_base_url?.trim() ?? "";
+            if (configuredBase) {
+                return buildRedirectUri(configuredBase, callbackPath);
+            }
+            const address = http?.address;
+            if (!address) {
+                return undefined;
+            }
+            return buildRedirectUri(localOriginFromAddress(address), callbackPath);
+        };
+        let auth;
+        const managers = createOAuthTokenManagers(config, {
+            credentials,
+            onAuthorizationLost: (provider, message) => auth?.notifyAuthorizationLost(provider, message),
+        });
+        auth = new CalendarAuthService({
+            config,
+            managers,
+            credentials,
+            notify,
+            resolveRedirectUri,
+        });
+        const provider = createCalendarProvider(config, { managers });
+        context.resources.provide(calendarRuntimeToken, {
+            config,
+            provider,
+            auth: auth,
+        });
+        if (config.provider !== "none" && !provider) {
+            console.warn("[calendar] provider 已配置但凭据为空，日历工具将不可用；Google/Microsoft 请先配置 client_id，再在聊天中发送 calendar auth <provider>");
+        }
+        const releaseRoute = http
+            ? registerOAuthCallbackRoute(http, callbackPath, (searchParams) => auth.handleCallback(searchParams))
+            : undefined;
+        return () => {
+            releaseRoute?.();
+        };
+    },
+});

package/skills/calendar-scheduling/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: calendar-scheduling
+description: >-
+  查询日历空闲、列出事件并在确认后创建日程。默认时区来自插件配置（默认 Asia/Manila）。
+  Use when the user mentions meetings, availability, calendar, 约时间, 日程.
+keywords:
+  - 日历
+  - 日程
+  - calendar
+  - 约时间
+  - free time
+  - 有空
+tags:
+  - calendar
+tools:
+  - list_events
+  - find_free_time
+  - create_event
+---
+
+# 日历安排
+
+## 何时使用
+
+- 查某段时间有没有会、找空档、创建日程
+
+## 工作流
+
+1. 先确认时区（配置项 `timezone`，默认 `Asia/Manila`）和日期范围。
+2. `list_events` 看已有安排；需要空档时用 `find_free_time`（尊重 `work_day_start` / `work_day_end`）。
+3. **创建前复述**：标题、开始、结束、地点、时区，等用户明确同意后再调 `create_event`（仅 master，且始终要求批准）。
+4. 若日历未启用，告诉用户去配置 CalDAV / Google / Microsoft，不要假装已创建。
+
+## 注意
+
+- 没有时区偏移的时间按配置时区解释。
+- Google / Microsoft 使用 refresh_token（环境变量）；用 `pnpm --filter @zhin.js/plugin-calendar auth google|microsoft` 获取。access token 仅内存缓存。
+- 操作哪本日历由配置 `calendar_id` 决定（Google 默认 `primary`，Outlook 默认账户主日历）。

package/skills/calendar-scheduling/tools/create_event/index.js

@@ -0,0 +1,38 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from "@zhin.js/tool";
+import { z } from "zod";
+import { calendarRuntimeToken } from "../../../../lib/runtime.js";
+import { runCalendarTool } from "../../../../lib/tool-errors.js";
+import { parseDateTimeInZone } from "../../../../lib/time.js";
+export default defineAgentTool({
+    description: "Create a calendar event. Always confirm title, start, end and timezone with the user first.",
+    requiresApproval: "always",
+    permissions: ["role(master)"],
+    tags: ["calendar"],
+    keywords: ["创建日程", "约时间", "create event"],
+    inputSchema: z.object({
+        title: z.string().min(1).max(200),
+        start: z.string().describe("Start YYYY-MM-DDTHH:mm"),
+        end: z.string().describe("End YYYY-MM-DDTHH:mm"),
+        location: z.string().max(200).optional(),
+        description: z.string().max(2000).optional(),
+        all_day: z.boolean().optional(),
+    }),
+    async execute(input, context) {
+        return runCalendarTool(async () => {
+            const runtime = context.use(calendarRuntimeToken);
+            if (!runtime.provider)
+                return "日历未启用：请先配置 provider 与凭据";
+            const timezone = runtime.config.timezone;
+            const event = await runtime.provider.createEvent({
+                title: input.title,
+                start: parseDateTimeInZone(input.start, timezone),
+                end: parseDateTimeInZone(input.end, timezone),
+                location: input.location,
+                description: input.description,
+                all_day: input.all_day,
+            }, context.signal);
+            return `已创建事件 [${event.id}]\n${event.title}\n${event.start} → ${event.end}（${timezone}）`;
+        });
+    },
+});

package/skills/calendar-scheduling/tools/create_event/index.ts

@@ -0,0 +1,41 @@
+import { defineAgentTool } from "@zhin.js/tool";
+import { z } from "zod";
+import { calendarRuntimeToken } from "../../../../src/runtime.js";
+import { runCalendarTool } from "../../../../src/tool-errors.js";
+import { parseDateTimeInZone } from "../../../../src/time.js";
+
+export default defineAgentTool({
+  description:
+    "Create a calendar event. Always confirm title, start, end and timezone with the user first.",
+  requiresApproval: "always",
+  permissions: ["role(master)"],
+  tags: ["calendar"],
+  keywords: ["创建日程", "约时间", "create event"],
+  inputSchema: z.object({
+    title: z.string().min(1).max(200),
+    start: z.string().describe("Start YYYY-MM-DDTHH:mm"),
+    end: z.string().describe("End YYYY-MM-DDTHH:mm"),
+    location: z.string().max(200).optional(),
+    description: z.string().max(2000).optional(),
+    all_day: z.boolean().optional(),
+  }),
+  async execute(input, context) {
+    return runCalendarTool(async () => {
+      const runtime = context.use(calendarRuntimeToken);
+      if (!runtime.provider) return "日历未启用：请先配置 provider 与凭据";
+      const timezone = runtime.config.timezone;
+      const event = await runtime.provider.createEvent(
+        {
+          title: input.title,
+          start: parseDateTimeInZone(input.start, timezone),
+          end: parseDateTimeInZone(input.end, timezone),
+          location: input.location,
+          description: input.description,
+          all_day: input.all_day,
+        },
+        context.signal
+      );
+      return `已创建事件 [${event.id}]\n${event.title}\n${event.start} → ${event.end}（${timezone}）`;
+    });
+  },
+});