AbelWorkflow

AbelWorkflow 为 Codex、Claude Code 和 Pi 部署统一的 Skills、工作流命令、Agent 配置与 Pi Extensions。

环境要求

• Node.js 22 或更高版本
• npm 10 或兼容版本
• Linux、macOS 或原生 Windows

工作流命令

| 命令 | 用途 | | --- | --- | | /abel-init | 初始化 OpenSpec 环境并验证工具链 | | /abel-design | 将需求整理为可实施、可验证的 OpenSpec 规格 | | /abel-implement | 按 Red → Green → Refactor 实施变更 | | /abel-diagnose | 基于证据定位根因并完成回归验证 |

/abel-init → /abel-design → /abel-implement(TDD)
                           ↘ /abel-diagnose (bug fix)

OpenSpec 命令保持独立：/opsx:propose、/opsx:explore、/opsx:apply、/opsx:update、/opsx:sync、/opsx:archive、openspec view、openspec status。

安装与更新

npx abelworkflow
npx abelworkflow install
npx abelworkflow@latest

无 TTY 环境必须显式运行 npx abelworkflow install。安装器将工作流部署到 ~/.agents，再为 Claude、Codex 与 Pi 建立链接。已有目标与托管内容冲突时，安装会失败并保留原内容；确认目标后再处理冲突。

源码安装

源码目录与部署目录必须分离，不能相同或互相嵌套。不要把源码仓库直接克隆到 ~/.agents。

git clone https://github.com/abelxiaoxing/AbelWorkflow ~/src/AbelWorkflow
cd ~/src/AbelWorkflow
npm ci
npm ci --prefix skills/dev-browser
npm run build --prefix skills/dev-browser
node bin/abelworkflow.mjs install --agents-dir ~/.agents

Windows PowerShell 使用独立源码目录，并显式指定部署目录：

node .\bin\abelworkflow.mjs install --agents-dir "$HOME\.agents"

可选 Skill 依赖

源码安装需按上方命令在同步前构建 dev-browser。同步后如需使用 dev-browser，还需在部署目录中显式安装运行依赖；Time 独立 CLI 需要 Python 3.9+，Windows 还需 tzdata 提供 IANA 时区；Grok 依赖安装到用户自行选择的 Python 环境。普通运行不会自动安装依赖或浏览器：

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 API 配置会合并个人默认模板（$schema、attribution、hooks、alwaysThinkingEnabled、language 与全局权限白名单），删除已弃用的 includeCoAuthoredBy；白名单使用当前任务工具 TaskCreate、TaskGet、TaskUpdate、TaskList，缺失项补入默认模板但保留已有权限数组。
• Claude API 使用 CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 统一关闭非必要流量并保留 API_TIMEOUT_MS，清理重叠的 DISABLE_TELEMETRY 与 DISABLE_ERROR_REPORTING。
• Claude API 管理 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY，并将所选模型同步到 ANTHROPIC_MODEL、Opus/Sonnet/Haiku 默认模型与 CLAUDE_CODE_SUBAGENT_MODEL；冲突的 ANTHROPIC_AUTH_TOKEN 会被删除，其他用户配置保持不变。
• Codex 配置以 Codex 最新稳定版为基线，不保留旧版本兼容配置；配置会合并个人默认模板，使用 approval_policy = "never" 与 sandbox_mode = "danger-full-access" 赋予 Agent 完全权限，同时管理 AbelWorkflow Provider 路由、OPENAI_API_KEY 与 auth_mode，清理冲突的 preferred_auth_method、temp_env_key 及目标 Provider 旧路由字段，保留其他认证字段。
• Pi 配置更新 abelworkflow Provider、对应凭据及全局 defaultProvider、defaultModel，保留其他 Provider 与无关设置。
• 所有 Provider 在配置结构或路径无法安全合并时直接失败。
• Skill 密钥写入 ~/.agents/skills/<skill>/.env，属于用户私密配置。
• .skill-lock.json 完全属于用户：安装器不读取、不修改、不备份、不删除，也不会将其放入发布包。
• 自定义 CA 应通过标准证书环境变量显式配置，不关闭 TLS 校验。

Codex WebSocket 中转

AbelWorkflow 为目标 Provider 设置 wire_api = "responses" 与 supports_websockets = true，使 Codex 最新稳定版优先使用 Responses API WebSocket。旧版 [features] 配置 responses_websockets 与 responses_websockets_v2 会被清理，不作为兼容开关保留。

Codex 根据 Provider Base URL 推导 WebSocket 地址。例如，https://relay.example/v1 对应 wss://relay.example/v1/responses；使用 HTTP Base URL 时则对应 ws://。中转必须在该路径支持 WebSocket Upgrade，并实现 Codex 使用的 Responses API WebSocket 协议、认证头和事件格式；只支持 HTTP/SSE Responses API 不满足此要求。

supports_websockets = true 是 Provider 能力声明，AbelWorkflow 不会在写入配置时探测中转能力。如果握手或协议不兼容，请修复中转并查看 Codex 日志；是否回退 HTTP 由当前 Codex 运行时决定，AbelWorkflow 只保证默认优先尝试 WebSocket，不保证 WebSocket-only。

部署映射

| 托管内容 | 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/* | — | — | ~/.agents/extensions/ → ~/.pi/agent/extensions/ |

自签名 HTTPS 中转

取得中转的 CA PEM 后，在启动客户端前配置：

export NODE_EXTRA_CA_CERTS=/absolute/path/relay-ca.pem
export CODEX_CA_CERTIFICATE=/absolute/path/relay-ca.pem

不要全局设置 NODE_TLS_REJECT_UNAUTHORIZED=0。证书过期或主机名不匹配时应重新签发证书。