dsh-pighub 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 positer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# dsh-pighub
 
-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.
+**PigHub（猪猪库调研项目）的 DeepSeek Harness 插件——当前是 0.0.1 占位版。**
+
+占位版只做三件事：占住 npm 包名 `dsh-pighub`、用一个最小 bundle 证明 DSH 装配链是对的、注册一个只读工具 `pighub_about` 让「装了且能调用」当场可验。
+它**不联网、不下载、不缓存、不内嵌任何猪图或猪名数据**。
+
+## 为什么先发布占位版
+
+npm 包名只有**发布**才锁定，仓库、README、issue 都不能占位。而 `dsh-pighub` 目前在 registry 上无人占用（`npm view dsh-pighub` → 404），所以先发一个诚实的最小包把名字钉住，再谈功能。
+真实功能的门槛不是代码，是**数据来源**：上游 PigHub 的图片与文案没有任何数据许可（GitHub `NOASSERTION`，按「保留全部权利」理解），把数据打进公开 npm 包就是再分发。占位版因此选择「零数据」。
+
+## 安装
+
+```sh
+dsh plugin --profile web add dsh-pighub     # 官方装配入口（写 profile 的 bundles，重启生效）
+```
+
+或从源码目录装（未发布前的等价路径）：
+
+```sh
+dsh plugin --profile web add ./dsh-pighub
+```
+
+装好后工具表里会多出 `pighub_about`，它返回本插件的版本、阶段、上游署名与数据许可立场。
+
+## 结构与契约
+
+```text
+dsh-pighub/
+├── package.json        # dsh.bundle.patch → ./cordis.patch.yml（bundle 声明的唯一入口）
+├── cordis.patch.yml    # 一行 insert：id: dsh-pighub, name: dsh-pighub
+├── lib/index.js        # export name / inject / apply；注册 pighub_about
+├── test/smoke.mjs      # 离线冒烟：模拟宿主 ctx，断言导出/注册/回收/工具输出
+├── docs/DSH-PLUGIN-PUBLIC-FORM.md   # 调研：DSH 插件的公开形式与发布通道
+├── README.md
+└── LICENSE
+```
+
+DSH 插件的公共形态只有一条主链：**npm 包 + `package.json` 的 `dsh.bundle.patch` + 一张补丁层 + 一个 ESM 入口**。完整调研（官方与社区一手来源、字段逐项核对、三种分发通道、以及本包为什么这样写）见 [docs/DSH-PLUGIN-PUBLIC-FORM.md](./docs/DSH-PLUGIN-PUBLIC-FORM.md)。
+
+## 验证
+
+```sh
+npm test             # = node test/smoke.mjs，12 项断言；同时是 prepublishOnly
+npm pack --dry-run   # 看发布内容（应只含 lib / cordis.patch.yml / README / LICENSE / test）
+```
+
+冒烟测试不启动 DSH：它按宿主的用法调用一次 `apply(ctx)`，断言只注册了 `pighub_about`、注册被 `ctx.effect` 包住（可回收）、工具输出是稳定 JSON、且代码里的版本号与 `package.json` 一致。
+
+## Roadmap（都未实现）
+
+1. **先定数据来源**：自建数据（自制猪图/自写文案）或取得上游书面授权；二者之外不做数据类工具。
+2. 之后才谈工具面：随机猪图、按名检索、今日猪猪。
+3. 若要出图，再谈是否加 `dsh.client` 前端半（设置卡片 / 图片面板）——声明 `dsh.client` 后要单独构建浏览器产物（`lib/client.js`），占位版刻意不带。
+
+## 许可
+
+- **本插件代码**：MIT（见 [LICENSE](./LICENSE)）。
+- **上游 PigHub 数据**：未声明许可；本包不包含、不再分发任何上游素材。MIT 只覆盖这里的插件代码，不覆盖任何猪图或猪名文案。
+
+## 状态
+
+- 版本：0.0.1 占位版，唯一工具 `pighub_about`（只读自述）
+- 数据：无。网络：无。
+- 项目主目录：[../README.md](../README.md)（PigHub 调研档案）

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-pighub 的 bundle 层：只插一行。
+#
+# 这一行是「已安装」的全部含义——Loader 读 package.json 的 dsh.bundle.patch，
+# 把这里的内容追加到 profile 的装配链末尾，于是 name 指向的包被 import，
+# 它的 apply(ctx) 才被执行。行 id 独立于包名，删包时按 id 回滚。
+#
+# name 必须是**包名**（Node 解析），不能写成源码相对路径。
+- insert:
+    - id: dsh-pighub
+      name: dsh-pighub

package/lib/index.js

@@ -0,0 +1,76 @@
+/**
+ * dsh-pighub — 猪猪库 PigHub 的 DeepSeek Harness 插件（0.0.1 占位版）。
+ *
+ * 这个版本只做三件事，且只做这三件：
+ *
+ *   1. 占住 npm 包名 `dsh-pighub`（名字只有发布才锁定）；
+ *   2. 用一个最小 bundle 证明装配链是对的（package.json 的 dsh.bundle.patch
+ *      → cordis.patch.yml 的一行 insert → 本文件的 apply）；
+ *   3. 注册一个只读工具 `pighub_about`，让「插件已装、能调用」可被当场验证。
+ *
+ * 它**不**做：不联网、不下载、不缓存、不内嵌任何猪图或猪名数据。上游 PigHub
+ * 的图片与文案没有任何数据许可（GitHub NOASSERTION → 默认保留全部权利），
+ * 把数据塞进一个公开 npm 包就是再分发，不是这个占位版有权做的事。真实能力的
+ * 设计见 README 的 roadmap，落地前必须先解决数据来源与许可。
+ *
+ * 契约（与宿主 loader 对齐，参考同机在跑的生产插件）：
+ *   - `export const name`   —— Loader 行的身份；
+ *   - `export const inject` —— 声明依赖的服务，这里只需要 tools；
+ *   - `export function apply(ctx)` —— 注册能力的唯一入口。
+ *
+ * 资源注册一律包在 `ctx.effect` 里：宿主热重载/卸载时靠它回收，否则工具会
+ * 变成僵尸残留在工具表里（同生态插件踩过的坑）。
+ */
+
+/** 与 package.json 的 name 必须一致；test/smoke.mjs 会断言两者相同。 */
+export const name = 'dsh-pighub';
+
+/** 只需要工具表；本版本不碰 LLM、会话、web 路由、文件系统。 */
+export const inject = ['tools'];
+
+/** 与 package.json 的 version 必须一致；test/smoke.mjs 会断言两者相同。 */
+const VERSION = '0.0.1';
+
+/**
+ * `pighub_about` 的回答是一条**自述**，不是数据查询：它描述的正是本插件此刻
+ * 的状态与立场，所以永远不需要网络，也不会因为上游下架而说谎。
+ *
+ * 冻结成常量，是因为它必须逐字段可预测——调用者拿它做健康检查与署名核对。
+ */
+const ABOUT = Object.freeze({
+  ok: true,
+  plugin: name,
+  version: VERSION,
+  stage: 'placeholder',
+  purpose: '预留包名 + 验证 bundle 装配 + 提供一个可调用的只读自述工具',
+  upstream: {
+    project: 'PigHub',
+    what: 'QQ 猪猪生态的开源数据调研项目（1,361 张图索引快照，2026-11-12）',
+    dataLicense: '上游未声明数据许可（NOASSERTION，按保留全部权利理解）',
+    redistributed: false,
+  },
+  bundledData: null,
+  tools: ['pighub_about'],
+  roadmap: [
+    '确定合法数据来源（自建 / 上游书面授权），再谈工具面',
+    '候选工具：随机猪图、按名检索、今日猪猪——都取决于数据来源能否落地',
+  ],
+  notice: '占位版不联网、不读写本地数据、无副作用；真实能力尚未实现。',
+});
+
+/**
+ * @param {any} ctx 宿主 Cordis 上下文：需要 `tools.register` 与 `effect`。
+ */
+export function apply(ctx) {
+  ctx.effect(
+    () =>
+      ctx.tools.register({
+        name: 'pighub_about',
+        description:
+          '读取 dsh-pighub 占位版的自述：版本 / 阶段 / 上游署名 / 数据许可立场；不联网、不读数据集、无副作用。 Read what the dsh-pighub placeholder is: version, stage, upstream attribution, data-licence position. No network, no dataset, no side effects.',
+        parameters: { type: 'object', properties: {}, additionalProperties: false },
+        execute: async () => ABOUT,
+      }),
+    'pighub-about-tool',
+  );
+}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "dsh-pighub",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "猪猪库 PigHub 的 DeepSeek Harness 插件——占位版（0.0.1）：预留包名、验证 bundle 装配、注册一个只读的 pighub_about 工具；不内嵌、不下载、不缓存任何猪图。",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE",
+    "test"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek",
+    "cordis",
+    "pighub",
+    "pig",
+    "dataset"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs",
+    "prepublishOnly": "node test/smoke.mjs"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "positer"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/",
+    "tag": "latest"
+  }
+}

package/test/smoke.mjs

@@ -0,0 +1,93 @@
+/**
+ * 离线冒烟测试：不启动 DSH，直接按宿主的用法调用一次 apply。
+ *
+ * 它验证的是「装配契约」而不是「功能」——占位版的功能就是那句自述：
+ *
+ *   1. 导出齐全（name / inject / apply），且 name 与 package.json 一致；
+ *   2. apply 之后工具表里确实多了 pighub_about，且只有它一个；
+ *   3. 注册被包在 ctx.effect 里（effect 返回的 disposer 能回收）；
+ *   4. execute 的返回是一个稳定的 JSON 对象，参数 schema 封闭。
+ *
+ * 任何一条不成立就非零退出——prepublishOnly 跑的就是它，坏包发不出去。
+ */
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const here = new URL('.', import.meta.url);
+const pkg = JSON.parse(readFileSync(new URL('../package.json', here), 'utf8'));
+const plugin = await import(new URL('../lib/index.js', here).href);
+
+let passed = 0;
+const check = (label, fn) => {
+  fn();
+  passed += 1;
+  console.log('PASS  ' + label);
+};
+
+// —— 1. 导出契约 ——
+check('导出 name / inject / apply', () => {
+  assert.equal(typeof plugin.name, 'string');
+  assert.ok(Array.isArray(plugin.inject));
+  assert.equal(typeof plugin.apply, 'function');
+});
+check('name 与 package.json 的 name 一致', () => assert.equal(plugin.name, pkg.name));
+check('inject 只声明 tools', () => assert.deepEqual(plugin.inject, ['tools']));
+check('package.json 声明了 bundle 补丁', () =>
+  assert.equal(pkg.dsh?.bundle?.patch, './cordis.patch.yml'));
+check('package.json 导出 cordis.patch.yml', () =>
+  assert.equal(pkg.exports?.['./cordis.patch.yml'], './cordis.patch.yml'));
+
+// —— 2. 模拟宿主上下文 ——
+const registered = new Map();
+const disposers = [];
+const ctx = {
+  effect(fn, label) {
+    const dispose = fn();
+    disposers.push({ label, dispose });
+    return dispose;
+  },
+  tools: {
+    register(definition) {
+      assert.ok(!registered.has(definition.name), '重复注册: ' + definition.name);
+      registered.set(definition.name, definition);
+      return () => registered.delete(definition.name);
+    },
+  },
+};
+
+plugin.apply(ctx);
+
+check('apply 后注册了且仅注册了 pighub_about', () =>
+  assert.deepEqual([...registered.keys()], ['pighub_about']));
+check('注册被包在 ctx.effect 里（可回收）', () => {
+  assert.equal(disposers.length, 1);
+  assert.equal(disposers[0].label, 'pighub-about-tool');
+});
+
+// —— 3. 工具定义与调用 ——
+const tool = registered.get('pighub_about');
+check('参数 schema 是封闭的空对象', () => {
+  assert.equal(tool.parameters.type, 'object');
+  assert.deepEqual(tool.parameters.properties, {});
+  assert.equal(tool.parameters.additionalProperties, false);
+});
+check('工具描述非空', () => assert.ok(tool.description.length > 20));
+
+const answer = await tool.execute({}, {});
+check('execute 返回冻结的自述对象', () => {
+  assert.equal(answer.ok, true);
+  assert.equal(answer.plugin, pkg.name);
+  assert.equal(answer.version, pkg.version, '代码版本与 package.json 不一致');
+  assert.equal(answer.stage, 'placeholder');
+  assert.deepEqual(answer.tools, ['pighub_about']);
+  assert.equal(answer.bundledData, null);
+});
+check('自述可无损 JSON 往返', () => assert.deepEqual(JSON.parse(JSON.stringify(answer)), answer));
+
+// —— 4. 回收 ——
+disposers[0].dispose();
+check('disposer 之后工具表清空', () => assert.equal(registered.size, 0));
+
+console.log('\n' + passed + ' PASS / 0 FAIL  —  ' + pkg.name + '@' + pkg.version);
+console.log('entry: ' + fileURLToPath(new URL('../lib/index.js', here)));