abelworkflow 1.1.3 → 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AbelWorkflow contributors
+
+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,6 +1,6 @@
 # AbelWorkflow
 
-AbelWorkflow 为 Codex、Claude Code 和 Pi 部署统一的 Skills、工作流命令、Agent 配置与扩展。
+AbelWorkflow 为 Codex、Claude Code 和 Pi 部署统一的 Skills、工作流命令、Agent 配置与 Pi Extensions。
 
 ## 环境要求
 
@@ -8,16 +8,14 @@ AbelWorkflow 为 Codex、Claude Code 和 Pi 部署统一的 Skills、工作流
 - npm 10 或兼容版本
 - Linux、macOS 或原生 Windows
 
-## 正式工作流命令
+## 工作流命令
 
 | 命令 | 用途 |
 | --- | --- |
 | `/abel-init` | 初始化 OpenSpec 环境并验证工具链 |
-| `/abel-design` | 通过双闸门澄清生成可实施、可验证规格 |
-| `/abel-implement` | 按强制 TDD 实施已批准变更 |
-| `/abel-diagnose` | 进行根因分析、回归测试和批量修复 |
-
-工作流：
+| `/abel-design` | 将需求整理为可实施、可验证的 OpenSpec 规格 |
+| `/abel-implement` | 按 Red → Green → Refactor 实施变更 |
+| `/abel-diagnose` | 基于证据定位根因并完成回归验证 |
 
 ```text
 /abel-init → /abel-design → /abel-implement(TDD)
@@ -28,48 +26,55 @@ OpenSpec 命令保持独立：`/opsx:propose`、`/opsx:explore`、`/opsx:apply`
 
 ## 安装与更新
 
-### npx
-
 ```bash
 npx abelworkflow
 npx abelworkflow install
 npx abelworkflow@latest
 ```
 
-无 TTY 的环境必须显式运行 `npx abelworkflow install`。安装器将工作流部署到 `~/.agents`，并维护 Claude、Codex 与 Pi 的链接。
+无 TTY 环境必须显式运行 `npx abelworkflow install`。安装器将工作流部署到 `~/.agents`，再为 Claude、Codex 与 Pi 建立链接。已有目标与托管内容冲突时，安装会失败并保留原内容；确认目标后再处理冲突。
 
 ### 源码安装
 
-源码目录和部署目录必须分离，不能相同或互相嵌套。推荐流程：
+源码目录与部署目录必须分离，不能相同或互相嵌套。不要把源码仓库直接克隆到 `~/.agents`。
 
 ```bash
 git clone https://github.com/abelxiaoxing/AbelWorkflow ~/src/AbelWorkflow
 cd ~/src/AbelWorkflow
 npm ci
 npm ci --prefix skills/dev-browser
-npm run build
+npm run build --prefix skills/dev-browser
 node bin/abelworkflow.mjs install --agents-dir ~/.agents
 ```
 
-Windows PowerShell 可将源码克隆到 `$HOME\src\AbelWorkflow`，然后运行相同的 npm 命令，并使用：
+Windows PowerShell 使用独立源码目录，并显式指定部署目录：
 
 ```powershell
 node .\bin\abelworkflow.mjs install --agents-dir "$HOME\.agents"
 ```
 
-不要把源码仓库直接克隆到 `~/.agents`。已有这种布局时，先按 [1.0 迁移指南](https://github.com/abelxiaoxing/AbelWorkflow/blob/master/docs/migration-1.0.md) 人工建立独立源码目录；安装器不会猜测性移动或删除用户数据。
+### 可选 Skill 依赖
 
-## 配置行为
+源码安装需按上方命令在同步前构建 dev-browser。同步后如需使用 dev-browser，还需在部署目录中显式安装运行依赖；Time 独立 CLI 需要 Python 3.9+，Windows 还需 `tzdata` 提供 IANA 时区；Grok 依赖安装到用户自行选择的 Python 环境。普通运行不会自动安装依赖或浏览器：
+
+```bash
+npm ci --omit=dev --prefix ~/.agents/skills/dev-browser
+node ~/.agents/skills/dev-browser/node_modules/playwright/cli.js install chromium
+python -m pip install tzdata
+python -m pip install -r skills/grok-search/requirements.txt
+```
+
+部署后的 Skill 目录在普通运行时按只读处理。显式 Skill 密钥配置会写入部署目录的 `.env`；临时文件、浏览器 profile、虚拟环境和其他运行状态应放在操作系统临时目录或用户数据目录。
 
-- Claude 配置默认写入 `bypassPermissions` 全权限模式（YOLO），第三方 API 仅使用 API Key 认证，不添加任何 MCP 权限。已有 permissions、deny、hooks 和 timeout 保持不变。
-- Codex 只更新 AbelWorkflow 管理的认证字段，保留未知字段、其他 Provider 和用户 token。
-- Pi 0.80.0 及以上版本按无会话启动时实际选中的当前有效 Provider 配置 API；首次使用且 Pi 明确没有可用模型时，引导创建 `gpt` 自定义 Provider。API Key 保存在 `~/.pi/agent/auth.json`，`models.json` 只保留模型定义；旧 models-only key 会按先写 auth、后删除旧 key 的顺序迁移。
-- Grok 默认模型统一为 `grok-4.20-non-reasoning`。
-- Context7 使用显式 CommonJS 入口 `context7-api.cjs`。
-- dev-browser 发布运行时使用 Node ESM 编译产物，入口为 `node dist/scripts/start.js`，不依赖 Bun 或运行时 `npx tsx`。
-- skill 密钥写入 `~/.agents/skills/<skill>/.env`；这些文件属于私密配置。
+## 配置行为
 
-`.skill-lock.json` 完全属于用户：安装器不读取、不修改、不备份、不删除，也不会把它放入发布包。
+- Claude 配置管理 `ANTHROPIC_BASE_URL`、`ANTHROPIC_API_KEY` 与 `ANTHROPIC_MODEL`；冲突的 `ANTHROPIC_AUTH_TOKEN` 会被删除，其他模型路由保持不变。
+- Codex 配置管理 AbelWorkflow Provider 路由、`OPENAI_API_KEY` 与 `auth_mode`，清理冲突的 `preferred_auth_method`、`temp_env_key` 及目标 Provider 旧路由字段，保留其他认证字段。
+- Pi 配置更新 `abelworkflow` Provider、对应凭据及全局 `defaultProvider`、`defaultModel`，保留其他 Provider 与无关设置。
+- API 配置不注入全局权限；配置结构或路径无法安全合并时直接失败。
+- Skill 密钥写入 `~/.agents/skills/<skill>/.env`，属于用户私密配置。
+- `.skill-lock.json` 完全属于用户：安装器不读取、不修改、不备份、不删除，也不会将其放入发布包。
+- 自定义 CA 应通过标准证书环境变量显式配置，不关闭 TLS 校验。
 
 ## 部署映射
 
@@ -78,11 +83,11 @@ node .\bin\abelworkflow.mjs install --agents-dir "$HOME\.agents"
 | 工作流 AGENTS 模板 | `~/.claude/CLAUDE.md` | `~/.codex/AGENTS.md` | `~/.pi/agent/AGENTS.md` |
 | `skills/<skill>/` | `~/.claude/skills/<skill>/` | `~/.codex/skills/<skill>/` | `~/.pi/agent/skills/<skill>/` |
 | `abel-*.md` 命令 | `~/.claude/commands/` | `~/.codex/prompts/` | `~/.pi/agent/prompts/` |
-| `extensions/*` | — | — | `~/.pi/agent/extensions/` |
+| `extensions/*` | — | — | `~/.agents/extensions/` → `~/.pi/agent/extensions/` |
 
 ## 自签名 HTTPS 中转
 
-优先取得中转的 CA PEM，并在启动客户端前配置：
+取得中转的 CA PEM 后，在启动客户端前配置：
 
 ```bash
 export NODE_EXTRA_CA_CERTS=/absolute/path/relay-ca.pem
@@ -90,7 +95,3 @@ export CODEX_CA_CERTIFICATE=/absolute/path/relay-ca.pem
 ```
 
 不要全局设置 `NODE_TLS_REJECT_UNAUTHORIZED=0`。证书过期或主机名不匹配时应重新签发证书。
-
-## 升级
-
-从 0.x 升级前请阅读 [AbelWorkflow 1.0 迁移指南](https://github.com/abelxiaoxing/AbelWorkflow/blob/master/docs/migration-1.0.md)。指南涵盖源码/部署目录拆分、metadata v2、Provider 配置、用户状态、dev-browser 和回滚。

package/extensions/gpt-responses-compat.ts

@@ -0,0 +1,213 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type JsonRecord = Record<string, any>;
+
+const DEFAULT_INSTRUCTIONS = "You are a helpful assistant.";
+const RESPONSES_API = "openai-responses";
+const RESPONSES_PROVIDERS = new Set(["abelworkflow", "gpt"]);
+const UNSUPPORTED_SPARK_REASONING_EFFORTS = new Set(["none", "minimal"]);
+const TRANSIENT_UPSTREAM_ERROR = /\bupstream(?:[_ -]error|\s+request\s+failed)\b/i;
+const EXPLICIT_ERROR_STATUS = /(?:^\s*|\b(?:upstream(?:[_ -]error|\s+request\s+failed)|code|error(?:[_ -]?code)?|http(?:\/\d+(?:\.\d+)*)?(?:[_ -]?status(?:[_ -]?code)?)?|status(?:[_ -]?code)?)\b\s*["']?\s*[:=(]?\s*)["']?([45]\d{2})["']?(?!\d)/i;
+
+function isRecord(value: unknown): value is JsonRecord {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function isCompatibleResponsesModel(model: unknown): boolean {
+  return isRecord(model) &&
+    model.api === RESPONSES_API &&
+    RESPONSES_PROVIDERS.has(model.provider);
+}
+
+function textFromContent(content: unknown): string | undefined {
+  if (typeof content === "string") return content.trim() || undefined;
+  if (!Array.isArray(content)) return undefined;
+
+  const text = content
+    .map((part) => {
+      if (!isRecord(part)) return "";
+      if (typeof part.text === "string") return part.text;
+      if (typeof part.refusal === "string") return part.refusal;
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n")
+    .trim();
+
+  return text || undefined;
+}
+
+function normalizeUserContent(content: unknown): unknown {
+  if (typeof content === "string") {
+    return [{ type: "input_text", text: content }];
+  }
+
+  if (!Array.isArray(content)) return content;
+
+  return content
+    .map((part) => {
+      if (!isRecord(part)) return undefined;
+      if (part.type === "input_text" && typeof part.text === "string") {
+        return { type: "input_text", text: part.text };
+      }
+      if (part.type === "input_image" && typeof part.image_url === "string") {
+        return {
+          type: "input_image",
+          image_url: part.image_url,
+          ...(typeof part.detail === "string" ? { detail: part.detail } : {}),
+        };
+      }
+      return undefined;
+    })
+    .filter(Boolean);
+}
+
+function normalizeAssistantContent(content: unknown): unknown {
+  if (typeof content === "string") {
+    return [{ type: "output_text", text: content, annotations: [] }];
+  }
+
+  if (!Array.isArray(content)) return content;
+
+  return content
+    .map((part) => {
+      if (!isRecord(part)) return undefined;
+      if (part.type === "output_text" && typeof part.text === "string") {
+        return { type: "output_text", text: part.text, annotations: [] };
+      }
+      if (part.type === "refusal" && typeof part.refusal === "string") {
+        return { type: "refusal", refusal: part.refusal };
+      }
+      return undefined;
+    })
+    .filter(Boolean);
+}
+
+function normalizeInputItem(item: unknown): unknown {
+  if (!isRecord(item)) return undefined;
+
+  // The Codex passthrough endpoint requires the prompt in `instructions`.
+  // Replaying developer/system messages inside `input` is redundant and can
+  // confuse proxies that only partially implement the Responses API.
+  if (item.role === "system" || item.role === "developer") return undefined;
+
+  // Reasoning items contain model-bound encrypted payloads. They are unsafe to
+  // replay when switching between GPT/Codex variants and are a common cause of
+  // upstream 5xx errors from passthrough providers. Dropping them preserves all
+  // visible conversation text and tool state.
+  if (item.type === "reasoning") return undefined;
+
+  if (item.type === "message") {
+    const content = normalizeAssistantContent(item.content);
+    if (Array.isArray(content) && content.length === 0) return undefined;
+    return { role: "assistant", content };
+  }
+
+  if (item.role === "user") {
+    const content = normalizeUserContent(item.content);
+    if (Array.isArray(content) && content.length === 0) return undefined;
+    return { role: "user", content };
+  }
+
+  if (item.role === "assistant") {
+    const content = normalizeAssistantContent(item.content);
+    if (Array.isArray(content) && content.length === 0) return undefined;
+    return { role: "assistant", content };
+  }
+
+  if (item.type === "function_call") {
+    if (typeof item.call_id !== "string" || typeof item.name !== "string") return undefined;
+    return {
+      type: "function_call",
+      call_id: item.call_id,
+      name: item.name,
+      arguments: typeof item.arguments === "string" ? item.arguments : JSON.stringify(item.arguments ?? {}),
+    };
+  }
+
+  if (item.type === "function_call_output") {
+    if (typeof item.call_id !== "string") return undefined;
+    return {
+      type: "function_call_output",
+      call_id: item.call_id,
+      output: Array.isArray(item.output) ? normalizeUserContent(item.output) : String(item.output ?? ""),
+    };
+  }
+
+  return item;
+}
+
+function normalizeInput(input: unknown): unknown[] {
+  const rawItems = Array.isArray(input)
+    ? input
+    : typeof input === "string"
+      ? [{ role: "user", content: input }]
+      : isRecord(input)
+        ? [input]
+        : [];
+
+  return rawItems.map(normalizeInputItem).filter((item) => item !== undefined);
+}
+
+function normalizeReasoning(payload: JsonRecord, modelId: string | undefined): void {
+  if (modelId !== "gpt-5.3-codex-spark") return;
+  if (!isRecord(payload.reasoning)) return;
+  if (!UNSUPPORTED_SPARK_REASONING_EFFORTS.has(payload.reasoning.effort)) return;
+
+  payload.reasoning = { ...payload.reasoning, effort: "low" };
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("before_provider_request", (event, ctx) => {
+    const payload = event.payload as unknown;
+    if (!isRecord(payload)) return;
+    if (!isCompatibleResponsesModel(ctx.model)) return;
+
+    const input = normalizeInput(payload.input);
+    const first = Array.isArray(payload.input) ? payload.input.find(isRecord) : undefined;
+    const firstIsPrompt = first?.role === "system" || first?.role === "developer";
+    const instructions =
+      textFromContent(payload.instructions) ||
+      (firstIsPrompt ? textFromContent(first.content) : undefined) ||
+      ctx.getSystemPrompt().trim() ||
+      DEFAULT_INSTRUCTIONS;
+
+    const nextPayload: JsonRecord = { ...payload, instructions, input, store: false };
+
+    // Unsupported or risky for this Codex passthrough endpoint.
+    delete nextPayload.max_output_tokens;
+    delete nextPayload.prompt_cache_key;
+    delete nextPayload.prompt_cache_retention;
+    delete nextPayload.previous_response_id;
+
+    normalizeReasoning(nextPayload, ctx.model?.id);
+
+    return nextPayload;
+  });
+
+  pi.on("message_end", (event, ctx) => {
+    const message = event.message;
+    if (
+      message.role !== "assistant" ||
+      message.stopReason !== "error" ||
+      !isCompatibleResponsesModel(ctx.model)
+    ) {
+      return;
+    }
+
+    const errorMessage = message.errorMessage ?? "";
+    if (
+      EXPLICIT_ERROR_STATUS.test(errorMessage) ||
+      !TRANSIENT_UPSTREAM_ERROR.test(errorMessage)
+    ) {
+      return;
+    }
+
+    return {
+      message: {
+        ...message,
+        errorMessage: `503 ${errorMessage}`,
+      },
+    };
+  });
+}

package/extensions/k2think-compat.ts

@@ -0,0 +1,40 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type JsonRecord = Record<string, unknown>;
+
+const MODEL_ID = "MBZUAI-IFM/K2-Think-v2";
+
+function isRecord(value: unknown): value is JsonRecord {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeTextContent(content: unknown): unknown {
+  if (!Array.isArray(content)) return content;
+  if (
+    !content.every(
+      (part) =>
+        isRecord(part) &&
+        part.type === "text" &&
+        typeof part.text === "string",
+    )
+  ) {
+    return content;
+  }
+
+  return content.map((part) => part.text).join("");
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("before_provider_request", (event, ctx) => {
+    if (ctx.model?.provider !== "ifm" || ctx.model.id !== MODEL_ID) return;
+    if (!isRecord(event.payload) || !Array.isArray(event.payload.messages)) return;
+
+    return {
+      ...event.payload,
+      messages: event.payload.messages.map((message) => {
+        if (!isRecord(message)) return message;
+        return { ...message, content: normalizeTextContent(message.content) };
+      }),
+    };
+  });
+}

package/lib/cli/args.mjs

@@ -1,9 +1,7 @@
-function parseArgs(argv, { defaultAgentsDir, resolvePath, env = process.env }) {
+function parseArgs(argv, { defaultAgentsDir, resolvePath }) {
   const options = {
     agentsDir: defaultAgentsDir,
     force: false,
-    relinkOnly: false,
-    nonInteractive: false,
     command: "menu"
   };
   const positional = [];
@@ -15,23 +13,15 @@ function parseArgs(argv, { defaultAgentsDir, resolvePath, env = process.env }) {
       options.force = true;
       continue;
     }
-    if (arg === "--link-only") {
-      options.relinkOnly = true;
-      continue;
-    }
     if (arg === "--agents-dir") {
       const value = argv[i + 1];
-      if (!value) {
+      if (!value || value.startsWith("-")) {
         throw new Error("--agents-dir requires a path");
       }
       options.agentsDir = resolvePath(value);
       i += 1;
       continue;
     }
-    if (arg === "--non-interactive") {
-      options.nonInteractive = true;
-      continue;
-    }
     if (arg === "--help" || arg === "-h" || arg === "help") {
       helpRequested = true;
       options.command = "help";
@@ -57,17 +47,13 @@ function parseArgs(argv, { defaultAgentsDir, resolvePath, env = process.env }) {
     }
   }
 
-  if (options.command !== "install" && (options.force || options.relinkOnly || options.agentsDir !== defaultAgentsDir)) {
-    throw new Error("`--force`、`--link-only`、`--agents-dir` 仅能与 `install` 命令一起使用");
+  if (options.command !== "install" && (options.force || options.agentsDir !== defaultAgentsDir)) {
+    throw new Error("`--force`、`--agents-dir` 仅能与 `install` 命令一起使用");
   }
-  if (!options.nonInteractive && env.CI) options.nonInteractive = true;
   return options;
 }
 
-function assertInteractiveMenuSupported({ command, inputIsTTY, outputIsTTY, nonInteractive }) {
-  if (command === "menu" && nonInteractive) {
-    throw new Error("非交互模式已启用；请显式使用 `npx abelworkflow install` 进行安装");
-  }
+function assertInteractiveMenuSupported({ command, inputIsTTY, outputIsTTY }) {
   if (command === "menu" && (!inputIsTTY || !outputIsTTY)) {
     throw new Error("交互式菜单需要 TTY 终端；非交互场景请显式使用 `npx abelworkflow install`");
   }