@abelxiaoxing/cadence 1.8.1 → 1.8.2

package/README.md

@@ -14,6 +14,33 @@
 4. 首次进入项目先运行 `/abel-init`，然后 `/abel-design <需求>`，确认集中呈现的目标与方案，设计完成后运行 `/abel-implement <change>`。
 5. 暂停时先查看原因和建议，不要靠反复 resume 或重启“碰运气”；未完成的工作会保留。
 
+### 每次加载时的配置提示卡
+
+每次扩展启动、重载或恢复会话，Cadence 都会在输入框上方显示一张简短研究能力提示卡，不需要额外记住配置或诊断命令。
+卡片只检查本地配置，显示 Context7、Grok 与可选 Tavily 的配置状态及当前生效文件；“已配置”不代表网络、认证或服务能力已验证。
+开始处理任务后卡片收起，下次加载重新显示；不记录“已看过”或“暂时不用”来抑制后续提示。
+安装 Cadence 时会创建用户级模板 `~/.pi/agent/cadence/.env`（已有文件不会覆盖）；卡片本身不会联网、调用模型、写入配置、索要密钥或自动激活 Abel 工作流，可选服务未配置不阻塞普通任务。
+未信任的项目只显示未检查提示，不读取研究配置。
+
+安装后用户级模板已包含 Grok 配置占位字段；Context7 无配置文件时仍使用默认地址匿名访问，显式配置文件损坏仍会报错。
+联网搜索需要在本地文件中配置以下内容，每项一行（替换为实际服务地址和密钥）：
+
+```dotenv
+GROK_API_URL=https://api.x.ai/v1
+GROK_API_KEY=<your-api-key>
+```
+
+安装器会创建用户级 `~/.pi/agent/cadence/.env` 及其父目录，并且只在文件不存在时写入模板；也可手动创建该文件以跨项目复用。
+如果项目已有 `.pi/cadence/.env`，它按整文件优先，**不会与用户级文件合并**；请编辑卡片显示的生效文件，不要覆盖已有无关配置。
+研究 Skills 不读取 shell 中的 API 环境变量，也不读取安装包旁的 `.env`；保存后下次 Skill 调用生效，无需重启。
+可选 `CONTEXT7_API_KEY` 提供认证访问；可选 `TAVILY_API_KEY` 启用扩展检索、抓取和站点映射，`TAVILY_ENABLED=false` 可关闭它。
+完整字段见 [配置模板](config/.env.example)，配置文件限普通文件且不超过 64 KiB。
+密钥只在本地编辑，勿发送到聊天或提交 Git；使用项目级文件时应将其加入忽略规则。
+
+TUI 显示卡片；RPC 通过非阻塞 `setWidget` 事件发送同一卡片，Web UI 需实现该事件的展示。
+Print / JSON 无交互界面，不额外输出卡片、不等待输入，也不污染标准输出；可按上述路径直接配置。
+本版本提供提示与本地编辑指引，不提供密钥输入向导或自动重试搜索。
+
 ### Pi / Web UI 阶段启动约定
 
 阶段命令需要 Cadence 扩展与包内 prompts 同时加载；只有提示正文可见，不代表 `abel_dispatch` 已注册或已激活。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abelxiaoxing/cadence",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "Four explicit Abel workflow prompts with stage-isolated design and diagnosis, durable resumable implementation, and three package-owned professional Agents.",
   "license": "MIT",
   "type": "module",
@@ -37,6 +37,7 @@
     ]
   },
   "scripts": {
+    "postinstall": "node src/install-config.mjs",
     "pack:check": "node scripts/pack-check.mjs",
     "traceability:check": "node scripts/traceability-check.mjs",
     "verify": "bun run check && bun run lint && bun run test && bun run pack:check",

package/skills/_shared/load-config.d.mts

@@ -1,7 +1,13 @@
 export declare function parseEnvFile(content: string): Record<string, string>;
 
+export declare function selectConfigPath(options: {
+  cwd: string;
+  home: string;
+}): string | null;
+
 export declare function loadConfig(options: {
   cwd: string;
   home: string;
   required?: readonly string[];
-}): { path: string; values: Record<string, string> };
+  allowMissing?: boolean;
+}): { path: string | null; values: Record<string, string> };

package/skills/_shared/load-config.mjs

@@ -1,4 +1,11 @@
-import { existsSync, readFileSync } from "node:fs";
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readSync,
+} from "node:fs";
 import path from "node:path";
 
 export function parseEnvFile(content) {
@@ -37,22 +44,68 @@ export function parseEnvFile(content) {
   return values;
 }
 
-export function loadConfig({ cwd, home, required = [] }) {
+function pathEntryExists(filePath) {
+  try {
+    // lstat, rather than existsSync, intentionally retains dangling symlinks.
+    // They are an explicit configuration path and must fail closed when opened.
+    lstatSync(filePath);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+export function selectConfigPath({ cwd, home }) {
   const projectPath = path.join(cwd, ".pi", "cadence", ".env");
   const userPath = path.join(home, ".pi", "agent", "cadence", ".env");
-  const selectedPath = existsSync(projectPath)
+  return pathEntryExists(projectPath)
     ? projectPath
-    : existsSync(userPath)
+    : pathEntryExists(userPath)
       ? userPath
       : null;
+}
+
+export function loadConfig({ cwd, home, required = [], allowMissing = false }) {
+  const selectedPath = selectConfigPath({ cwd, home });
+  if (!selectedPath && allowMissing && required.length === 0) {
+    return { path: null, values: {} };
+  }
 
   if (!selectedPath) {
+    const projectPath = path.join(cwd, ".pi", "cadence", ".env");
+    const userPath = path.join(home, ".pi", "agent", "cadence", ".env");
     throw new Error(
       `No cadence configuration file found; create ${projectPath} or ${userPath}`,
     );
   }
 
-  const values = parseEnvFile(readFileSync(selectedPath, "utf8"));
+  // Configuration inspection also runs at extension startup: never block on
+  // a FIFO/device or read an unbounded file. Read one extra byte to detect growth.
+  const maxBytes = 64 * 1024;
+  const fd = openSync(selectedPath, constants.O_RDONLY | constants.O_NONBLOCK);
+  let content;
+  try {
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > maxBytes) {
+      throw new Error(
+        "Cadence configuration must be a regular file of at most 64 KiB",
+      );
+    }
+    const buffer = Buffer.alloc(maxBytes + 1);
+    let size = 0;
+    while (size < buffer.length) {
+      const count = readSync(fd, buffer, size, buffer.length - size, null);
+      if (!count) break;
+      size += count;
+    }
+    if (size > maxBytes)
+      throw new Error("Cadence configuration exceeds 64 KiB");
+    content = buffer.subarray(0, size).toString("utf8");
+  } finally {
+    closeSync(fd);
+  }
+  const values = parseEnvFile(content);
   const missing = required.filter((name) => !values[name]);
   if (missing.length > 0) {
     throw new Error(

package/skills/context7-auto-research/SKILL.md

@@ -30,3 +30,8 @@ Treat a non-zero exit, invalid shape, or empty useful result as a failed lookup;
 The CLI selects the project `.pi/cadence/.env` as a whole file when present, otherwise `~/.pi/agent/cadence/.env`.
 It does not merge files, read ambient API configuration, or read `.env` beside the installed package.
 `CONTEXT7_API_KEY` may be empty; `CONTEXT7_API_URL` defaults to `https://context7.com/api/v2`.
+When neither configuration file exists, use those anonymous defaults without creating a file.
+An existing malformed or unreadable file is still an error; never silently fall back.
+Cadence shows a local configuration card on every extension load in TUI/RPC; configured does not mean network-verified.
+Configuration files must be regular files of at most 64 KiB.
+Never ask for API keys in chat.

package/skills/context7-auto-research/context7.mjs

@@ -9,7 +9,7 @@ import { loadConfig } from "../_shared/load-config.mjs";
 const DEFAULT_API_URL = "https://context7.com/api/v2";
 
 export function loadContext7Config({ cwd, home }) {
-  const selected = loadConfig({ cwd, home });
+  const selected = loadConfig({ cwd, home, allowMissing: true });
   return {
     path: selected.path,
     apiUrl: selected.values.CONTEXT7_API_URL || DEFAULT_API_URL,

package/skills/grok-search/SKILL.md

@@ -36,4 +36,9 @@ Treat non-zero exits and invalid result shapes as failed research.
 
 The CLI selects the project `.pi/cadence/.env` as a whole file when present, otherwise `~/.pi/agent/cadence/.env`.
 `GROK_API_URL` and `GROK_API_KEY` are required.
+Cadence shows the selected configuration path and missing fields on every extension load in TUI/RPC, without network verification.
+If configuration is missing, direct the user to edit that local file (prefer the user file when no project file exists); never ask them to paste a key in chat.
+The CLI does not read shell API variables.
+Save one `NAME=value` per line; the next invocation reads the changes without restarting Pi.
+Configuration files must be regular files of at most 64 KiB.
 `GROK_MODEL` defaults to `grok-4.20-non-reasoning`, `TAVILY_API_URL` defaults to `https://api.tavily.com`, and Tavily is enabled by default once a non-empty `TAVILY_API_KEY` is configured; set `TAVILY_ENABLED=false` to opt out.

package/src/index.ts

@@ -22,6 +22,7 @@ export { executePackageVerification } from "./package-verification.ts";
 // integration; abel-init and ordinary prompts never activate dispatch.
 
 import { createHash } from "node:crypto";
+import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import type {
@@ -58,7 +59,7 @@ import { canonicalJson } from "./implement-graph.ts";
 import { PACKET_ACTIONS, PacketRuntime } from "./packet-runtime.ts";
 
 import { RunStoreFormatError, RunStoreMigrationError } from "./run-store.ts";
-
+import { STARTUP_CARD_KEY, startupCardLines } from "./startup-card.ts";
 import { StateRootError } from "./state-root.ts";
 import {
   ACTIVITY_DETAILS_KEY,
@@ -1792,4 +1793,22 @@ export function registerWorkflowControl(
 
 export default function register(pi: ExtensionAPI): void {
   registerWorkflowControl(pi);
+  // Presentation only: never persist a dismissal or inject a model message.
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    ctx.ui.setWidget(
+      STARTUP_CARD_KEY,
+      startupCardLines({
+        cwd: ctx.cwd,
+        home: homedir(),
+        projectTrusted: ctx.isProjectTrusted(),
+      }),
+    );
+  });
+  pi.on("agent_start", (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setWidget(STARTUP_CARD_KEY, undefined);
+  });
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setWidget(STARTUP_CARD_KEY, undefined);
+  });
 }

package/src/install-config.d.mts

@@ -0,0 +1,6 @@
+export declare const CONFIG_TEMPLATE: string;
+
+export declare function ensureUserConfig(home?: string): {
+  created: boolean;
+  path: string;
+};

package/src/install-config.mjs

@@ -0,0 +1,57 @@
+import { closeSync, constants, mkdirSync, openSync, writeSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const CONFIG_TEMPLATE = `# Cadence research configuration. Keep this file local and never commit it.
+# Context7 works anonymously with its default URL.
+# CONTEXT7_API_URL=https://context7.com/api/v2
+# CONTEXT7_API_KEY=
+
+# Required when using the Grok search skill.
+GROK_API_URL=https://api.x.ai/v1
+GROK_API_KEY=
+
+# Optional Tavily integration.
+# TAVILY_ENABLED=true
+# TAVILY_API_URL=https://api.tavily.com
+# TAVILY_API_KEY=
+`;
+
+export function ensureUserConfig(home = homedir()) {
+  const directory = path.join(home, ".pi", "agent", "cadence");
+  const file = path.join(directory, ".env");
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    const fd = openSync(
+      file,
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL,
+      0o600,
+    );
+    try {
+      writeSync(fd, CONFIG_TEMPLATE, undefined, "utf8");
+    } finally {
+      closeSync(fd);
+    }
+    return { created: true, path: file };
+  } catch (error) {
+    if (error?.code === "EEXIST") return { created: false, path: file };
+    throw error;
+  }
+}
+
+if (
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))
+) {
+  try {
+    const result = ensureUserConfig();
+    if (result.created)
+      process.stderr.write(`Cadence created ${result.path}\n`);
+  } catch (error) {
+    process.stderr.write(
+      `Cadence could not create the user configuration template: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+    process.exitCode = 0;
+  }
+}

package/src/startup-card.ts

@@ -0,0 +1,84 @@
+import path from "node:path";
+import {
+  loadConfig,
+  selectConfigPath,
+} from "../skills/_shared/load-config.mjs";
+
+export const STARTUP_CARD_KEY = "cadence-configuration";
+
+// Only code-owned labels and paths enter the UI; never values, endpoints,
+// models, parser errors or credentials from the configuration file.
+function displayPath(value: string): string {
+  return JSON.stringify(value).slice(1, -1);
+}
+
+function validUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+export function startupCardLines(options: {
+  cwd: string;
+  home: string;
+  projectTrusted: boolean;
+}): string[] {
+  const lines = ["Cadence · 研究能力（仅本地配置检查，未联网验证）"];
+  if (!options.projectTrusted) {
+    return [
+      ...lines,
+      "尚未信任当前项目：未读取研究配置；信任项目后重新加载可查看状态。",
+      "不自动启动 Abel 工作流；请勿在聊天中发送 API Key。",
+    ];
+  }
+
+  let selectedPath: string | null = null;
+  try {
+    selectedPath = selectConfigPath(options);
+    const { values } = loadConfig({ ...options, allowMissing: true });
+    const context7 = !validUrl(
+      values.CONTEXT7_API_URL || "https://context7.com/api/v2",
+    )
+      ? "CONTEXT7_API_URL 格式无效"
+      : values.CONTEXT7_API_KEY
+        ? "已配置密钥"
+        : "匿名模式，无需密钥";
+    const missing = ["GROK_API_URL", "GROK_API_KEY"].filter(
+      (name) => !values[name],
+    );
+    const grok = missing.length
+      ? `待配置 ${missing.join("、")}`
+      : !validUrl(values.GROK_API_URL)
+        ? "GROK_API_URL 格式无效"
+        : "已配置";
+    const tavily =
+      values.TAVILY_ENABLED === "false"
+        ? "已关闭"
+        : !values.TAVILY_API_KEY
+          ? "未配置（可选）"
+          : !validUrl(values.TAVILY_API_URL || "https://api.tavily.com")
+            ? "TAVILY_API_URL 格式无效"
+            : "已配置（Grok Skill 仍需 Grok 配置）";
+    lines.push(
+      `文档查询 Context7：${context7}`,
+      `联网搜索 Grok：${grok}；Tavily：${tavily}`,
+    );
+  } catch {
+    lines.push("研究配置无法读取或解析：请检查下方文件；未回退到其他配置。");
+  }
+
+  const userPath = path.join(options.home, ".pi", "agent", "cadence", ".env");
+  const projectPath = path.join(options.cwd, ".pi", "cadence", ".env");
+  lines.push(
+    selectedPath
+      ? `生效文件：${displayPath(selectedPath)}${selectedPath === projectPath ? "（项目整文件优先，不合并用户配置）" : "（用户级，跨项目复用）"}`
+      : `配置位置：${displayPath(userPath)}（用户级，跨项目复用）`,
+    "在本地编辑该文件：GROK_API_URL=<服务地址>、GROK_API_KEY=<密钥>，每项一行；可选 TAVILY_API_KEY。",
+    "研究 Skills 不读取 shell API 变量；保存后下次调用生效。不要把密钥发到聊天或提交到 Git。",
+    "可选服务未配置不阻塞普通任务，也不自动启动 Abel 工作流。",
+  );
+  return lines;
+}