@andyqiu/teamkit 0.1.1

package/scripts/capability-detect.mjs

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+/**
+ * scripts/capability-detect.mjs — teamkit 安装前能力探测
+ *
+ * 探测 5 个功能下限（ADR: opencode-version-compatibility §Decision §1）：
+ *   1. plugin 加载机制（@opencode-ai/plugin 包存在 或 opencode.json plugins[] 可读）
+ *   2. ctx 上下文对象至少 1 个字段可访问
+ *   3. opencode 配置可读写（dry-run，不实际写）
+ *   4. AGENTS.md 全局路径可写（~/.config/opencode/AGENTS.md）
+ *   5. experimental.session.compacting hook 可被识别
+ *
+ * 退出码：
+ *   0 = 全部必需能力通过
+ *   1 = 任意必需能力失败
+ *
+ * ADR: opencode-version-compatibility
+ */
+
+import { readFileSync, existsSync, constants as fsConstants } from "node:fs"
+import { access } from "node:fs/promises"
+import { join } from "node:path"
+import { homedir } from "node:os"
+import { execSync } from "node:child_process"
+import { createRequire } from "node:module"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+
+const HOME = homedir()
+const OPENCODE_CONFIG_DIR = join(HOME, ".config", "opencode")
+const OPENCODE_JSON_PATH = join(OPENCODE_CONFIG_DIR, "opencode.json")
+const AGENTS_MD_PATH = join(OPENCODE_CONFIG_DIR, "AGENTS.md")
+const require = createRequire(import.meta.url)
+
+const results = {
+  pluginLoad:       { ok: false, label: "plugin 加载机制（@opencode-ai/plugin 或 opencode.json plugins[]）" },
+  ctxObject:        { ok: false, label: "ctx 上下文对象可访问（@opencode-ai/plugin API）" },
+  configReadWrite:  { ok: false, label: "opencode 配置可读写（~/.config/opencode/opencode.json）" },
+  agentsMd:         { ok: false, label: "AGENTS.md 全局路径可写（~/.config/opencode/AGENTS.md）" },
+  sessionCompacting:{ ok: false, label: "experimental.session.compacting hook 可被识别" },
+}
+
+const warnings = []
+
+// ─── 探测 1：plugin 加载机制 ─────────────────────────────────────────────────
+function detectPluginLoad() {
+  // 优先：@opencode-ai/plugin 包可解析
+  try {
+    require.resolve("@opencode-ai/plugin")
+    results.pluginLoad.ok = true
+    return
+  } catch { /* 继续 fallback */ }
+
+  // Fallback 1：opencode.json 存在且有 plugin/plugins 数组
+  try {
+    if (existsSync(OPENCODE_JSON_PATH)) {
+      const raw = JSON.parse(readFileSync(OPENCODE_JSON_PATH, "utf8"))
+      if (Array.isArray(raw?.plugin) || Array.isArray(raw?.plugins)) {
+        results.pluginLoad.ok = true
+        return
+      }
+    }
+  } catch { /* 失败 */ }
+
+  // Fallback 2：opencode CLI 存在即乐观通过（新用户首装场景）
+  // install.sh 后续会写入 opencode.json，此时文件可能尚不存在
+  try {
+    execSync('opencode --version', { timeout: 5000, stdio: 'ignore' })
+    warnings.push("⚠️  plugin 加载机制：opencode 存在，乐观通过（首装场景）")
+    results.pluginLoad.ok = true
+    return
+  } catch { /* opencode 不存在 */ }
+}
+
+// ─── 探测 2：ctx 上下文对象 ──────────────────────────────────────────────────
+function detectCtxObject() {
+  try {
+    const mod = require("@opencode-ai/plugin")
+    if (mod && typeof mod === "object" && Object.keys(mod).length > 0) {
+      results.ctxObject.ok = true
+      return
+    }
+  } catch { /* 包不存在 */ }
+
+  // Phase 1 MVP：包不存在时乐观通过，Phase 2 收紧
+  // ADR §Decision §3：Phase 1 不主动 probe IPC
+  warnings.push("⚠️  可选说明：@opencode-ai/plugin 未找到，ctx 探测乐观通过（Phase 1 行为）")
+  results.ctxObject.ok = true
+}
+
+// ─── 探测 3：opencode 配置可读写 ─────────────────────────────────────────────
+async function detectConfigReadWrite() {
+  // 逐层向上找可写祖先目录
+  const candidates = [
+    OPENCODE_CONFIG_DIR,
+    join(HOME, ".config"),
+    HOME,
+  ]
+  for (const dir of candidates) {
+    if (!existsSync(dir)) continue
+    try {
+      await access(dir, fsConstants.W_OK | fsConstants.R_OK)
+      results.configReadWrite.ok = true
+      return
+    } catch { /* 继续上一层 */ }
+  }
+}
+
+// ─── 探测 4：AGENTS.md 全局路径可写 ─────────────────────────────────────────
+async function detectAgentsMd() {
+  if (existsSync(AGENTS_MD_PATH)) {
+    try {
+      await access(AGENTS_MD_PATH, fsConstants.W_OK)
+      results.agentsMd.ok = true
+      return
+    } catch { return }
+  }
+
+  // 文件不存在 → 检测父目录
+  const candidates = [
+    OPENCODE_CONFIG_DIR,
+    join(HOME, ".config"),
+    HOME,
+  ]
+  for (const dir of candidates) {
+    if (!existsSync(dir)) continue
+    try {
+      await access(dir, fsConstants.W_OK)
+      results.agentsMd.ok = true
+      return
+    } catch { /* 继续 */ }
+  }
+}
+
+// ─── 探测 5：experimental.session.compacting hook ────────────────────────────
+// REQUIRED — hard fail（ADR: opencode-version-compatibility §Decision §4）
+//
+// 虚采纳-4 修正（Phase 1.2）：
+//   之前：依赖 @opencode-ai/plugin npm 包字段探测（在 file:// 部署模式下失效——
+//         opencode 通过 `plugin` key + file:// URI 加载插件，不通过 npm 包；
+//         因此 @opencode-ai/plugin 不存在于 node_modules，任何正常安装环境都会 exit(1)）
+//   probe plugin 方案局限：opencode run 无 --plugin CLI flag（仅有 --pure），
+//         无法在 capability-detect 中用 `opencode run --pure --plugin file://... "probe"` 单次运行；
+//         probe plugin 仍作为 T4/T5 验收测试 fixture 保留（tests/fixtures/probe-compacting-plugin.js）
+//   现在：版本检查方案——opencode >= 1.x 均支持 experimental.session.compacting；
+//         通过 `opencode --version` 判断主版本号，>= 1 则通过
+async function detectSessionCompacting() {
+  // 版本检查：opencode >= 1.x 均支持 session.compacting（ADR: opencode-version-compatibility）
+  try {
+    const ver = execSync("opencode --version", { timeout: 5000 }).toString().trim()
+    const major = parseInt(ver.split(".")[0], 10)
+    if (!isNaN(major) && major >= 1) {
+      results.sessionCompacting.ok = true
+      return
+    }
+    // 版本号 < 1（如 0.x）→ hard fail
+    results.sessionCompacting.ok = false
+    return
+  } catch {
+    // opencode CLI 不可用 → 无法确认 hook 支持 → hard fail
+    results.sessionCompacting.ok = false
+  }
+}
+
+// ─── 可选能力探测 ─────────────────────────────────────────────────────────────
+function detectOptionalCapabilities() {
+  try {
+    const mod = require("@opencode-ai/plugin")
+
+    if (!mod?.workingMemory && !mod?.WorkingMemory && !mod?.working_memory) {
+      warnings.push("⚠️  可选能力缺失：working_memory API（M1 KH 注入将降级）")
+    }
+
+    const hookNames = mod?.HOOK_NAMES ?? mod?.SUPPORTED_HOOKS ?? mod?.hookNames ?? []
+    if (Array.isArray(hookNames) && !hookNames.includes("session.end")) {
+      warnings.push("⚠️  可选能力缺失：session.end hook（auto-learning 将降级）")
+    }
+  } catch {
+    // @opencode-ai/plugin 不存在，跳过可选探测
+  }
+}
+
+// ─── 主流程 ───────────────────────────────────────────────────────────────────
+async function main() {
+  process.stdout.write("teamkit capability-detect: 探测 OpenCode 功能下限...\n")
+
+  detectPluginLoad()
+  detectCtxObject()
+  await detectSessionCompacting()
+  detectOptionalCapabilities()
+  await detectConfigReadWrite()
+  await detectAgentsMd()
+
+  for (const w of warnings) {
+    console.warn(w)
+  }
+
+  const failures = Object.entries(results).filter(([, v]) => !v.ok)
+
+  if (failures.length === 0) {
+    process.stdout.write("✅ 全部 5 项功能下限探测通过\n")
+    process.exit(0)
+  }
+
+  process.stderr.write("\n❌ teamkit: 以下必需能力不可用：\n\n")
+
+  for (const [key, v] of failures) {
+    process.stderr.write(`  ✗ ${v.label}\n`)
+
+    if (key === "sessionCompacting") {
+      // ADR: opencode-version-compatibility §Decision §4
+      process.stderr.write(
+        "\n" +
+        "  ⚠️  experimental.session.compacting hook 不可用！\n" +
+        "  此 hook 是 teamkit M2 层（长对话 KH 保护）的核心依赖。\n" +
+        "  请升级 OpenCode 至支持 experimental.session.compacting hook 的版本。\n" +
+        "  参考：docs/compatibility.md\n\n"
+      )
+    }
+  }
+
+  process.stderr.write(
+    "install 已中止。请修复上述问题后重新运行 install.sh\n" +
+    "运行 `teamkit doctor` 获取详细诊断信息\n"
+  )
+  process.exit(1)
+}
+
+main().catch((err) => {
+  process.stderr.write(`capability-detect 内部错误: ${err.message}\n`)
+  process.exit(1)
+})

package/scripts/merge-agents-md.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * scripts/merge-agents-md.mjs — install.sh / install.ps1 共用的 AGENTS.md 智能合并 CLI
+ *
+ * 从 code-forge/scripts/merge-agents-md.mjs 搬迁，适配 teamkit。
+ * 改动：注释将 CodeForge → teamkit，其余逻辑不变。
+ *
+ * 算法语义与 lib/agents-merge.ts 严格一致（单一来源）。
+ * 自带实现而不是 import lib/agents-merge.ts，因为 install 时 lib/ 可能不可访问。
+ *
+ * 用法：
+ *   node scripts/merge-agents-md.mjs --target <path/to/AGENTS.md> --template <path/to/kh-instructions.md>
+ *
+ * 选项：
+ *   --target <path>       目标 AGENTS.md 路径（必填）
+ *   --template <path>     KH instructions 模板路径（必填）
+ *   --dry-run             仅打印将要做什么，不实际写文件
+ *   --no-backup           跳过 .bak 备份（默认会备份）
+ *   --quiet               静默模式（仅错误输出）
+ *   -h / --help           帮助
+ *
+ * 退出码：
+ *   0 = 成功（或 dry-run）
+ *   1 = 参数错误
+ *   2 = 模板文件不存在
+ *   3 = 写文件失败
+ */
+
+import { readFileSync, writeFileSync, copyFileSync, existsSync } from "node:fs"
+import { basename } from "node:path"
+import process from "node:process"
+
+const KH_MARKER_START = "<!-- knowledge-hub:start -->"
+const KH_MARKER_END = "<!-- knowledge-hub:end -->"
+const START_PREFIX = "<!-- knowledge-hub:start"
+const END_PREFIX = "<!-- knowledge-hub:end"
+
+// ────────────────────────────────────────────────────────────────────
+// 算法：与 lib/agents-merge.ts 一致
+// ────────────────────────────────────────────────────────────────────
+
+function findMarkerLine(text, prefix, fromLine = 0) {
+  const lines = text.split("\n")
+  for (let i = fromLine; i < lines.length; i++) {
+    if (lines[i].trimStart().startsWith(prefix)) return i
+  }
+  return -1
+}
+
+function normalizeTemplate(tpl) {
+  return tpl.replace(/\n+$/g, "")
+}
+
+function backupSuffix(now = new Date()) {
+  const pad = (n) => String(n).padStart(2, "0")
+  return (
+    `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}` +
+    `${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`
+  )
+}
+
+function backupPath(originalPath, now = new Date()) {
+  return `${originalPath}.bak.${backupSuffix(now)}`
+}
+
+function createDefault(template) {
+  const tpl = normalizeTemplate(template)
+  return [
+    "# 项目 AGENTS.md",
+    "",
+    KH_MARKER_START,
+    "",
+    tpl,
+    "",
+    KH_MARKER_END,
+    "",
+    "## 项目专属约定",
+    "",
+    "（在此添加本项目特有的开发约定）",
+    "",
+  ].join("\n")
+}
+
+function mergeAgentsMd({ template, existing }) {
+  const tpl = normalizeTemplate(template)
+
+  if (existing == null || existing.length === 0) {
+    return { content: createDefault(tpl), mode: "created" }
+  }
+
+  const startIdx = findMarkerLine(existing, START_PREFIX)
+  const endIdx = startIdx === -1 ? -1 : findMarkerLine(existing, END_PREFIX, startIdx + 1)
+
+  if (startIdx !== -1 && endIdx !== -1) {
+    const lines = existing.split("\n")
+    const before = lines.slice(0, startIdx + 1)
+    const after = lines.slice(endIdx)
+    const middle = ["", tpl, ""]
+    return {
+      content: [...before, ...middle, ...after].join("\n"),
+      mode: "replaced",
+    }
+  }
+
+  const block = `${KH_MARKER_START}\n\n${tpl}\n\n${KH_MARKER_END}\n\n`
+  return {
+    content: block + existing,
+    mode: "inserted",
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// CLI
+// ────────────────────────────────────────────────────────────────────
+
+const HELP = `
+scripts/merge-agents-md.mjs — AGENTS.md 智能合并 CLI（teamkit）
+
+用法：
+  node scripts/merge-agents-md.mjs --target <path> --template <path> [选项]
+
+选项：
+  --target <path>       目标 AGENTS.md 路径（必填）
+  --template <path>     KH instructions 模板路径（必填）
+  --dry-run             仅打印将要做什么
+  --no-backup           跳过 .bak 备份（默认会备份）
+  --quiet               静默模式
+  -h / --help           本帮助
+
+退出码：
+  0 成功    1 参数错误    2 模板缺失    3 写文件失败
+`
+
+function parseArgs(argv) {
+  const args = { target: null, template: null, dryRun: false, backup: true, quiet: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === "-h" || a === "--help") {
+      process.stdout.write(HELP)
+      process.exit(0)
+    } else if (a === "--target") args.target = argv[++i]
+    else if (a === "--template") args.template = argv[++i]
+    else if (a === "--dry-run") args.dryRun = true
+    else if (a === "--no-backup") args.backup = false
+    else if (a === "--quiet") args.quiet = true
+    else {
+      process.stderr.write(`未知参数: ${a}\n${HELP}`)
+      process.exit(1)
+    }
+  }
+  return args
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (!args.target || !args.template) {
+    process.stderr.write("错误：--target 和 --template 都必须指定\n" + HELP)
+    process.exit(1)
+  }
+
+  const log = args.quiet ? () => {} : (msg) => process.stdout.write(msg + "\n")
+
+  if (!existsSync(args.template)) {
+    process.stderr.write(`模板文件不存在: ${args.template}\n`)
+    process.exit(2)
+  }
+  const template = readFileSync(args.template, "utf8")
+  const existing = existsSync(args.target) ? readFileSync(args.target, "utf8") : null
+  const result = mergeAgentsMd({ template, existing })
+
+  if (args.dryRun) {
+    log(`[dry-run] mode=${result.mode}  target=${args.target}`)
+    log(`[dry-run] 将写入 ${result.content.length} 字节`)
+    if (existing && args.backup) {
+      log(`[dry-run] 将备份到 ${backupPath(args.target)}`)
+    }
+    process.exit(0)
+  }
+
+  if (existing && args.backup) {
+    const bak = backupPath(args.target)
+    try {
+      copyFileSync(args.target, bak)
+      log(`  ✓ 已备份原 AGENTS.md → ${basename(bak)}`)
+    } catch (err) {
+      process.stderr.write(`备份失败: ${err.message}\n`)
+      process.exit(3)
+    }
+  }
+
+  try {
+    writeFileSync(args.target, result.content, "utf8")
+    log(`  ✓ AGENTS.md ${result.mode}: ${args.target}`)
+    process.exit(0)
+  } catch (err) {
+    process.stderr.write(`写入失败: ${err.message}\n`)
+    process.exit(3)
+  }
+}
+
+main()

package/scripts/publish.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+# publish.sh — teamkit 一键发布脚本
+#
+# 用法：
+#   bash scripts/publish.sh            # 发布当前版本（不 bump）
+#   bash scripts/publish.sh --patch    # bump patch 后发布
+#   bash scripts/publish.sh --minor    # bump minor 后发布
+#   bash scripts/publish.sh --major    # bump major 后发布
+#
+# 环境变量：
+#   NPM_OTP   若已设置，自动用于 NPM_CONFIG_OTP；否则脚本交互式询问
+#
+# 步骤：
+#   1. 读取 / 展示当前版本
+#   2. （可选）bump 版本
+#   3. npm run build && npm run typecheck
+#   4. git tag v<version>（只创建，不 push）
+#   5. npm publish --access public
+#   6. git push && git push --tags（publish 成功后才推送）
+#   7. 成功提示
+
+set -euo pipefail
+
+# ────────────────────────────────────────────────────────────────────────────
+# 颜色 & 输出工具（与 install.sh 一致）
+# ────────────────────────────────────────────────────────────────────────────
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+GREEN='\033[0;32m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+err()  { printf "${RED}❌  %s${NC}\n" "$*" >&2; }
+warn() { printf "${YELLOW}⚠️   %s${NC}\n" "$*"; }
+info() { printf "${CYAN}ℹ️   %s${NC}\n" "$*"; }
+ok()   { printf "${GREEN}✅  %s${NC}\n" "$*"; }
+
+# ────────────────────────────────────────────────────────────────────────────
+# 定位项目根目录（脚本可从任意目录调用）
+# ────────────────────────────────────────────────────────────────────────────
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+PACKAGE_JSON="${ROOT_DIR}/package.json"
+
+# ────────────────────────────────────────────────────────────────────────────
+# 参数解析
+# ────────────────────────────────────────────────────────────────────────────
+BUMP=""
+
+for arg in "$@"; do
+  case "$arg" in
+    --patch) BUMP="patch" ;;
+    --minor) BUMP="minor" ;;
+    --major) BUMP="major" ;;
+    *)
+      err "未知参数：$arg"
+      err "用法：$0 [--patch|--minor|--major]"
+      exit 1
+      ;;
+  esac
+done
+
+# ────────────────────────────────────────────────────────────────────────────
+# 步骤 1：读取当前版本
+# ────────────────────────────────────────────────────────────────────────────
+if ! command -v node &>/dev/null; then
+  err "未找到 node，请先安装 Node.js"
+  exit 1
+fi
+
+CURRENT_VERSION="$(node -e "process.stdout.write(require('${PACKAGE_JSON}').version)")"
+info "当前版本：${CURRENT_VERSION}"
+
+# ────────────────────────────────────────────────────────────────────────────
+# 步骤 2：（可选）bump 版本
+# ────────────────────────────────────────────────────────────────────────────
+bump_semver() {
+  local ver="$1"
+  local part="$2"
+  local major minor patch
+  IFS='.' read -r major minor patch <<< "$ver"
+  case "$part" in
+    major) major=$((major + 1)); minor=0; patch=0 ;;
+    minor) minor=$((minor + 1)); patch=0 ;;
+    patch) patch=$((patch + 1)) ;;
+  esac
+  echo "${major}.${minor}.${patch}"
+}
+
+if [[ -n "$BUMP" ]]; then
+  NEW_VERSION="$(bump_semver "$CURRENT_VERSION" "$BUMP")"
+  info "Bump ${BUMP}：${CURRENT_VERSION} → ${NEW_VERSION}"
+
+  # 用 node 原地更新 package.json（保留格式）
+  node - <<EOF
+const fs = require('fs');
+const pkg = JSON.parse(fs.readFileSync('${PACKAGE_JSON}', 'utf8'));
+pkg.version = '${NEW_VERSION}';
+fs.writeFileSync('${PACKAGE_JSON}', JSON.stringify(pkg, null, 2) + '\n');
+EOF
+  ok "package.json 已更新版本为 ${NEW_VERSION}"
+  VERSION="$NEW_VERSION"
+else
+  VERSION="$CURRENT_VERSION"
+  info "不 bump 版本，使用当前版本 ${VERSION}"
+fi
+
+# ────────────────────────────────────────────────────────────────────────────
+# 用户确认
+# ────────────────────────────────────────────────────────────────────────────
+printf "\n"
+warn "即将发布 @andyqiu/teamkit@${VERSION}"
+read -r -p "$(printf "${YELLOW}确认发布？[y/N] ${NC}")" CONFIRM
+case "$CONFIRM" in
+  [yY][eE][sS]|[yY]) ;;
+  *)
+    info "已取消发布"
+    exit 0
+    ;;
+esac
+printf "\n"
+
+# ────────────────────────────────────────────────────────────────────────────
+# 步骤 3：build + typecheck
+# ────────────────────────────────────────────────────────────────────────────
+info "正在执行 build + typecheck …"
+(cd "$ROOT_DIR" && npm run build && npm run typecheck)
+ok "build + typecheck 通过"
+
+# ────────────────────────────────────────────────────────────────────────────
+# 步骤 4：git tag（只创建，不 push）
+# ────────────────────────────────────────────────────────────────────────────
+TAG="v${VERSION}"
+info "创建 git tag ${TAG} …"
+
+(
+  cd "$ROOT_DIR"
+
+  # 若版本被 bump，先提交 package.json 改动
+  if [[ -n "$BUMP" ]]; then
+    git add package.json
+    git commit -m "chore: bump version to ${VERSION}"
+    ok "已提交版本 bump commit"
+  fi
+
+  if git rev-parse "$TAG" &>/dev/null; then
+    err "Tag ${TAG} 已存在，请先删除或检查版本号"
+    exit 1
+  fi
+
+  git tag "$TAG"
+  ok "已创建 tag ${TAG}"
+)
+
+# ────────────────────────────────────────────────────────────────────────────
+# 步骤 5：npm publish（OTP 通过环境变量传入，不出现在命令行参数）
+# ────────────────────────────────────────────────────────────────────────────
+info "准备 npm publish …"
+
+if [[ -n "${NPM_OTP:-}" ]]; then
+  info "检测到环境变量 NPM_OTP，自动使用"
+  OTP="$NPM_OTP"
+else
+  read -r -p "$(printf "${CYAN}Authenticator OTP: ${NC}")" OTP
+fi
+
+info "执行 npm publish --access public …"
+(cd "$ROOT_DIR" && NPM_CONFIG_OTP="$OTP" npm publish --access public)
+ok "npm publish 完成"
+
+# ────────────────────────────────────────────────────────────────────────────
+# 步骤 6：git push + push tags（publish 成功后才推送）
+# ────────────────────────────────────────────────────────────────────────────
+info "推送代码 + tags …"
+(cd "$ROOT_DIR" && git push && git push --tags)
+ok "已推送到远端"
+
+# ────────────────────────────────────────────────────────────────────────────
+# 步骤 7：成功
+# ────────────────────────────────────────────────────────────────────────────
+printf "\n"
+ok "🎉  @andyqiu/teamkit@${VERSION} 发布成功！"
+info "安装/升级命令：npm install -g @andyqiu/teamkit"
+info "查看包页面：https://www.npmjs.com/package/@andyqiu/teamkit"