@joekytc/dsh-swarm 0.1.2 → 0.2.0

package/skills/llm-wiki-skill/scripts/runtime-context.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# 共享运行场景解析：供 install.sh 和 adapter-state.sh 复用
+
+resolve_platform_skill_root() {
+  case "$1" in
+    claude)
+      printf '%s\n' "$HOME/.claude/skills"
+      ;;
+    codex)
+      if [ -d "$HOME/.codex/skills" ] || [ ! -d "$HOME/.Codex/skills" ]; then
+        printf '%s\n' "$HOME/.codex/skills"
+      else
+        printf '%s\n' "$HOME/.Codex/skills"
+      fi
+      ;;
+    openclaw)
+      printf '%s\n' "$HOME/.openclaw/skills"
+      ;;
+    hermes)
+      printf '%s\n' "$HOME/.hermes/skills"
+      ;;
+    *)
+      echo "不支持的平台：$1" >&2
+      return 1
+      ;;
+  esac
+}
+
+detect_layout_mode() {
+  local bundle_root="$1"
+
+  if [ -e "$bundle_root/.git" ]; then
+    printf '%s\n' "source_checkout"
+    return 0
+  fi
+
+  printf '%s\n' "installed_skill"
+}
+
+resolve_layout_mode() {
+  local bundle_root="$1"
+  local override_mode="${2:-}"
+
+  if [ -n "$override_mode" ]; then
+    printf '%s\n' "$override_mode"
+    return 0
+  fi
+
+  detect_layout_mode "$bundle_root"
+}
+
+resolve_optional_adapter_root() {
+  local bundle_root="$1"
+  local skill_root_override="${2:-}"
+  local override_mode="${3:-}"
+  local layout_mode
+
+  if [ -n "$skill_root_override" ]; then
+    printf '%s\n' "$skill_root_override"
+    return 0
+  fi
+
+  layout_mode="$(resolve_layout_mode "$bundle_root" "$override_mode")"
+
+  case "$layout_mode" in
+    source_checkout)
+      printf '%s\n' "$bundle_root/deps"
+      ;;
+    installed_skill|upgrade_target)
+      printf '%s\n' "$(dirname "$bundle_root")"
+      ;;
+    *)
+      echo "未知运行模式：$layout_mode" >&2
+      return 1
+      ;;
+  esac
+}

package/skills/llm-wiki-skill/scripts/shared-config.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# 共享配置：被 install.sh / hook-session-start.sh / cache.sh / delete-helper.sh 等引用
+# 微信公众号提取工具的 Git 仓库地址
+WECHAT_TOOL_URL="git+https://github.com/jackwener/wechat-article-to-markdown.git"
+
+# Python 命令检测：Windows 默认安装为 python.exe，不存在 python3 命令
+# （Microsoft Store 的 python3 是安装提示 stub，运行会失败）
+_python_version_check='import sys; sys.exit(0 if sys.version_info >= (3, 8) else 1)'
+
+_python_cmd_is_valid() {
+  local candidate="$1"
+
+  command -v "$candidate" >/dev/null 2>&1 && "$candidate" -c "$_python_version_check" >/dev/null 2>&1
+}
+
+_detect_python_cmd() {
+  # 要求 Python 3.8+（见 README Windows 小节与下方错误消息）
+  if _python_cmd_is_valid python3; then
+    echo "python3"
+  elif _python_cmd_is_valid python; then
+    echo "python"
+  else
+    echo ""
+  fi
+}
+
+require_python_cmd() {
+  local detected_cmd
+
+  if [ "${PYTHON_CMD_READY:-0}" = "1" ]; then
+    return 0
+  fi
+
+  if [ -n "${PYTHON_CMD:-}" ] && _python_cmd_is_valid "$PYTHON_CMD"; then
+    export PYTHON_CMD
+    PYTHON_CMD_READY=1
+    return 0
+  fi
+
+  detected_cmd="$(_detect_python_cmd)"
+  if [ -z "$detected_cmd" ]; then
+    echo "[llm-wiki] 错误：找不到可用的 Python 3，请先安装 Python 3.8+ 并加入 PATH" >&2
+    return 1
+  fi
+
+  PYTHON_CMD="$detected_cmd"
+  export PYTHON_CMD
+  PYTHON_CMD_READY=1
+}
+
+# 统一 Python 子进程 stdout/stderr 编码为 UTF-8
+# Windows 中文环境下 Python 无 TTY 时 sys.stdout.encoding 默认 gbk (cp936)，
+# 会导致 Agent 通过 subprocess 读取的 JSON / 输出出现乱码 (issue #16)
+export PYTHONIOENCODING="${PYTHONIOENCODING:-utf-8}"
+
+# 输出指定工具的跨平台安装提示，缩进 2 空格便于嵌套在 ERROR 消息下；
+# 输出走 stderr，与 ERROR 消息保持同一通道。
+print_install_hint() {
+  local tool="$1"
+  case "$tool" in
+    jq)
+      echo "  macOS:        brew install jq" >&2
+      echo "  Linux/WSL:    sudo apt-get install jq   (Debian/Ubuntu)" >&2
+      echo "                sudo dnf install jq       (RHEL/Fedora)" >&2
+      echo "  Windows:      winget install jqlang.jq  (or choco install jq)" >&2
+      ;;
+    node)
+      echo "  macOS:        brew install node" >&2
+      echo "  Linux/WSL:    sudo apt-get install nodejs npm" >&2
+      echo "  Windows:      winget install OpenJS.NodeJS  (or choco install nodejs)" >&2
+      ;;
+    uv)
+      echo "  macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh    (official)" >&2
+      echo "                brew install uv                                    (alternative)" >&2
+      echo "  Windows:      powershell -c \"irm https://astral.sh/uv/install.ps1 | iex\"   (official)" >&2
+      echo "                winget install --id=astral-sh.uv -e                (alternative)" >&2
+      ;;
+    *)
+      echo "  unknown tool: $tool" >&2
+      return 1
+      ;;
+  esac
+}

package/skills/llm-wiki-skill/scripts/source-record-contract.tsv

@@ -0,0 +1,10 @@
+field_name	requiredness	filled_by	value_rule
+source_id	required	router	必须匹配 source-registry.tsv 中的 source_id
+source_label	required	router	必须匹配 source-registry.tsv 中的 source_label
+source_category	required	router	必须匹配 source-registry.tsv 中的 source_category
+input_mode	required	caller_or_router	只能是 url / file / text / asset
+raw_dir	required	router	必须是 raw/ 下的相对目录
+original_ref	required	caller	保存原始 URL、文件路径或用户粘贴说明
+ingest_text	required	adapter_or_user	进入主线前必须是非空文本
+adapter_name	required_may_be_empty	router_or_adapter	核心主线和手动入口留空；外挂来源写实际 adapter 名称
+fallback_hint	required	router	必须给出用户可执行的手动回退提示

package/skills/llm-wiki-skill/scripts/source-registry.sh

@@ -0,0 +1,349 @@
+#!/bin/bash
+# 统一来源总表读取与验证脚本
+# 权威数据文件：source-registry.tsv（来源定义）、source-record-contract.tsv（字段契约）
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONTRACT_FILE="$SCRIPT_DIR/source-record-contract.tsv"
+REGISTRY_FILE="$SCRIPT_DIR/source-registry.tsv"
+
+usage() {
+  cat <<'EOF'
+用法：
+  bash scripts/source-registry.sh fields
+  bash scripts/source-registry.sh list
+  bash scripts/source-registry.sh get <source_id>
+  bash scripts/source-registry.sh match-url <url>
+  bash scripts/source-registry.sh match-file <path>
+  bash scripts/source-registry.sh list-by-category <core_builtin|optional_adapter|manual_only>
+  bash scripts/source-registry.sh unique-dependencies <bundled|install_time|none>
+  bash scripts/source-registry.sh validate
+EOF
+}
+
+require_file() {
+  local file="$1"
+
+  [ -f "$file" ] || {
+    echo "缺少文件：$file" >&2
+    exit 1
+  }
+}
+
+expect_header() {
+  local file="$1"
+  local expected="$2"
+  local actual
+
+  actual="$(head -n 1 "$file")"
+  [ "$actual" = "$expected" ] || {
+    echo "表头不匹配：$file" >&2
+    echo "期望：$expected" >&2
+    echo "实际：$actual" >&2
+    exit 1
+  }
+}
+
+validate_contract() {
+  require_file "$CONTRACT_FILE"
+  expect_header "$CONTRACT_FILE" $'field_name\trequiredness\tfilled_by\tvalue_rule'
+
+  awk -F '\t' '
+    BEGIN {
+      required["source_id"] = 1
+      required["source_label"] = 1
+      required["source_category"] = 1
+      required["input_mode"] = 1
+      required["raw_dir"] = 1
+      required["original_ref"] = 1
+      required["ingest_text"] = 1
+      required["adapter_name"] = 1
+      required["fallback_hint"] = 1
+    }
+    NR == 1 { next }
+    {
+      if ($1 == "" || $2 == "" || $3 == "" || $4 == "") {
+        printf("source-record-contract.tsv 第 %d 行存在空字段\n", NR) > "/dev/stderr"
+        failed = 1
+      }
+
+      seen[$1] += 1
+    }
+    END {
+      for (field in required) {
+        if (seen[field] != 1) {
+          printf("source-record-contract.tsv 缺少或重复字段：%s\n", field) > "/dev/stderr"
+          failed = 1
+        }
+      }
+
+      exit failed ? 1 : 0
+    }
+  ' "$CONTRACT_FILE"
+}
+
+validate_registry() {
+  require_file "$REGISTRY_FILE"
+  expect_header "$REGISTRY_FILE" $'source_id\tsource_label\tsource_category\tinput_mode\tmatch_rule\traw_dir\tadapter_name\tdependency_name\tdependency_type\tfallback_hint'
+
+  awk -F '\t' '
+    NR == 1 { next }
+    {
+      if ($1 == "" || $2 == "" || $3 == "" || $4 == "" || $5 == "" || $6 == "" || $10 == "") {
+        printf("source-registry.tsv 第 %d 行存在空字段\n", NR) > "/dev/stderr"
+        failed = 1
+      }
+
+      if ($3 != "core_builtin" && $3 != "optional_adapter" && $3 != "manual_only") {
+        printf("source-registry.tsv 第 %d 行存在未知分类：%s\n", NR, $3) > "/dev/stderr"
+        failed = 1
+      }
+
+      if ($4 != "url" && $4 != "file" && $4 != "text" && $4 != "asset") {
+        printf("source-registry.tsv 第 %d 行存在未知输入模式：%s\n", NR, $4) > "/dev/stderr"
+        failed = 1
+      }
+
+      if ($4 == "url" && $5 !~ /^url_host:/) {
+        printf("source-registry.tsv 第 %d 行 URL 来源必须声明 url_host 规则：%s\n", NR, $5) > "/dev/stderr"
+        failed = 1
+      }
+
+      if ($4 == "file" && $5 !~ /^file_ext:/) {
+        printf("source-registry.tsv 第 %d 行文件来源必须声明 file_ext 规则：%s\n", NR, $5) > "/dev/stderr"
+        failed = 1
+      }
+
+      if ($4 == "text" && $5 !~ /^text:/) {
+        printf("source-registry.tsv 第 %d 行文本来源必须声明 text 规则：%s\n", NR, $5) > "/dev/stderr"
+        failed = 1
+      }
+
+      if ($4 == "asset" && $5 !~ /^asset:/) {
+        printf("source-registry.tsv 第 %d 行附件来源必须声明 asset 规则：%s\n", NR, $5) > "/dev/stderr"
+        failed = 1
+      }
+
+      if ($6 !~ /^raw\//) {
+        printf("source-registry.tsv 第 %d 行 raw_dir 必须位于 raw/ 下：%s\n", NR, $6) > "/dev/stderr"
+        failed = 1
+      }
+
+      if (seen[$1]++) {
+        printf("source-registry.tsv source_id 重复：%s\n", $1) > "/dev/stderr"
+        failed = 1
+      }
+
+      category_seen[$3] = 1
+
+      if ($3 == "optional_adapter") {
+        if ($7 == "-" || $8 == "-" || $9 == "none") {
+          printf("source-registry.tsv 第 %d 行 optional_adapter 缺少依赖信息\n", NR) > "/dev/stderr"
+          failed = 1
+        }
+      } else if ($7 != "-" || $8 != "-" || $9 != "none") {
+        printf("source-registry.tsv 第 %d 行非外挂来源不应声明依赖\n", NR) > "/dev/stderr"
+        failed = 1
+      }
+    }
+    END {
+      if (!category_seen["core_builtin"]) {
+        print "source-registry.tsv 缺少 core_builtin 来源" > "/dev/stderr"
+        failed = 1
+      }
+
+      if (!category_seen["optional_adapter"]) {
+        print "source-registry.tsv 缺少 optional_adapter 来源" > "/dev/stderr"
+        failed = 1
+      }
+
+      if (!category_seen["manual_only"]) {
+        print "source-registry.tsv 缺少 manual_only 来源" > "/dev/stderr"
+        failed = 1
+      }
+
+      exit failed ? 1 : 0
+    }
+  ' "$REGISTRY_FILE"
+}
+
+print_contract() {
+  validate_contract
+  cat "$CONTRACT_FILE"
+}
+
+print_registry() {
+  validate_registry
+  cat "$REGISTRY_FILE"
+}
+
+get_source() {
+  local source_id="$1"
+
+  validate_registry
+
+  awk -F '\t' -v source_id="$source_id" '
+    NR == 1 { next }
+    $1 == source_id {
+      print
+      found = 1
+    }
+    END {
+      exit found ? 0 : 1
+    }
+  ' "$REGISTRY_FILE"
+}
+
+extract_url_host() {
+  local url="$1"
+  local rest host
+
+  rest="${url#*://}"
+  if [ "$rest" = "$url" ]; then
+    rest="$url"
+  fi
+
+  rest="${rest#*@}"
+  host="${rest%%/*}"
+  host="${host%%\?*}"
+  host="${host%%#*}"
+  host="${host%%:*}"
+
+  printf '%s\n' "$host" | tr '[:upper:]' '[:lower:]'
+}
+
+host_matches_pattern() {
+  local host="$1"
+  local pattern="$2"
+
+  case "$host" in
+    "$pattern"|*."$pattern")
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+match_url() {
+  local url="$1"
+  local host row source_id source_label source_category input_mode match_rule raw_dir adapter_name dependency_name dependency_type fallback_hint
+  local fallback_row=""
+  local pattern pattern_list
+
+  validate_registry
+  host="$(extract_url_host "$url")"
+
+  while IFS=$'\t' read -r source_id source_label source_category input_mode match_rule raw_dir adapter_name dependency_name dependency_type fallback_hint; do
+    [ "$source_id" = "source_id" ] && continue
+    [ "$input_mode" = "url" ] || continue
+
+    pattern_list="${match_rule#url_host:}"
+    if [ "$pattern_list" = "*" ]; then
+      fallback_row="$(printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$source_id" "$source_label" "$source_category" "$input_mode" "$match_rule" "$raw_dir" "$adapter_name" "$dependency_name" "$dependency_type" "$fallback_hint")"
+      continue
+    fi
+
+    for pattern in ${pattern_list//,/ }; do
+      if host_matches_pattern "$host" "$pattern"; then
+        printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$source_id" "$source_label" "$source_category" "$input_mode" "$match_rule" "$raw_dir" "$adapter_name" "$dependency_name" "$dependency_type" "$fallback_hint"
+        return 0
+      fi
+    done
+  done < "$REGISTRY_FILE"
+
+  [ -n "$fallback_row" ] || return 1
+  printf '%s\n' "$fallback_row"
+}
+
+match_file() {
+  local path="$1"
+  local lowered_path source_id source_label source_category input_mode match_rule raw_dir adapter_name dependency_name dependency_type fallback_hint
+  local extension_list extension
+
+  validate_registry
+  lowered_path="$(printf '%s\n' "$path" | tr '[:upper:]' '[:lower:]')"
+
+  while IFS=$'\t' read -r source_id source_label source_category input_mode match_rule raw_dir adapter_name dependency_name dependency_type fallback_hint; do
+    [ "$source_id" = "source_id" ] && continue
+    [ "$input_mode" = "file" ] || continue
+
+    extension_list="${match_rule#file_ext:}"
+    for extension in ${extension_list//,/ }; do
+      case "$lowered_path" in
+        *"$extension")
+          printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$source_id" "$source_label" "$source_category" "$input_mode" "$match_rule" "$raw_dir" "$adapter_name" "$dependency_name" "$dependency_type" "$fallback_hint"
+          return 0
+          ;;
+      esac
+    done
+  done < "$REGISTRY_FILE"
+
+  return 1
+}
+
+list_by_category() {
+  local category="$1"
+
+  validate_registry
+
+  awk -F '\t' -v category="$category" '
+    NR == 1 { next }
+    $3 == category { print }
+  ' "$REGISTRY_FILE"
+}
+
+list_unique_dependencies() {
+  local dependency_type="$1"
+
+  validate_registry
+
+  awk -F '\t' -v dependency_type="$dependency_type" '
+    NR == 1 { next }
+    $9 == dependency_type && $8 != "-" { print $8 }
+  ' "$REGISTRY_FILE" | sort -u
+}
+
+command_name="${1:-}"
+
+case "$command_name" in
+  fields)
+    [ "$#" -eq 1 ] || { usage; exit 1; }
+    print_contract
+    ;;
+  list)
+    [ "$#" -eq 1 ] || { usage; exit 1; }
+    print_registry
+    ;;
+  get)
+    [ "$#" -eq 2 ] || { usage; exit 1; }
+    get_source "$2"
+    ;;
+  match-url)
+    [ "$#" -eq 2 ] || { usage; exit 1; }
+    match_url "$2"
+    ;;
+  match-file)
+    [ "$#" -eq 2 ] || { usage; exit 1; }
+    match_file "$2"
+    ;;
+  list-by-category)
+    [ "$#" -eq 2 ] || { usage; exit 1; }
+    list_by_category "$2"
+    ;;
+  unique-dependencies)
+    [ "$#" -eq 2 ] || { usage; exit 1; }
+    list_unique_dependencies "$2"
+    ;;
+  validate)
+    [ "$#" -eq 1 ] || { usage; exit 1; }
+    validate_contract
+    validate_registry
+    ;;
+  *)
+    usage
+    exit 1
+    ;;
+esac

package/skills/llm-wiki-skill/scripts/source-registry.tsv

@@ -0,0 +1,10 @@
+source_id	source_label	source_category	input_mode	match_rule	raw_dir	adapter_name	dependency_name	dependency_type	fallback_hint
+local_pdf	PDF / 本地 PDF	core_builtin	file	file_ext:.pdf	raw/pdfs	-	-	none	直接提供文件路径即可进入主线
+local_document	Markdown/文本/HTML	core_builtin	file	file_ext:.md,.txt,.html	raw/notes	-	-	none	直接提供文件路径即可进入主线
+plain_text	纯文本粘贴	core_builtin	text	text:inline	raw/notes	-	-	none	直接粘贴正文即可进入主线
+x_twitter	X/Twitter	optional_adapter	url	url_host:x.com,twitter.com	raw/tweets	baoyu-url-to-markdown	baoyu-url-to-markdown	bundled	自动提取失败时，改为复制全文粘贴
+wechat_article	微信公众号	optional_adapter	url	url_host:mp.weixin.qq.com	raw/wechat	wechat-article-to-markdown	wechat-article-to-markdown	install_time	自动提取失败时，在浏览器打开后复制全文粘贴
+youtube_video	YouTube	optional_adapter	url	url_host:youtube.com,youtu.be	raw/articles	youtube-transcript	youtube-transcript	bundled	自动提取失败时，提供字幕文件或手动粘贴文本
+zhihu_article	知乎	optional_adapter	url	url_host:zhihu.com	raw/zhihu	baoyu-url-to-markdown	baoyu-url-to-markdown	bundled	自动提取失败时，改为复制全文粘贴
+xiaohongshu_post	小红书	manual_only	url	url_host:xiaohongshu.com,xhslink.com	raw/xiaohongshu	-	-	none	请先从 App 或网页复制内容，再粘贴进来
+web_article	网页文章	optional_adapter	url	url_host:*	raw/articles	baoyu-url-to-markdown	baoyu-url-to-markdown	bundled	自动提取失败时，改为复制全文或保存为本地文件后继续

package/skills/llm-wiki-skill/scripts/source-signal-coverage.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const {
+  SCAN_KINDS,
+  extractFrontmatter,
+  evaluateSourceSignalEligibility
+} = require("./lib/source-signal-eligibility");
+
+function scanWiki(wikiRoot) {
+  const wikiDir = path.join(wikiRoot, "wiki");
+  if (!fs.existsSync(wikiDir)) {
+    console.error(`ERROR: wiki 目录不存在：${wikiDir}`);
+    process.exit(1);
+  }
+
+  const pages = [];
+  const summary = {
+    applicable_total: 0,
+    ok: 0,
+    missing_sources: 0,
+    empty_sources: 0,
+    invalid_sources: 0,
+    not_applicable: 0
+  };
+
+  for (const kind of SCAN_KINDS) {
+    const dir = path.join(wikiDir, kind.subdir);
+    if (!fs.existsSync(dir)) continue;
+
+    const files = fs.readdirSync(dir)
+      .filter((f) => f.endsWith(".md"))
+      .sort();
+
+    for (const file of files) {
+      const id = path.basename(file, ".md");
+      if (["index", "log", "purpose", ".wiki-schema", "README"].includes(id)) continue;
+
+      const filePath = path.join(dir, file);
+      const raw = fs.readFileSync(filePath, "utf8");
+      const { frontmatter } = extractFrontmatter(raw);
+      const result = evaluateSourceSignalEligibility({
+        pageType: kind.pageType,
+        frontmatter
+      });
+
+      pages.push({
+        path: path.relative(wikiRoot, filePath),
+        id,
+        pageType: kind.pageType,
+        eligible: result.eligible,
+        reason: result.reason,
+        sourceCount: result.sources.length
+      });
+
+      summary[result.reason] += 1;
+      if (result.reason !== "not_applicable") {
+        summary.applicable_total += 1;
+      }
+    }
+  }
+
+  return { summary, pages };
+}
+
+function main(argv) {
+  if (argv.length < 3) {
+    console.error("Usage: node scripts/source-signal-coverage.js <wiki_root>");
+    process.exit(1);
+  }
+
+  const wikiRoot = path.resolve(argv[2]);
+  const result = scanWiki(wikiRoot);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+if (require.main === module) {
+  main(process.argv);
+}
+
+module.exports = { scanWiki };