cortico-world-image-attach 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+- 首个版本:`image_attach`,把硬盘上的一张图片读成对话附件,回执给 `log:` 句柄。

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# cortico-world-image-attach
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Owner: `src/definition.ts`
+
+`image_attach` 读硬盘上的一张图片(png / jpg / jpeg / gif / webp,不超过 5 MB),把字节作为这次对话的
+附件交出去。回执正文写原路径与字节数;句柄是 Core 追加在后面的 `[blob log:… image/png 文件名]` 行。
+把那个 `log:` 句柄填进 `pet_say` 的 `images`,对话页就会出现这张图。
+
+图片字节进日志附件(`log:`),不写 Memory,也不复制原文件。要长期留在工作区,再让 bot 调 Persona 的
+`save_blob` 存成 `mem:`。
+
+## 装到哪
+
+这个目录就是包,放在哪里都行。Coopanion 便携版把扩展装在
+`<Coopanion>\data\extensions`;WebUI 的「从本机目录安装」会以链接方式把它放进去。
+
+## 怎么加载
+
+1. 打开 Coopanion 的 WebUI,进「扩展」页,「手动安装」选「从本机目录安装」,填这个目录的绝对路径
+   (例如 `D:\AI\Cortina-main\Cortina\state\packages\cortico-world-image-attach`)。
+2. 重启 Coopanion 进程。
+3. 在 World 总览里启用「本地图片递送」(配置 `worlds.image.enabled`)。它是新 World,默认关闭。
+
+命令行也可以:在 `<Coopanion>\data\extensions` 下 `corepack pnpm add <这个目录>`。WebUI 装完同样要重启。
+
+## 怎么确认加载成功
+
+- 扩展页卡片显示「已加载」,名称是「本地图片递送」。
+- World 总览里多一张「本地图片递送」卡,启用后工具表里出现 `image_attach`。
+- 对话里让桌宠调一次,回执里应有 `[blob log:…]` 行。
+
+## 怎么测
+
+1. 在对话页对桌宠说:「用 image_attach 读 `D:\图片\cat.png`,然后用 pet_say 把这张图发给我」。
+2. 工具回执应包含原路径、字节数和一行 `[blob log:… image/png cat.png]`。
+3. 桌宠调 `pet_say` 时,`images` 填回执里的那个 `log:` 句柄;对话页里看到图片就算成了。
+
+## 失败回执
+
+工具失败时返回可读的文本,并把这次调用标成失败,不抛异常:
+
+- `path 不能为空;给图片文件的绝对路径。`
+- `路径必须是绝对路径: cat.png`
+- `文件不存在: D:\…\nope.png`
+- `不是普通文件(可能是目录或设备): D:\…\folder.png`
+- `不支持的图片格式: .bmp。支持 png、jpg、jpeg、gif、webp。`
+- `文件太大: 6291456 字节,上限 5 MB(5242880 字节)。`
+- `读取失败: …`
+
+## 开发
+
+```bash
+corepack pnpm install
+pnpm typecheck && pnpm test
+```
+
+在 Cortico 检出根下重写自描述并校验:
+
+```bash
+pnpm describe:extension <这个目录>
+pnpm check:extension <这个目录>
+```
+
+契约版本是 world 6;`describe.json` 由 `describe:extension` 生成,工具或描述改了要重跑。

package/describe.json

@@ -0,0 +1,29 @@
+{
+  "tools": [
+    {
+      "name": "image_attach",
+      "description": "Attach one image file from the local disk to this conversation. Give its absolute path; the receipt carries the image as a [blob ...] line with a log: handle you can hand to image-sending tools. Accepts png, jpg, jpeg, gif and webp up to 5 MB.",
+      "parameters": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "description": "Absolute path of the image file on this machine."
+          }
+        },
+        "required": [
+          "path"
+        ]
+      },
+      "tags": [
+        "read"
+      ],
+      "summary": {
+        "zh": "读取硬盘上的一张图片,作为附件交给这次对话,回执给 log: 句柄。",
+        "en": "Reads one image file from disk into the conversation as an attachment and returns its log: handle."
+      }
+    }
+  ],
+  "events": []
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "cortico-world-image-attach",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Cortico World: 把电脑里任意一张图片发进对话，可以配合有搜图能力的扩展，将找到的图片直接发在对话里。",
+  "license": "MIT",
+  "keywords": [
+    "cortico-world",
+    "cortico"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@11.28.6",
+  "main": "./src/index.ts",
+  "cortico": {
+    "kind": "world",
+    "api": 6,
+    "displayName": "本地图片递送",
+    "tags": [
+      "unsafe"
+    ],
+    "describe": "describe.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "describe.json"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "cortico": "^0.2.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/src/config.ts

@@ -0,0 +1,8 @@
+/** config.json 的 worlds.image 段;这个 World 没有自己的旋钮,只有启用开关。 */
+export interface ImageConfigSection {
+  enabled: boolean;
+}
+
+export const IMAGE_DEFAULTS: ImageConfigSection = {
+  enabled: false,
+};

package/src/definition.ts

@@ -0,0 +1,20 @@
+import { describeTools, type WorldDefinition } from 'cortico/world.ts';
+import { IMAGE_DEFAULTS, type ImageConfigSection } from './config.ts';
+import { IMAGE_TOOL_DECLS, ImageWorld } from './world.ts';
+
+export const IMAGE: WorldDefinition<ImageConfigSection> = {
+  id: 'image',
+  label: 'Image',
+  defaults: () => ({ ...IMAGE_DEFAULTS }),
+  create: () => new ImageWorld(),
+  // 自描述:全部工具;这个 World 不推事件。
+  describe: {
+    tools: describeTools(IMAGE_TOOL_DECLS, {
+      image_attach: {
+        zh: '读取硬盘上的一张图片,作为附件交给这次对话,回执给 log: 句柄。',
+        en: 'Reads one image file from disk into the conversation as an attachment and returns its log: handle.',
+      },
+    }),
+    events: [],
+  },
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+/** 包入口:默认导出 `WorldDefinition`,加载器按 `cortico.kind === 'world'` 认它。 */
+import { IMAGE } from './definition.ts';
+
+export default IMAGE;
+export { IMAGE };
+export type { ImageConfigSection } from './config.ts';

package/src/world.ts

@@ -0,0 +1,88 @@
+/** `image_attach`:把硬盘上的一张图片读成这次对话的附件,回执给句柄。 */
+import { readFileSync, statSync } from 'node:fs';
+import { basename, extname, isAbsolute } from 'node:path';
+import type { ToolDef, ToolOutcome, World } from 'cortico/core/types.ts';
+
+/** 5 MiB;再大的图不值得随上下文走。 */
+const MAX_BYTES = 5 * 1024 * 1024;
+
+const MIME_BY_EXTENSION: Record<string, string> = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+};
+
+/** 全部工具的声明;定义里的 describe 与 `tools()` 都取它。 */
+export const IMAGE_TOOL_DECLS: ReadonlyArray<Omit<ToolDef, 'handler'>> = [
+  {
+    name: 'image_attach',
+    description: 'Attach one image file from the local disk to this conversation. Give its absolute path; '
+      + 'the receipt carries the image as a [blob ...] line with a log: handle you can hand to image-sending tools. '
+      + 'Accepts png, jpg, jpeg, gif and webp up to 5 MB.',
+    tags: ['read'],
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        path: { type: 'string', description: 'Absolute path of the image file on this machine.' },
+      },
+      required: ['path'],
+    },
+  },
+];
+
+export class ImageWorld implements World {
+  readonly id = 'image';
+
+  /** 这个 World 不进环境提示词。 */
+  envPromptVars(): null {
+    return null;
+  }
+
+  tools(): ToolDef[] {
+    return [{ ...IMAGE_TOOL_DECLS[0], handler: async (args) => this.attach(args) }];
+  }
+
+  async start(): Promise<void> {}
+
+  async stop(): Promise<void> {}
+
+  private attach(args: Record<string, unknown>): ToolOutcome {
+    const path = String(args.path ?? '').trim();
+    if (!path) return fail('path 不能为空;给图片文件的绝对路径。');
+    if (!isAbsolute(path)) return fail(`路径必须是绝对路径: ${path}`);
+
+    let size: number;
+    try {
+      const stat = statSync(path);
+      if (!stat.isFile()) return fail(`不是普通文件(可能是目录或设备): ${path}`);
+      size = stat.size;
+    } catch {
+      return fail(`文件不存在: ${path}`);
+    }
+
+    const extension = extname(path).toLowerCase();
+    const mime = MIME_BY_EXTENSION[extension];
+    if (!mime) return fail(`不支持的图片格式: ${extension || '(无扩展名)'}。支持 png、jpg、jpeg、gif、webp。`);
+    if (size > MAX_BYTES) return fail(`文件太大: ${size} 字节,上限 5 MB(${MAX_BYTES} 字节)。`);
+
+    let bytes: Uint8Array;
+    try {
+      bytes = readFileSync(path);
+    } catch (err) {
+      return fail(`读取失败: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    const name = basename(path);
+    return {
+      text: `已读取 ${path}(${bytes.byteLength} 字节,${mime})。句柄在下一行 [blob …] 里,把它填进 pet_say 的 images。`,
+      blobs: [{ bytes, mime, name, fallbackText: `原路径 ${path}` }],
+    };
+  }
+}
+
+function fail(text: string): ToolOutcome {
+  return { text, failed: true };
+}