cortico-provider-humanize 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.0
+
+**装上就生效，不用再新建端点。**
+
+- 你现在用的端点（Coo、Responses 兼容等）直接带上活人感：装好两个扩展、重启一次就行，不用到「模型」页新建、填写、切换。
+- 卸载也不用先切端点：卸掉重启后，端点就是原来的端点，桌宠照常说话。
+- 0.1.0 时手动新建的「活人感」端点照样能用，模块改名为「活人感（旧版端点，不用再新建）」。建议切回原来的端点；以后要卸载本包，必须先切回去。
+- 和 World 之间的桥升到第 3 版：要和 `cortico-world-humanize` 0.2.0 一起用。版本对不上时原样转发，不出错。
+
 ## 0.1.0
 
 第一个公开版本。

package/README.md

@@ -2,26 +2,32 @@
 
 和 [活人感（cortico-world-humanize）](https://github.com/abbabanana/cortico-world-humanize) 搭配使用的 Cortico provider。
 
-它包住 Coopanion 自带的 Coo 连接。你对桌宠说话时，它先等活人感 World 想好桌宠此刻的心情，再把心情和你的话一起发给模型。主模型这一轮就带着心事开口，不用先调用 `humanize_feel` 再多跑一轮。
+装上以后，你现在用的模型端点就会带上活人感：你对桌宠说话时，先等活人感 World 想好桌宠此刻的心情，再把心情和你的话一起发给模型。主模型这一轮就带着心事开口，不用先调用 `humanize_feel` 再多跑一轮。
 
 - **World 开着**：等心事（最多 5 秒），追加在这一批事件的末尾，然后转发。
-- **World 关着，或者那边出了任何错**：原样转发，就是一条普通的 Coo 连接。最坏就是这一轮没有心事，桌宠照常说话。
-- 思考档、价格、模型列表、配置项全部沿用 Coo 的。
+- **World 关着，或者那边出了任何错**：原样转发，和没装一样。最坏就是这一轮没有心事，桌宠照常说话。
+- 端点的地址、Key、模型、思考档、价格都不动，还是你原来配的。
 - 只改发出去的那一次请求，会话记录不动。
 
 ## 安装
 
-1. 先装好并打开 [活人感 World](https://github.com/abbabanana/cortico-world-humanize)。
-2. Coopanion 的「扩展」页搜 `cortico-provider-humanize`，安装，重启。
-3. 「模型」页新建一个端点：模块选「活人感（包住 Coo 连接）」，地址、Key、模型、思考档照你现在用的那个填（比如 DeepSeek 的 `https://api.deepseek.com`、`deepseek-flash`）。
-4. 把当前端点切到这个新端点。
-5. 活人感会提醒你系统前缀要刷新：在 World 页把「活人感」关掉再打开一次。
+1. Coopanion 的「扩展」页搜「活人感」，把 `cortico-world-humanize` 和 `cortico-provider-humanize` 都装上。
+2. 重启 Coopanion。
+3. World 页打开「活人感」。如果它已经开着，提示「系统前缀需要刷新」时，把它关掉再打开一次。
 
-之后在活人感的「最近 20 轮记录」里看到「经 provider 注入」，就说明生效了。想换回去，把当前端点切回原来那个即可。
+不用到「模型」页做任何设置。在活人感的「最近 20 轮记录」里看到「经 provider 注入」，就说明生效了。
+
+> 不装这个 provider，只装 World 也能用，只是桌宠每次要先调用 `humanize_feel`，多跑一轮。
 
 ## 卸载
 
-**先在「模型」页把当前端点切回原来那个**，再在「扩展」页卸掉这个包，然后重启。端点还指着它就卸掉，Coopanion 找不到这个模块，桌宠会说不了话。
+「扩展」页卸掉，重启。端点还是原来的端点，不用先做别的。
+
+**例外**：如果你用 0.1.0 时在「模型」页新建过「活人感」端点（模块叫「活人感（旧版端点，不用再新建）」），并且当前端点还是它，要**先把当前端点切回原来那个**再卸载，不然 Coopanion 找不到这个模块，桌宠会说不了话。
+
+## 从 0.1.0 升级
+
+升级后原来的「活人感」端点照样能用。建议在「模型」页切回你原来的端点（比如 `deepseek`），然后可以删掉那个「活人感」端点，以后卸载就不用担心了。切换后在 World 页把活人感关开一次。
 
 ## 为什么不做推理预填充
 
@@ -29,15 +35,15 @@ DeepSeek 的前缀续写（`/beta`）不允许和工具调用一起用，而桌
 
 ## 市场标签说明
 
-- `requires-extension`：要和活人感 World 一起用才有作用，单独装就是一条普通的 Coo 连接。
+- `requires-extension`：要和活人感 World 一起用才有作用，单独装就是原样转发。
 - `experimental`：还在测试，只在少数环境里验证过（Windows、DeepSeek）。
 
 ## 许可证
 
-AGPL-3.0-or-later。它在运行时包住 Coopanion 自带的 Coo 连接模块（`cortico-provider-coo`，AGPL-3.0-or-later），所以用同样的许可证。
+AGPL-3.0-or-later。它在运行时包住 Coopanion 自带的端点模块（包括 `cortico-provider-coo`，AGPL-3.0-or-later），所以用同样的许可证。
 
 ---
 
 ## English
 
-**Humanize provider** pairs with the [Humanize World](https://github.com/abbabanana/cortico-world-humanize). It wraps Coopanion's own Coo connection and, when the person speaks, waits for the World to write the pet's inner thought, then sends it along with the person's words, so the main model answers with it in a single round. With the World off, or on any error on the World's side, it forwards requests unchanged. Switch the active endpoint back before uninstalling it. Licensed under AGPL-3.0-or-later, the same as the Coo connection it wraps.
+**Humanize provider** pairs with the [Humanize World](https://github.com/abbabanana/cortico-world-humanize). Install both and restart; there is nothing to set up. Your current model endpoint then waits for the World to write the pet's inner thought whenever the person speaks, and sends it along with their words, so the main model answers with it in a single round. With the World off, or on any error on the World's side, requests pass through unchanged. Uninstalling needs no preparation, unless you still use an endpoint created with the 0.1.0 "Humanize" module: switch back to your original endpoint first. Licensed under AGPL-3.0-or-later, the same as the Coo connection it wraps.

package/describe.json

@@ -14,8 +14,8 @@
       "text",
       "image"
     ],
-    "title": "活人感（包住 Coo 连接）",
-    "description": "和「活人感」World 搭配：你对桌宠说话时，先等 World 想好桌宠的心情，再连同你的话一起发给模型。World 关着时就是普通的 Coo 连接。",
+    "title": "活人感（旧版端点，不用再新建）",
+    "description": "0.1.0 时要手动新建的端点类型，留着给已经这么配过的人。现在装上活人感 provider，你原来的端点就自动带上活人感，不用新建这种端点。",
     "reasoningTiers": [
       {
         "id": "off",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "cortico-provider-humanize",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
-  "description": "Cortico provider for Coopanion: wraps the app's own Coo connection and holds each reply until the Humanize World has written the pet's inner thought, then sends it along with the person's words",
+  "description": "Cortico provider for Coopanion: once installed, your existing model endpoint waits for the Humanize World's inner thought and sends it along with the person's words. No endpoint to create or switch",
   "author": "abbabanana",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -19,15 +19,15 @@
   "cortico": {
     "kind": "provider",
     "api": 6,
-    "displayName": "活人感（包住 Coo 连接）",
+    "displayName": "活人感 provider",
     "locales": {
       "zh": {
-        "displayName": "活人感（包住 Coo 连接）",
-        "description": "和「活人感」World 搭配：你对桌宠说话时，先等 World 想好桌宠的心情，再连同你的话一起发给模型，省掉 humanize_feel 那一轮。World 关着时就是普通的 Coo 连接。"
+        "displayName": "活人感 provider",
+        "description": "「活人感」的加速搭档：让桌宠的心事和你的话一起发给模型，桌宠一轮就开口。必须先装「活人感」，装上重启即可，不用任何设置。\n\n**两个扩展怎么配合**\n\n- **活人感**（World，必装）：负责想心事、查 AI 固定句式。单独装就能用。\n- **活人感 provider**（就是本扩展，可选）：把心事直接放进发给模型的请求里，省掉桌宠先调工具读心事的那一轮，回复更快。\n- 只装本扩展、不装「活人感」，没有任何作用。\n\n**怎么用**\n\n1. 在扩展页把「活人感」和本扩展都装上。\n2. 重启 Coopanion。\n3. 到 World 页打开「活人感」。如果它本来就开着，按提示把它关掉再打开一次。\n\n**不用去「模型」页做任何事。** 你现在用的模型端点会自动带上活人感，地址、Key、模型都不变。活人感关着时，请求原样发出，和没装一样。\n\n**怎么确认生效**：活人感「提示词」页签里的「最近 20 轮记录」出现「经 provider 注入」。\n\n**卸载**：扩展页卸掉，重启即可。只有一种例外：用 0.1.0 时在「模型」页手动新建过「活人感」端点，而且现在还在用它，要先切回原来的端点再卸载，不然桌宠会说不了话。"
       },
       "en": {
-        "displayName": "Humanize (wraps the Coo connection)",
-        "description": "Pairs with the Humanize World: each time you speak to the pet, waits for the World to write the pet's inner thought and sends it along with your words, saving the humanize_feel round. With the World off it is a plain Coo connection."
+        "displayName": "Humanize provider",
+        "description": "A speed-up companion for Humanize: sends the pet's inner thought along with your words, so the pet answers in one round. Requires the Humanize World. Install and restart; nothing to set up.\n\n**How the two extensions fit together**\n\n- **Humanize** (World, required): writes the inner thought and checks stock AI sentence patterns. Works on its own.\n- **Humanize provider** (this one, optional): puts the thought straight into the request sent to the model, saving the round where the pet first calls a tool to read it.\n- This extension alone does nothing.\n\n**Getting started**\n\n1. Install both Humanize and this extension on the Extensions page.\n2. Restart Coopanion.\n3. Turn on Humanize on the World page. If it was already on, turn it off and on once when prompted.\n\n**Nothing to do on the Models page.** Your current model endpoint picks it up automatically; address, key and model stay as they are. With Humanize off, requests go out unchanged.\n\n**Uninstall**: remove it on the Extensions page and restart. One exception: if you created a \"Humanize\" endpoint by hand under 0.1.0 and still use it, switch back to your original endpoint first."
       }
     },
     "tags": ["requires-extension", "experimental"],

package/src/bridge.ts

@@ -1,9 +1,13 @@
 /**
  * 与 cortico-world-humanize/src/bridge.ts 约定的同一座桥（那边是定义方，这里只读）。
  * World 没启用时 globalThis 上没有它，provider 就原样转发。
+ *
+ * 反方向还有一块牌子（PROVIDER_KEY）：provider 加载时挂上，告诉 World「我装着，包住了哪些模块」，
+ * World 据此判断当前端点是不是走 provider 模式。
  */
 export const BRIDGE_KEY = Symbol.for('cortico-humanize.bridge');
-export const BRIDGE_VERSION = 2;
+export const PROVIDER_KEY = Symbol.for('cortico-humanize.provider');
+export const BRIDGE_VERSION = 3;
 
 export interface MainContext {
   instructions: string;
@@ -17,6 +21,12 @@ export interface HumanizeBridge {
   touch(): void;
 }
 
+export interface ProviderMarker {
+  version: typeof BRIDGE_VERSION;
+  /** 这种端点模块（端点配置里的 kind）是不是被活人感包着。 */
+  wraps(kind: string): boolean;
+}
+
 /** 当前挂着的桥；没有或版本对不上返回 null。 */
 export function bridge(): HumanizeBridge | null {
   const b = (globalThis as Record<symbol, unknown>)[BRIDGE_KEY] as HumanizeBridge | undefined;

package/src/index.ts

@@ -1,5 +1,11 @@
 /**
- * 活人感 provider:包住 Coopanion 自己的 Coo 连接（`coo` 模块，从框架的注册表现取，不按路径 import）。
+ * 活人感 provider。
+ *
+ * 装上就生效：加载时把已注册的每个端点模块（Coo、Responses 兼容……）的 `create` 包一层
+ * (见 wrap.ts)，你现在用的端点直接带上活人感，不用新建端点、不用切换。卸掉重启就恢复原样。
+ *
+ * 另外保留一个 `humanize` 模块（0.1.0 时要手动新建的那种端点），已经这么配过的人不用改；
+ * 它包住 Coopanion 自己的 Coo 连接（`coo` 模块，从框架的注册表现取，不按路径 import）。
  *
  * 每次请求：上下文最后一项是刚投递进来的事件帧时，问「活人感」World 要这批事件引出的心事
  * (连同主模型这次的系统前缀和最近上下文，让副 API 知道主模型知道的一切，不管记忆存在哪)，
@@ -15,6 +21,7 @@ import type { GenerateOptions, Generation, ResponseClient } from 'cortico/core/g
 import type { Request } from 'cortico/protocol/open-responses/index.ts';
 import { bridge } from './bridge.ts';
 import { capped, contextWithInner, inputWithInner, mainContext, newestFrame } from './inject.ts';
+import { wrapAll } from './wrap.ts';
 
 export const HUMANIZE_PROVIDER_ID = 'humanize';
 const WRAPPED = 'coo';
@@ -24,8 +31,8 @@ const CAP_MS = 5_000;
 /** 记住最近这么多帧的心事，之后的请求照样补上，前缀才稳定。 */
 const KEEP = 200;
 
-const TITLE = '活人感（包住 Coo 连接）';
-const DESCRIPTION = '和「活人感」World 搭配：你对桌宠说话时，先等 World 想好桌宠的心情，再连同你的话一起发给模型。World 关着时就是普通的 Coo 连接。';
+const TITLE = '活人感（旧版端点，不用再新建）';
+const DESCRIPTION = '0.1.0 时要手动新建的端点类型，留着给已经这么配过的人。现在装上活人感 provider，你原来的端点就自动带上活人感，不用新建这种端点。';
 
 /** 被包住的模块：Coo,没有就内建的 Responses 兼容模块。 */
 function wrapped(): ProviderModule {
@@ -133,9 +140,17 @@ export const HUMANIZE_PROVIDER: ProviderModule = {
     }))) as ProviderModule['config'];
   },
   create(name, entry, host): ProviderInstance {
-    const instance = wrapped().create(name, entry, host);
-    return { ...instance, client: new HumanizeClient(instance.client) };
+    // 被包住的 Coo 自己已经被 wrapAll 包过时，不再套第二层
+    return withHumanize(wrapped().create(name, entry, host));
   },
 } as ProviderModule;
 
+/** 给一个端点实例套上活人感；已经套过就原样返回。 */
+export function withHumanize(instance: ProviderInstance): ProviderInstance {
+  if (instance.client instanceof HumanizeClient) return instance;
+  return { ...instance, client: new HumanizeClient(instance.client) };
+}
+
+wrapAll(HUMANIZE_PROVIDER_ID, withHumanize);
+
 export default HUMANIZE_PROVIDER;

package/src/wrap.ts

@@ -0,0 +1,62 @@
+/**
+ * 不用另建端点：装上就把已注册的每个 provider 模块的 `create` 包一层，你现在用的端点直接带上
+ * 活人感。World 没启用（桥不在）时，包着的这层原样转发，和没装一样。
+ *
+ * 扩展的 provider 模块（比如 Coo）可能在本包之后才注册，所以除了包现有的，还接住注册表数组
+ * 之后的 `push`(`registerProviderModules` 就地往这个数组里加，不换引用)。
+ *
+ * 卸掉本包重启后，这层包装自然就没了，端点还是原来的端点，不会说不了话。
+ */
+import { providerModules } from 'cortico/providers/registry.ts';
+import type { ProviderModule } from 'cortico/providers/base.ts';
+import { BRIDGE_VERSION, PROVIDER_KEY, type ProviderMarker } from './bridge.ts';
+
+const WRAPPED = Symbol.for('cortico-humanize.wrapped');
+const PUSH_HOOKED = Symbol.for('cortico-humanize.push-hooked');
+
+type Wrappable = ProviderModule & { [WRAPPED]?: true };
+
+/** 包住一个模块的 create;已经包过、或者是活人感自己的旧模块就跳过。成功返回 true。 */
+function wrapModule(module: Wrappable, skip: string, wrapClient: (instance: ReturnType<ProviderModule['create']>) => ReturnType<ProviderModule['create']>): boolean {
+  if (!module || module.id === skip) return false;
+  if (module[WRAPPED]) return true;
+  const original = module.create;
+  if (typeof original !== 'function') return false;
+  try {
+    const create: ProviderModule['create'] = function (this: unknown, name, entry, host) {
+      return wrapClient(original.call(this ?? module, name, entry, host));
+    };
+    module.create = create;
+    module[WRAPPED] = true;
+    return module.create === create;
+  } catch {
+    // 冻结的对象改不了：这个模块就不带活人感，照常工作
+    return false;
+  }
+}
+
+/** 已经包住的模块 id。 */
+const wrappedKinds = new Set<string>();
+
+export function wrapAll(skip: string, wrapClient: (instance: ReturnType<ProviderModule['create']>) => ReturnType<ProviderModule['create']>): void {
+  const list = providerModules as ProviderModule[] & { [PUSH_HOOKED]?: true };
+  for (const module of list) if (wrapModule(module, skip, wrapClient)) wrappedKinds.add(module.id);
+  if (!list[PUSH_HOOKED]) {
+    try {
+      const push = list.push;
+      Object.defineProperty(list, 'push', {
+        configurable: true, writable: true, enumerable: false,
+        value(this: ProviderModule[], ...items: ProviderModule[]) {
+          for (const module of items) if (wrapModule(module, skip, wrapClient)) wrappedKinds.add(module.id);
+          return push.apply(this, items);
+        },
+      });
+      Object.defineProperty(list, PUSH_HOOKED, { value: true });
+    } catch { /* 接不住就只包现有的 */ }
+  }
+  const marker: ProviderMarker = {
+    version: BRIDGE_VERSION,
+    wraps: (kind) => kind === skip || wrappedKinds.has(kind),
+  };
+  (globalThis as Record<symbol, unknown>)[PROVIDER_KEY] = marker;
+}