codex-flow 2.1.13__tar.gz

codex_flow-2.1.13/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codex-flow 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.

codex_flow-2.1.13/MANIFEST.in

@@ -0,0 +1,21 @@
+include VERSION
+include LICENSE
+include README.md
+include README.en.md
+include install.sh
+include install.ps1
+include install-release.sh
+include install-release.ps1
+include smithery.yaml
+include glama.json
+recursive-include scripts *.py *.sh
+recursive-include policy *.toml
+recursive-include templates *
+recursive-include completions *
+recursive-include benchmark *.json
+recursive-include apps/chatgpt-mcp *
+recursive-include apps/macos-overlay *
+recursive-include packaging/pypi *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[cod]
+recursive-exclude * .DS_Store

codex_flow-2.1.13/PKG-INFO

@@ -0,0 +1,342 @@
+Metadata-Version: 2.4
+Name: codex-flow
+Version: 2.1.13
+Summary: Intelligent, Efficient, Adaptive Multi-Agent Strategy Orchestration for Codex
+Home-page: https://github.com/ParsifalC/codex-flow
+Author: Parsifal
+Author-email: Parsifal <zmw@izmw.me>
+License: MIT
+Project-URL: Homepage, https://github.com/ParsifalC/codex-flow
+Project-URL: Repository, https://github.com/ParsifalC/codex-flow
+Project-URL: Issues, https://github.com/ParsifalC/codex-flow/issues
+Project-URL: Documentation, https://github.com/ParsifalC/codex-flow#readme
+Keywords: codex,agent,multi-agent,orchestration,llm,workflow,mcp,telemetry
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+<div align="center">
+
+<a href="https://github.com/ParsifalC/codex-flow">
+  <img src="docs/assets/logo.png" alt="FlowPilot Logo" width="130" height="130" />
+</a>
+
+# FlowPilot · codex-flow
+
+**智能、高效、自适应的 Codex 多 Agent 策略编排引擎**
+
+[![Version](https://img.shields.io/badge/version-2.1.13-blue.svg?style=flat-square)](VERSION)
+[![Homebrew](https://img.shields.io/badge/Homebrew-ParsifalC%2Ftap-orange.svg?style=flat-square&logo=homebrew)](https://github.com/ParsifalC/homebrew-tap)
+[![PyPI](https://img.shields.io/pypi/v/codex-flow.svg?style=flat-square&logo=pypi)](https://pypi.org/project/codex-flow/)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-brightgreen.svg?style=flat-square)](#-快速安装)
+[![SwiftUI](https://img.shields.io/badge/UI-SwiftUI%20%2B%20AppKit-orange.svg?style=flat-square)](docs/overlay.md)
+[![Telemetry](https://img.shields.io/badge/telemetry-deterministic%200--cost-purple.svg?style=flat-square)](docs/telemetry.md)
+[![Smithery](https://img.shields.io/badge/Smithery-FlowPilot-black.svg?style=flat-square)](https://smithery.ai)
+[![Glama](https://img.shields.io/badge/Glama-MCP-5046e6.svg?style=flat-square)](https://glama.ai/mcp/servers)
+[![LinuxDo](https://img.shields.io/badge/LinuxDo-公测中-5046e6.svg?style=flat-square)](https://linux.do)
+[![License](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
+
+<br />
+
+<img src="docs/assets/promo/flowpilot_promo_banner.png" alt="codex-flow Banner" width="100%" style="border-radius: 12px; box-shadow: 0 8px 24px rgba(0,0,0,0.15);" />
+
+<br /><br />
+
+[**English Documentation**](README.en.md) · [**多策略运行时**](docs/strategy-runtime.md) · [**深入配置**](docs/configuration.md) · [**遥测机制**](docs/telemetry.md) · [**原生悬浮窗**](docs/overlay.md) · [**基准评测**](docs/benchmark.md)
+
+<br />
+
+> 📢 **社区公测**：`codex-flow` 现已正式在 [**LINUX DO**](https://linux.do) 开启公测，欢迎各位佬友前往体验、讨论与反馈！
+
+<br />
+
+> **“ 让昂贵的 Parent 做高价值判断，让高性价比 Worker 用更深推理承担探索、实现、验证与调试循环；当用户明确要求最高质量时，把高级 capability 精确投放到关键 Implementer / Reviewer，而不是无差别升级所有 Worker。”**
+
+</div>
+
+---
+
+## ✨ 核心亮点
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>🧠 多策略运行时 (FlowPilot)</h3>
+      <p>FlowPilot 从单一分发策略升级为统一 Strategy Runtime。内置 <code>efficient</code> / <code>balanced</code> / <code>quality</code> / <code>speed</code>，统一通过 TaskProfile → WorkerBudget → ExecutionPlan v7 驱动执行。</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>⚙️ 动态 Worker Budget</h3>
+      <p>Worker 数不再写死为 1~2 个。Runtime 根据不确定性、工作流隔离、Quota 与线程上限动态计算 Explorer / Implementer / Reviewer，并且可写并发始终要求真实隔离证据。</p>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>🧠 Worker-first Reasoning</h3>
+      <p>默认 Parent 以 <code>high</code> 为主，便宜的 Worker 以 <code>xhigh</code> 起步；委派时各 Worker role reasoning 至少比 Parent 高一档，Parent 已为 <code>max</code> 时除外。</p>
+    </td>
+    <td width="50%" valign="top">
+      <h3>🏆 Quality Intent</h3>
+      <p><code>quality</code> 支持 <code>normal / strong / absolute</code> 三档当前任务质量意图。普通 Explorer 继续优先 <code>latest-efficient</code>；强质量意图可把关键 Implementer / Reviewer 升级到 <code>latest-capable</code>。只有技术风险本身达到 critical 时，Explorer 才会升级到 Parent 级 capability。</p>
+    </td>
+  </tr>
+</table>
+
+---
+
+## 🧩 四种内置策略
+
+| Strategy | 优化目标 | 高需求任务的 Worker 倾向 |
+| :--- | :--- | :--- |
+| **`efficient`** | 减少昂贵 Parent 消耗与无效总成本 | 最多约 2 Explorer / 2 Implementer，低 speculation，Quota 紧张会自动收敛 |
+| **`balanced`** | 平衡质量、额度与耗时 | 最多约 3 Explorer / 3 Implementer，适度安全并行 |
+| **`quality`** | 最大化正确性与验证置信度 | 普通 complex 优先 Luna + `max` reasoning；`strong/absolute` 只把关键 Implementer / Reviewer 升级到 Parent 级 capability，Explorer 默认保持高性价比 |
+| **`speed`** | 最小化 wall-clock latency | 最多 8 个 Implementer budget；实际数量由已证明 writable workstreams 与 Runtime ceiling 决定 |
+
+`quality_intent` 是**当前任务语义**，不是持久化配置，也不是 `risk` 的别名；并且只有 `quality` strategy 会消费它：
+
+```text
+normal   → 普通质量目标，优先 latest-efficient Worker + 深 reasoning
+strong   → 明确质量优先，允许关键 Implementer / Reviewer 使用 latest-capable
+absolute → 明确最高质量优先，在安全 ceiling 内 correctness > quota / latency；Explorer 仍默认 latest-efficient
+```
+
+默认配置仍是：
+
+```text
+strategy = efficient
+routing = adaptive
+```
+
+但 v1.7 的 fresh-install 资源策略已经从“Parent 与 Worker 相近 reasoning”调整为 **Parent 高价值决策 + Worker 深推理执行**。已有用户的自定义 reasoning 配置在 update/reinstall 时会无损保留。
+
+---
+
+## 🚀 快速安装
+
+### 前置要求 (Prerequisites)
+
+> 💡 **特别说明**：Codex CLI **仅用于首次安装的环境校验与一次性 Hook 授权**。初始化完成后，**日常使用完全使用 Codex 桌面端 APP 即可**，无需在终端中启动或使用 CLI。
+
+确保环境拥有 Codex CLI（用于首次安装与授权）：
+```bash
+# npm 全局安装
+npm install -g @openai/codex
+
+# 或 macOS Homebrew 安装
+brew install codex
+```
+
+### 快速安装
+
+#### 方式一：PyPI 安装（全平台推荐，支持 Windows / macOS / Linux）
+
+```bash
+# 推荐使用 pipx（独立隔离环境）
+pipx install codex-flow
+
+# 或使用标准 pip
+pip install codex-flow
+
+# 初始化配置与环境
+codex-flow install
+```
+
+#### 方式二：Homebrew 安装（macOS / Linux）
+
+```bash
+brew install ParsifalC/tap/codex-flow
+codex-flow install
+```
+
+#### 方式三：一键发布安装脚本
+
+首次安装统一使用 GitHub Release 中与你的系统和 CPU 架构匹配的正式 artifact，不需要 clone 仓库。
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/ParsifalC/codex-flow/main/install-release.sh | bash
+```
+
+```powershell
+# Windows PowerShell
+irm https://raw.githubusercontent.com/ParsifalC/codex-flow/main/install-release.ps1 | iex
+```
+
+安装器会自动识别 OS / CPU、解析 Latest Stable Release、下载对应 artifact、校验 SHA-256、安装到 `~/.codex/codex-flow/versions/<version>`，并运行健康检查。Windows 自动选择 x86_64 / ARM64 ZIP；macOS 直接使用 Release 中已经预编译好的 FlowPilot，**安装完成后悬浮按钮会自动启动**，不会在本机执行 `build.sh`。
+
+> ⚠️ **最后一步**：
+> 1. **首次一次性授权**：在终端启动一次 `codex`，在对话框中输入 `/hooks` 批准 FlowPilot telemetry（仅需做一次，完成永久信任）。
+> 2. **重启 Codex 桌面端**：完全退出 Codex 桌面应用后重新打开。FlowPilot 悬浮窗已在 macOS 桌面自动运行，后续所有日常工作**直接在 Codex 桌面端使用即可**，无需再打开终端。
+
+安装器还会把带有明确标记的 FlowPilot 入口写入生效的全局 `AGENTS.md`。入口会要求当前 Agent 在仓库技术工作前读取已安装 skill 并取得策略门禁 receipt，因此不需要在提示中点名 skill。安装后请开始新任务或完整重新加载 Codex，确保新的指令生效。全局开关关闭或本任务的一次性 bypass 已消费时，该任务按普通流程执行。这个提示入口依赖当前宿主遵循指令，不是 100% 的强制边界；生命周期 hooks 仍只用于遥测。
+
+---
+
+## 🎮 基本使用
+
+### 1. 查看 / 切换默认策略
+
+```bash
+codex-flow strategy show
+codex-flow strategy profiles
+codex-flow strategy set quality
+codex-flow strategy set efficient
+codex-flow strategy routing adaptive
+```
+
+### 2. 对话内自然语言覆盖
+
+当前任务可以临时覆盖持久配置：
+
+```text
+👉 策略覆盖："质量优先" / "尽量少用 Plan 额度" / "尽快完成"
+👉 强质量："质量优先，必要时使用更强模型" → quality_intent=strong
+👉 最高质量："成本不重要，用最强模型和独立验证" → quality_intent=absolute
+👉 自动路由："按默认策略实现" / "自适应处理"
+👉 强制委派："delegate" / "使用子 agent 实现" / "交给 worker 处理"
+👉 单兵直出："direct" / "不要使用子 agent，直接完成" / "这次直接做"
+```
+
+Strategy 与 Routing 正交，例如：
+
+```text
+quality + direct
+```
+
+表示使用 quality 的能力/推理目标，但当前任务不使用子 Agent。
+
+### 3. 查看确定性的 ExecutionPlan
+
+```bash
+codex-flow strategy plan \
+  --profile quality \
+  --quality-intent strong \
+  --complexity complex \
+  --uncertainty high \
+  --parallelism high
+```
+
+Plan 会输出 `quality_intent`、Strategy 的 `worker_budget`，以及 Runtime 实际编译出的三组角色资源：
+
+```text
+explorer_capability_policy / explorer_model / explorer_reasoning
+implementer_capability_policy / implementer_model / implementer_reasoning
+reviewer_capability_policy / reviewer_model / reviewer_reasoning
+```
+
+同时包含 `exploration_workers`、`implementation_workers`、`reviewer_workers` 和 `planned_worker_count`。
+
+### 4. 交互式控制台
+
+```bash
+codex-flow
+```
+
+最新控制台同时集成了 Overlay 构建/启动入口、策略状态、Benchmark 与遥测：
+
+```text
+╭────────────────────────────────────────────────────────────────────╮
+│                  🚀 codex-flow 控制台 (v2.1.13)                  │
+│    FlowPilot 智能编排 · 确定性任务遥测 · 本地 Benchmark 验证     │
+╰────────────────────────────────────────────────────────────────────╯
+  [1] 🪟 macOS 原生悬浮窗 (overlay widget)
+  [2] 📊 查看最新任务卡片 (usage last)
+  [3] 📜 浏览历史任务列表 (usage list)
+  [4] 📈 项目聚合统计分析 (usage stats)
+  [5] 🎯 查看生效策略配置 (status)
+  [6] 🩺 运行系统诊断检查 (doctor)
+  [7] ⚡ 本地快速 Benchmark (benchmark-local quick)
+  [8] 🔄 检查与拉取更新 (update)
+  [0] 🚪 退出
+```
+
+Overlay 子菜单支持直接启动、编译并启动、仅编译，以及运行时的重编译/重启、展开切换和数据推送，不再要求用户手动先执行 `build.sh`。
+
+### 5. 常用 CLI
+
+```bash
+codex-flow usage last
+codex-flow usage list --today
+codex-flow usage stats -d 30
+codex-flow doctor
+codex-flow update
+```
+
+### 6. MCP 客户端与平台集成 (Claude Desktop / Cursor / Smithery / Glama)
+
+`codex-flow` 内置标准的 Model Context Protocol (MCP) 服务端，支持将 FlowPilot 确定性遥测注入任意支持 MCP 的宿主：
+
+* **Claude Desktop / Cursor (`stdio` 模式)**：
+  在 `claude_desktop_config.json` 中配置：
+  ```json
+  {
+    "mcpServers": {
+      "flowpilot": {
+        "command": "codex-flow-mcp",
+        "args": ["--stdio"]
+      }
+    }
+  }
+  ```
+* **Smithery.ai**：配置文件见根目录 `smithery.yaml`，已支持一键发现与客户端挂载。
+* **Glama**：认证元数据见根目录 `glama.json`，已入驻 Glama MCP 注册目录。
+
+---
+
+## 🪟 FlowPilot macOS 原生悬浮窗
+
+专为 macOS 深度定制的 **100% 纯原生毛玻璃效能看板**，打通任务生命周期与 Quota 监控。
+
+<div align="center">
+  <img src="docs/assets/promo/flowpilot_promo_poster.png" alt="FlowPilot Native Widget Showcase" width="100%" style="border-radius: 12px; margin: 16px 0;" />
+</div>
+
+- **🟢 灵动微胶囊 (Capsule)**：闲置时边缘半收起，呼吸光环显示任务状态与最新消耗。
+- **⚡️ 实时巡检 (Inspector)**：耗时 / Tokens / 费用、Quota 水位与 Agent 拓扑。
+- **📜 历史回溯 (History)**：跨项目任务时间线与详情回溯。
+- **📊 效能看板 (Analytics)**：7d/30d 缓存命中率、Worker 算力卸载比与模型/仓库分布。
+
+```bash
+codex-flow overlay start
+codex-flow overlay toggle
+```
+
+---
+
+## 📚 深入文档
+
+| 模块 | 文档入口 | 核心内容 |
+| :--- | :--- | :--- |
+| **🧠 多策略运行时** | [docs/strategy-runtime.md](docs/strategy-runtime.md) | TaskProfile、Quality Intent、WorkerBudget、Strategy Registry、ExecutionPlan v7、role-scoped resources |
+| **⚙️ 策略与配置** | [docs/configuration.md](docs/configuration.md) | policy schema v4、Worker-first reasoning、路由、Runtime ceiling |
+| **📈 确定性遥测** | [docs/telemetry.md](docs/telemetry.md) | Hook 生命周期、Token 差值归因、账户 Quota |
+| **🪟 原生悬浮窗** | [docs/overlay.md](docs/overlay.md) | 交互、IPC 与 SwiftUI 架构 |
+| **🧪 本地基准测试** | [docs/benchmark.md](docs/benchmark.md) | 本地无 Key 评测与多策略对比 |
+| **☁️ Actions 评测** | [docs/benchmark-actions.md](docs/benchmark-actions.md) | GitHub Actions Benchmark |
+| **🌐 多语言支持** | [docs/localization.md](docs/localization.md) | 中英双语与本地化范围 |
+
+---
+
+## 📄 开源协议
+
+本项目采用 [MIT License](LICENSE) 开源协议。