abelworkflow 0.9.1 → 1.0.0-rc.1

package/README.md

@@ -1,207 +1,97 @@
 # AbelWorkflow
 
-Codex、OpenCode、Claude Code、Pi 的 Skills、Commands/Prompts 和扩展配置仓库。
+AbelWorkflow 为 Codex、Claude Code 和 Pi 部署统一的 Skills、工作流命令、Agent 配置与扩展。
 
-## 目录结构
+## 环境要求
 
-```
-.agents/
-├── skills/              # 技能目录
-│   ├── time/                    # 时间与时区工具
-│   ├── grok-search/             # 增强型网页搜索
-│   ├── sequential-think/        # 多步推理引擎
-│   ├── dev-browser/             # 浏览器自动化
-│   ├── context7-auto-research/   # 自动文档检索
-│   ├── confidence-check/        # 实施前信心评估
-│   ├── git-commit/            # Git 提交助手
-│   └── prompt-enhancer/     # 提示词优化器
-├── commands/           # 命令目录
-│   └── oc/                # 工作流命令
-├── extensions/         # Pi 扩展
-├── AGENTS.md         # Agent 全局系统 prompts
-└── README.md
-```
-
-## 技能概览
+- Node.js 22 或更高版本
+- npm 10 或兼容版本
+- Linux、macOS 或原生 Windows
 
-| 技能 | 描述 |
-|------|------|
-| **time** | 时间和时区工具，获取当前时间及时区转换 |
-| **grok-search** | 通过 Grok API 增强网页搜索与实时内容检索 |
-| **sequential-think** | 多步推理引擎，支持假设检验与分支的复杂分析 |
-| **dev-browser** | 浏览器自动化，支持导航、表单填写、截图与数据提取 |
-| **context7-auto-research** | 自动从 Context7 获取最新库/框架文档 |
-| **confidence-check** | 实施前置信度评估（≥90%），含架构合规与根因识别 |
-| **git-commit** | Conventional Commits 规范提交，智能暂存与消息生成 |
-| **prompt-enhancer** | CoT 推理优化 AI 编码提示词，模糊请求转结构化指令 |
+## 正式工作流命令
 
-## 命令概览
+| 命令 | 用途 |
+| --- | --- |
+| `/abel-init` | 初始化 OpenSpec 环境并验证工具链 |
+| `/abel-research` | 研究需求并生成约束，不实施代码 |
+| `/abel-plan` | 将已确认变更细化为可执行计划 |
+| `/abel-implement` | 按强制 TDD 实施已批准变更 |
+| `/abel-diagnose` | 进行根因分析、回归测试和批量修复 |
 
-| 命令 | 描述 |
-|------|------|
-| **/oc:init** | 初始化 OpenSpec 环境并验证工具链 |
-| **/oc:research** | 结构化需求探索与约束集生成（不实施） |
-| **/oc:plan** | 将已批准变更细化为零决策可执行方案 |
-| **/oc:implementation** | 以 TDD 方式实施已批准的变更 |
-| **/oc:diagnose** | 系统化根因分析与批量修复报告 |
+工作流：
 
-## 工作流
-
-```
-/oc:init → /oc:research → /oc:plan → /oc:implementation(TDD)
-                                   ↘ /oc:diagnose (bug fix)
+```text
+/abel-init → /abel-research → /abel-plan → /abel-implement(TDD)
+                                      ↘ /abel-diagnose (bug fix)
 ```
 
-## 配置说明
-
-- **目录位置**:
-  - Linux/macOS: `~/.agents/`
-  - Windows: `%USERPROFILE%\.agents\`（PowerShell: `$HOME\.agents`）
-- **AGENTS.md**: Agent 全局系统 prompts 配置
+OpenSpec 命令保持独立：`/opsx:new`、`/opsx:ff`、`/opsx:archive`、`openspec view`、`openspec status`。
 
 ## 安装与更新
 
-### 方法一：npx 一键安装（推荐）
+### npx
 
 ```bash
-# 交互式初始化菜单
 npx abelworkflow
-
-# 直接执行工作流同步/重链
 npx abelworkflow install
-
-# 更新到最新发布版本
 npx abelworkflow@latest
 ```
 
-> 说明：
-> - npm 发布包名必须使用小写，所以实际可执行命令是 `npx abelworkflow`。
-> - 交互式模式下，默认会打开初始化菜单，支持：
->   - 同步 `~/.agents` 并自动重建 `~/.claude` / `~/.codex` / `~/.pi/agent` 链接
->   - 交互式填写 `grok-search`、`context7-auto-research`、`prompt-enhancer` 的 `.env`
->   - 一键安装或更新 `Claude Code`、`Codex`、`Pi`
->   - 配置 `Claude Code` 的第三方 API 到 `~/.claude/settings.json`
->   - 配置 `Codex` 的第三方 API 到 `~/.codex/config.toml` 和 `~/.codex/auth.json`
->   - 配置 `Pi` 的自定义 API 到 `~/.pi/agent/models.json` 中的 `gpt` provider，并设置 `~/.pi/agent/settings.json` 默认模型，同时携带 Pi 扩展
-> - 非交互场景请显式使用 `npx abelworkflow install`，不再保留旧的默认自动同步逻辑。
+无 TTY 的环境必须显式运行 `npx abelworkflow install`。安装器将工作流部署到 `~/.agents`，并维护 Claude、Codex 与 Pi 的链接。
 
-### 交互式初始化能力
+### 源码安装
 
-`npx abelworkflow` 现在默认提供一个类似 `npx zcf` 的菜单，常见入口包括：
+源码目录和部署目录必须分离，不能相同或互相嵌套。推荐流程：
 
 ```bash
-npx abelworkflow
-npx abelworkflow init
-npx abelworkflow install
-npx abelworkflow --help
+git clone https://github.com/abelxiaoxing/AbelWorkflow ~/src/AbelWorkflow
+cd ~/src/AbelWorkflow
+npm ci
+npm ci --prefix skills/dev-browser
+npm run build
+node bin/abelworkflow.mjs install --agents-dir ~/.agents
 ```
 
-其中完整初始化会按需引导你完成：
-
-1. 安装 AbelWorkflow 到 `~/.agents`
-2. 自动链接到 `~/.claude/`、`~/.codex/` 和 `~/.pi/agent/`
-3. 可选安装 `Claude Code` CLI
-4. 可选配置 `Claude Code` 第三方 API
-5. 可选安装 `Codex` CLI
-6. 可选配置 `Codex` 第三方 API
-7. 可选安装 `Pi` CLI
-8. 可选配置 Pi `gpt` provider 自定义 API，并链接 Pi 扩展
-9. 可选填写三个技能的环境变量
-
-### 技能环境写入位置
-
-交互式配置会把技能密钥写到 `~/.agents` 下对应 skill 目录的 `.env` 中：
-
-| 技能 | 写入位置 | 主要字段 |
-|---|---|---|
-| `grok-search` | `~/.agents/skills/grok-search/.env` | `GROK_API_URL` `GROK_API_KEY` `GROK_MODEL` |
-| `context7-auto-research` | `~/.agents/skills/context7-auto-research/.env` | `CONTEXT7_API_KEY` |
-| `prompt-enhancer` | `~/.agents/skills/prompt-enhancer/.env` | `PE_API_URL` `PE_API_KEY` `PE_MODEL` |
-
-### 方法二：源码克隆安装
-
-如需自定义修改或贡献代码，可手动克隆后直接运行本地 CLI：
-
-#### 1. 克隆仓库
-
-**Linux/macOS（bash/zsh）**
-
-```bash
-# 首次安装
-git clone https://github.com/abelxiaoxing/AbelWorkflow ~/.agents
-
-# 更新
-git -C ~/.agents pull
-```
-
-**Windows（PowerShell）**
-
-```powershell
-# 首次安装
-git clone https://github.com/abelxiaoxing/AbelWorkflow "$HOME\.agents"
-
-# 更新
-git -C "$HOME\.agents" pull
-```
-
-#### 2. 执行本地初始化
-
-**Linux/macOS（bash/zsh）**
-
-```bash
-cd ~/.agents
-node bin/abelworkflow.mjs
-```
-
-**Windows（PowerShell）**
+Windows PowerShell 可将源码克隆到 `$HOME\src\AbelWorkflow`，然后运行相同的 npm 命令，并使用：
 
 ```powershell
-Set-Location "$HOME\.agents"
-node .\bin\abelworkflow.mjs
+node .\bin\abelworkflow.mjs install --agents-dir "$HOME\.agents"
 ```
 
-如果只想重建链接，不进入菜单：
-
-**Linux/macOS（bash/zsh）**
+不要把源码仓库直接克隆到 `~/.agents`。已有这种布局时，先按 [1.0 迁移指南](https://github.com/abelxiaoxing/AbelWorkflow/blob/master/docs/migration-1.0.md) 人工建立独立源码目录；安装器不会猜测性移动或删除用户数据。
 
-```bash
-cd ~/.agents
-node bin/abelworkflow.mjs install
-```
+## 配置行为
 
-**Windows（PowerShell）**
+- Claude 默认使用 `standard` 权限档，不预授权 Bash、Write 或 Edit；只有用户明确选择 `trusted` 才增加宽权限。已有 permissions、deny、hooks 和 timeout 保持不变。
+- Codex 只更新 AbelWorkflow 管理的认证字段，保留未知字段、其他 Provider 和用户 token。
+- Pi 0.80.0 及以上版本将 GPT API Key 保存在 `~/.pi/agent/auth.json`；`models.json` 只保留模型定义。旧 models-only key 会按先写 auth、后删除旧 key 的顺序迁移。
+- Grok 默认模型统一为 `grok-4.20-auto`。
+- Context7 使用显式 CommonJS 入口 `context7-api.cjs`。
+- dev-browser 发布运行时使用 Node ESM 编译产物，入口为 `node dist/scripts/start.js`，不依赖 Bun 或运行时 `npx tsx`。
+- skill 密钥写入 `~/.agents/skills/<skill>/.env`；这些文件属于私密配置。
 
-```powershell
-Set-Location "$HOME\.agents"
-node .\bin\abelworkflow.mjs install
-```
+`.skill-lock.json` 完全属于用户：安装器不读取、不修改、不备份、不删除，也不会把它放入发布包。
 
-### 映射关系（本仓库 → 配置目录）
+## 部署映射
 
-| 本仓库 | Claude Code | Codex | Pi | 说明 |
-|---|---|---|---|---|
-| `AGENTS.md` | `~/.claude/CLAUDE.md` | `~/.codex/AGENTS.md` | `~/.pi/agent/AGENTS.md` | 全局系统提示词/规则 |
-| `skills/<skill>/` | `~/.claude/skills/<skill>/` | `~/.codex/skills/<skill>/` | `~/.pi/agent/skills/<skill>/` | Skills（每个目录一个技能） |
-| `commands/abel-*.md` | `~/.claude/commands/abel-*.md` | `~/.codex/prompts/abel-*.md` | `~/.pi/agent/prompts/abel-*.md` | 扁平化部署，避免命名冲突 |
-| `extensions/*.ts` | - | - | `~/.pi/agent/extensions/*.ts` | Pi 扩展 |
+| 托管内容 | Claude Code | Codex | Pi |
+| --- | --- | --- | --- |
+| 工作流 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/` |
 
-### 验证（可选）
+## 自签名 HTTPS 中转
 
-**Linux/macOS（bash/zsh）**
+优先取得中转的 CA PEM，并在启动客户端前配置：
 
 ```bash
-ls -la "$HOME/.claude/CLAUDE.md" "$HOME/.claude/commands/"abel-*.md
-ls -la "$HOME/.codex/AGENTS.md" "$HOME/.codex/prompts/"abel-*.md
-cat "$HOME/.claude/settings.json" | head
-cat "$HOME/.codex/config.toml" | head
+export NODE_EXTRA_CA_CERTS=/absolute/path/relay-ca.pem
+export CODEX_CA_CERTIFICATE=/absolute/path/relay-ca.pem
 ```
 
-**Windows（PowerShell）**
+不要全局设置 `NODE_TLS_REJECT_UNAUTHORIZED=0`。证书过期或主机名不匹配时应重新签发证书。
 
-```powershell
-Get-Item "$HOME\.claude\CLAUDE.md"; Get-ChildItem "$HOME\.claude\commands\abel-*.md"
-Get-Item "$HOME\.codex\AGENTS.md"
-Get-ChildItem "$HOME\.codex\prompts\abel-*.md"
-Get-Content "$HOME\.claude\settings.json" -TotalCount 10
-Get-Content "$HOME\.codex\config.toml" -TotalCount 10
-```
+## 升级
+
+从 0.x 升级前请阅读 [AbelWorkflow 1.0 迁移指南](https://github.com/abelxiaoxing/AbelWorkflow/blob/master/docs/migration-1.0.md)。指南涵盖源码/部署目录拆分、metadata v2、Provider 配置、用户状态、dev-browser 和回滚。

package/bin/abelworkflow.mjs

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
-import { main } from "../lib/cli.mjs";
+import { main } from "../lib/cli/main.mjs";
 
-main().catch((error) => {
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}).catch((error) => {
   console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
+  process.exitCode = 1;
 });

package/extensions/{pi-gpt-responses-compat.ts → pi-gpt-responses-compat/index.ts}

@@ -1,6 +1,23 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createNodeInsecureDispatcher, installProviderTlsFetch } from "./tls-fetch.mjs";
+
+let nodeInsecureDispatcher: unknown;
+
+function getNodeInsecureDispatcher() {
+  if (nodeInsecureDispatcher) return nodeInsecureDispatcher;
+  nodeInsecureDispatcher = createNodeInsecureDispatcher();
+  return nodeInsecureDispatcher;
+}
 
 export default function (pi: ExtensionAPI) {
+  if (typeof globalThis.fetch === "function") {
+    const runtime = typeof (globalThis as any).Bun === "undefined" ? "node" : "bun";
+    installProviderTlsFetch({
+      runtime,
+      insecureDispatcher: runtime === "node" ? getNodeInsecureDispatcher : undefined
+    });
+  }
+
   pi.on("before_provider_request", (event, ctx) => {
     const payload = event.payload as any;
     if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;

package/extensions/pi-gpt-responses-compat/tls-fetch.mjs

@@ -0,0 +1,188 @@
+export const piInsecureTlsHeader = "x-abelworkflow-insecure-tls";
+
+const installedFetchMarker = Symbol.for("abelworkflow.pi-provider-tls-fetch");
+const undiciGlobalDispatchers = [
+  Symbol.for("undici.globalDispatcher.2"),
+  Symbol.for("undici.globalDispatcher.1")
+];
+const redirectStatuses = new Set([301, 302, 303, 307, 308]);
+const maxRedirects = 5;
+
+function getMarkedHeaders(input, init) {
+  const source = init?.headers !== undefined
+    ? init.headers
+    : typeof Request !== "undefined" && input instanceof Request
+      ? input.headers
+      : undefined;
+  if (source === undefined) return null;
+
+  const headers = new Headers(source);
+  if (!headers.has(piInsecureTlsHeader)) return null;
+  const allowedOrigin = headers.get(piInsecureTlsHeader);
+  headers.delete(piInsecureTlsHeader);
+  return { allowedOrigin, headers };
+}
+
+function getRequestUrl(input) {
+  return typeof Request !== "undefined" && input instanceof Request
+    ? input.url
+    : input instanceof URL
+      ? input.href
+      : input;
+}
+
+function getRequestOrigin(input) {
+  try {
+    return new URL(getRequestUrl(input)).origin;
+  } catch {
+    return null;
+  }
+}
+
+function redirectRequestInit(input, init, status) {
+  const method = String(init.method ?? (
+    typeof Request !== "undefined" && input instanceof Request ? input.method : "GET"
+  )).toUpperCase();
+  const switchToGet = status === 303 && method !== "HEAD"
+    || (status === 301 || status === 302) && method === "POST";
+  if (!switchToGet) {
+    if (typeof Request !== "undefined" && input instanceof Request && method !== "GET" && method !== "HEAD") {
+      throw new Error("Pi insecure TLS cannot safely replay a redirected Request body");
+    }
+    return init;
+  }
+
+  const headers = new Headers(init.headers);
+  for (const name of ["content-encoding", "content-language", "content-length", "content-location", "content-type"]) {
+    headers.delete(name);
+  }
+  const nextInit = { ...init, method: "GET", headers };
+  delete nextInit.body;
+  return nextInit;
+}
+
+async function fetchWithSameOriginRedirects({ fetchOnce, input, init, allowedOrigin }) {
+  let nextInput = input;
+  let nextInit = init;
+
+  for (let redirectCount = 0; redirectCount <= maxRedirects; redirectCount += 1) {
+    const response = await fetchOnce(nextInput, nextInit);
+    const location = redirectStatuses.has(response?.status) ? response.headers?.get?.("location") : null;
+    if (!location) return response;
+    if (redirectCount === maxRedirects) {
+      await response.body?.cancel?.();
+      throw new Error(`Pi insecure TLS exceeded ${maxRedirects} same-origin redirects`);
+    }
+
+    const target = new URL(location, getRequestUrl(nextInput));
+    if (target.origin !== allowedOrigin) {
+      await response.body?.cancel?.();
+      throw new Error(`Pi insecure TLS blocked cross-origin redirect to ${target.origin}`);
+    }
+    await response.body?.cancel?.();
+    nextInit = redirectRequestInit(nextInput, nextInit, response.status);
+    nextInput = target.href;
+  }
+}
+
+function applyNodeDispatcher(fetchImpl, input, init, dispatcherSource) {
+  let dispatcher;
+  try {
+    dispatcher = typeof dispatcherSource === "function" ? dispatcherSource() : dispatcherSource;
+  } catch (error) {
+    return Promise.reject(error);
+  }
+
+  if (dispatcher && typeof dispatcher.then === "function") {
+    return dispatcher.then((resolved) => applyNodeDispatcher(fetchImpl, input, init, resolved));
+  }
+  if (!dispatcher || typeof dispatcher.dispatch !== "function") {
+    return Promise.reject(new Error("Pi insecure TLS requires an injected Undici dispatcher"));
+  }
+  return fetchImpl(input, { ...init, dispatcher });
+}
+
+function getUndiciDispatcherConstructor(target) {
+  return undiciGlobalDispatchers
+    .map((symbol) => target[symbol]?.constructor)
+    .find((constructor) => typeof constructor === "function");
+}
+
+function initializeUndiciGlobalDispatcher(target) {
+  if (typeof target.fetch !== "function") return;
+  try {
+    void Promise.resolve(target.fetch("data:,")).catch(() => {});
+  } catch {
+  }
+}
+
+export function createNodeInsecureDispatcher(target = globalThis) {
+  let Dispatcher = getUndiciDispatcherConstructor(target);
+  if (typeof Dispatcher !== "function") {
+    initializeUndiciGlobalDispatcher(target);
+    Dispatcher = getUndiciDispatcherConstructor(target);
+  }
+  if (typeof Dispatcher !== "function") {
+    throw new Error("Pi insecure TLS requires the active Undici dispatcher");
+  }
+  return new Dispatcher({
+    allowH2: false,
+    connect: { rejectUnauthorized: false },
+    requestTls: { rejectUnauthorized: false }
+  });
+}
+
+export function createProviderTlsFetch({
+  fetchImpl = globalThis.fetch,
+  runtime = typeof globalThis.Bun === "undefined" ? "node" : "bun",
+  insecureDispatcher
+} = {}) {
+  if (typeof fetchImpl !== "function") {
+    throw new TypeError("A fetch implementation is required");
+  }
+
+  return function providerTlsFetch(input, init) {
+    const marked = getMarkedHeaders(input, init);
+    if (!marked) return fetchImpl(input, init);
+
+    const nextInit = { ...(init ?? {}), headers: marked.headers };
+    if (!marked.allowedOrigin || getRequestOrigin(input) !== marked.allowedOrigin) {
+      return fetchImpl(input, nextInit);
+    }
+
+    nextInit.redirect = "manual";
+    const fetchOnce = runtime === "bun"
+      ? (nextInput, redirectInit) => {
+          const tls = redirectInit.tls && typeof redirectInit.tls === "object" ? redirectInit.tls : {};
+          return fetchImpl(nextInput, {
+            ...redirectInit,
+            tls: { ...tls, rejectUnauthorized: false }
+          });
+        }
+      : (nextInput, redirectInit) => applyNodeDispatcher(
+          fetchImpl,
+          nextInput,
+          redirectInit,
+          insecureDispatcher
+        );
+
+    return fetchWithSameOriginRedirects({
+      fetchOnce,
+      input,
+      init: nextInit,
+      allowedOrigin: marked.allowedOrigin
+    });
+  };
+}
+
+export function installProviderTlsFetch({ target = globalThis, ...options } = {}) {
+  if (target.fetch?.[installedFetchMarker]) return target.fetch;
+
+  const wrapped = createProviderTlsFetch({
+    ...options,
+    fetchImpl: target.fetch.bind(target)
+  });
+  Object.defineProperty(wrapped, installedFetchMarker, { value: true });
+  target.fetch = wrapped;
+  return wrapped;
+}

package/lib/cli/args.mjs

@@ -0,0 +1,76 @@
+function parseArgs(argv, { defaultAgentsDir, resolvePath }) {
+  const options = {
+    agentsDir: defaultAgentsDir,
+    force: false,
+    relinkOnly: false,
+    nonInteractive: false,
+    command: "menu"
+  };
+  const positional = [];
+  let helpRequested = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--force" || arg === "-f") {
+      options.force = true;
+      continue;
+    }
+    if (arg === "--link-only") {
+      options.relinkOnly = true;
+      continue;
+    }
+    if (arg === "--agents-dir") {
+      const value = argv[i + 1];
+      if (!value) {
+        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";
+      continue;
+    }
+    if (arg.startsWith("-")) {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+    positional.push(arg);
+  }
+
+  if (positional.length > 1) {
+    throw new Error(`Unknown argument: ${positional.slice(1).join(" ")}`);
+  }
+
+  if (positional[0]) {
+    if (["menu", "init"].includes(positional[0])) {
+      if (!helpRequested) options.command = "menu";
+    } else if (["install", "sync"].includes(positional[0])) {
+      if (!helpRequested) options.command = "install";
+    } else {
+      throw new Error(`Unknown command: ${positional[0]}`);
+    }
+  }
+
+  if (options.command !== "install" && (options.force || options.relinkOnly || options.agentsDir !== defaultAgentsDir)) {
+    throw new Error("`--force`、`--link-only`、`--agents-dir` 仅能与 `install` 命令一起使用");
+  }
+  if (!options.nonInteractive && process.env.CI) options.nonInteractive = true;
+  return options;
+}
+
+function assertInteractiveMenuSupported({ command, inputIsTTY, outputIsTTY, nonInteractive }) {
+  if (command === "menu" && nonInteractive) {
+    throw new Error("非交互模式已启用；请显式使用 `npx abelworkflow install` 进行安装");
+  }
+  if (command === "menu" && (!inputIsTTY || !outputIsTTY)) {
+    throw new Error("交互式菜单需要 TTY 终端；非交互场景请显式使用 `npx abelworkflow install`");
+  }
+}
+
+export { assertInteractiveMenuSupported, parseArgs };