askhuman 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# askhuman
+
+跨平台「Human-in-the-loop」交互工具。命令行 `AskHuman` 在 AI 助手需要确认/补充时弹出窗口（或经 Telegram）收集人类回应，并把结果按固定区块写到 stdout。
+
+底层为单一可执行文件（Tauri 2 / Rust）。本 npm 包通过「平台子包」分发：安装时只会拉取与当前平台匹配的一个二进制。
+
+## 单独使用
+
+```bash
+npm i -g askhuman
+AskHuman "要不要继续？" -o "继续" -o "停止"
+```
+
+## 作为依赖（程序集成）
+
+```bash
+npm i askhuman
+```
+
+```js
+import { getBinaryPath, isAvailable } from "askhuman";
+import { spawnSync } from "node:child_process";
+
+if (!isAvailable()) {
+  // 二进制未就位：跳过人工确认环节，避免阻塞流程
+} else {
+  const r = spawnSync(getBinaryPath(), ["要继续吗？", "-o", "继续", "-o", "停止"], {
+    encoding: "utf8",
+  });
+  if (r.status === 3) {
+    // 当前环境无任何可用 channel（GUI 打不开且未配置 Telegram）：降级处理
+  } else if (r.status === 0) {
+    // 成功：解析 r.stdout 的结果区块
+    console.log(r.stdout);
+  }
+}
+```
+
+`getBinaryPath()` 解析顺序：环境变量 `HUMANINLOOP_BINARY` → 平台子包 → 系统 `PATH`。
+
+## 退出码契约
+
+| 退出码 | 含义 |
+|---|---|
+| `0` | 成功拿到结果，或用户取消（输出 `[状态]`） |
+| `3` | 无任何可用 channel（本地弹窗打不开且未配置 Telegram）——下游应降级 |
+| `1` | 其他异常 |
+
+stdout 只含结果区块（`[选择的选项]`/`[用户输入]`/`[图片]`/`[状态]`），所有日志与报错走 stderr。
+
+## 平台与系统依赖
+
+支持 macOS（arm64/x64）、Windows（x64）、Linux（x64）。
+
+> Linux 运行 GUI 弹窗需系统具备 WebKitGTK（如 `libwebkit2gtk-4.1`）。若缺失且配置了 Telegram，会自动改走 Telegram；若两者都不可用，则以退出码 `3` 提示降级。
+
+更多信息见项目仓库：<https://github.com/Naituw/HumanInLoop>

package/bin/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+"use strict";
+
+// 全局命令入口（npm i -g humaninloop 后的 `AskHuman`）：
+// 解析当前平台二进制并透传 argv 与退出码。
+// 下游程序集成请直接使用 require("humaninloop").getBinaryPath()，不必经此 shim。
+
+const { spawn } = require("child_process");
+const { getBinaryPath } = require("../index.js");
+
+const bin = getBinaryPath();
+if (!bin) {
+  process.stderr.write(
+    "humaninloop: 未找到当前平台的 AskHuman 二进制。\n" +
+      "请确认对应平台子包已安装，或设置环境变量 HUMANINLOOP_BINARY 指向二进制。\n"
+  );
+  process.exit(1);
+}
+
+const child = spawn(bin, process.argv.slice(2), { stdio: "inherit" });
+
+child.on("error", (err) => {
+  process.stderr.write(`humaninloop: 启动失败: ${err.message}\n`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+  } else {
+    process.exit(code == null ? 0 : code);
+  }
+});

package/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 返回当前平台的 AskHuman 二进制绝对路径。
+ * 解析顺序：环境变量 `HUMANINLOOP_BINARY` → 平台子包 → 系统 `PATH`。
+ * 找不到时返回 `null`。
+ */
+export declare function getBinaryPath(): string | null;
+
+/**
+ * 二进制是否已就位且可执行。
+ * 注意：仅代表二进制可被调用，不代表 GUI 弹窗可用；
+ * 具体哪个 channel 可用由二进制运行期决定（见退出码契约：3 = 无可用 channel）。
+ */
+export declare function isAvailable(): boolean;

package/index.js

@@ -0,0 +1,80 @@
+"use strict";
+
+// 解析当前平台的 AskHuman 二进制路径，供下游程序集成调用。
+// 解析顺序：环境变量 HUMANINLOOP_BINARY → 平台子包 → 系统 PATH。
+
+const fs = require("fs");
+const path = require("path");
+
+// platformKey -> 平台子包名
+const PLATFORM_PACKAGES = {
+  "darwin-arm64": "@humaninloop/darwin-arm64",
+  "darwin-x64": "@humaninloop/darwin-x64",
+  "win32-x64": "@humaninloop/win32-x64",
+  "linux-x64": "@humaninloop/linux-x64",
+};
+
+function binName() {
+  return process.platform === "win32" ? "AskHuman.exe" : "AskHuman";
+}
+
+function platformKey() {
+  return `${process.platform}-${process.arch}`;
+}
+
+function isExecutableFile(p) {
+  try {
+    const st = fs.statSync(p);
+    if (!st.isFile()) return false;
+  } catch {
+    return false;
+  }
+  if (process.platform === "win32") return true; // X_OK 在 Windows 无意义
+  try {
+    fs.accessSync(p, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function fromEnv() {
+  const p = process.env.HUMANINLOOP_BINARY;
+  return p && fs.existsSync(p) ? p : null;
+}
+
+function fromPlatformPackage() {
+  const pkg = PLATFORM_PACKAGES[platformKey()];
+  if (!pkg) return null;
+  try {
+    return require.resolve(`${pkg}/bin/${binName()}`);
+  } catch {
+    return null;
+  }
+}
+
+function fromPath() {
+  const exe = binName();
+  const dirs = (process.env.PATH || "").split(path.delimiter);
+  for (const dir of dirs) {
+    if (!dir) continue;
+    const candidate = path.join(dir, exe);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+// 返回二进制绝对路径；找不到返回 null。
+function getBinaryPath() {
+  return fromEnv() || fromPlatformPackage() || fromPath() || null;
+}
+
+// 二进制是否已就位且可执行。
+// 注意：仅代表二进制可被调用，不代表 GUI 弹窗可用；
+// 具体哪个 channel 可用由二进制运行期决定（见退出码契约）。
+function isAvailable() {
+  const p = getBinaryPath();
+  return p != null && isExecutableFile(p);
+}
+
+module.exports = { getBinaryPath, isAvailable };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "askhuman",
+  "version": "0.1.0",
+  "description": "Human-in-the-loop interaction tool. The `AskHuman` CLI pops up a window (or uses Telegram) to collect human input and prints the result to stdout — usable standalone or as a dependency.",
+  "license": "MIT",
+  "author": "Naituw",
+  "homepage": "https://github.com/Naituw/HumanInLoop",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Naituw/HumanInLoop.git"
+  },
+  "type": "commonjs",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "AskHuman": "bin/cli.js"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "bin",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "keywords": [
+    "human-in-the-loop",
+    "cli",
+    "tauri",
+    "ai",
+    "askhuman",
+    "prompt"
+  ],
+  "optionalDependencies": {
+    "@humaninloop/darwin-arm64": "0.1.0",
+    "@humaninloop/darwin-x64": "0.1.0",
+    "@humaninloop/win32-x64": "0.1.0",
+    "@humaninloop/linux-x64": "0.1.0"
+  }
+}