Metadata-Version: 2.4
Name: byoe
Version: 0.2.7
Summary: 卜一智航 — 携智而来，决策随行。AI 开发团队编排 + 内置多模型编程 Agent 一体化工具
Author-email: 卜一智元 <hi@byoe.net>
License-Expression: MIT
Project-URL: Homepage, https://byoe.net
Project-URL: Repository, https://github.com/byoe/byoe
Project-URL: Bug Tracker, https://github.com/byoe/byoe/issues
Project-URL: Changelog, https://github.com/byoe/byoe/blob/main/CHANGELOG.md
Keywords: ai,agent,orchestration,coding,llm,cli,dev-team,byoe
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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 :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: openai>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: prompt_toolkit>=3.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: web

# 卜一智航 · BYOE

> **携智而来，决策随行** — Bring Your Own Executive AI

**卜一智航**（BYOE）是[卜一智元](https://byoe.net)出品的 AI 开发团队编排工具，秉承「自建引擎（Build Your Own Engine）」理念，让每位开发者都能拥有一支随时待命的 AI 研发团队。

BYOE 将两个工具合二为一：

- **Orchestrator**（Crew 编排层）：项目工作流管理 — 初始化、变更计划、进度跟踪、归档
- **Engine**（AI Agent 执行层）：内置轻量 AI 编程 Agent，支持任意 OpenAI 兼容模型

**深度集成核心**：在 BYOE 管理的项目目录下运行 `byoe chat` 时，`INSTRUCTIONS.md`、`crew.yaml`、`crew/resume.md` 会被**自动注入**到 Agent 的 system prompt，无需手动粘贴上下文。

🌐 **官网**: [byoe.net](https://byoe.net) ｜ 📦 `pip install byoe`

---

## 安装

```bash
pip install byoe
```

或从源码安装（开发模式）：

```bash
cd byoe
pip install -e .
```

**要求：** Python ≥ 3.10

---

## 快速开始

### 1. 初始化项目

```bash
cd my-project
byoe init
```

生成：`INSTRUCTIONS.md`、`crew.yaml`、`crew/resume.md`、`crew/specs/`

### 2. 配置 API Key

```bash
# OpenAI
export OPENAI_API_KEY=sk-...

# DeepSeek
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://api.deepseek.com
export BYOE_MODEL=deepseek-chat

# Qwen（通义千问）
export OPENAI_API_KEY=sk-...
export OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
export BYOE_MODEL=qwen3-max

# Ollama（本地）
export OPENAI_API_KEY=ollama
export OPENAI_BASE_URL=http://localhost:11434/v1
export BYOE_MODEL=qwen2.5-coder:32b
```

Windows PowerShell：将 `export` 替换为 `$env:`，例如：

```powershell
$env:OPENAI_API_KEY = "sk-..."
$env:BYOE_MODEL = "deepseek-chat"
```

### 3. 启动内置 Agent

```bash
byoe chat
# 或等价命令
byoe run
```

Agent 启动时自动检测并注入项目上下文，欢迎界面显示 `✓ Crew 项目上下文已自动注入`。

### 4. 创建变更计划并执行

```bash
byoe plan user-auth          # 创建标准变更计划
byoe plan fix-login-bug      # 自动推断为 express 模式（含 fix 关键词）
byoe chat                    # 启动 Agent，描述需求开始工作
```

### 5. 外部工具（可选）

```bash
byoe run claude              # 启动 Claude Code，自动写入 .claude/CLAUDE.md
byoe run opencode            # 启动 OpenCode，自动写入 .opencode/instructions.md
byoe run aider               # 启动 Aider，通过 --system-prompt 注入
byoe run cursor              # 打开 Cursor，自动写入 .cursorrules
```

---

## 命令参考

### 编排命令

| 命令 | 说明 |
|------|------|
| `byoe init` | 初始化 Crew 工作区 |
| `byoe init --scan` | 初始化 + 扫描代码库建立基线（生成 `crew/codebase.md`） |
| `byoe init --prd <file>` | 导入已有需求文档 |
| `byoe plan <name>` | 创建变更计划（standard 模式） |
| `byoe plan <name> --express` | 快速模式（Bug 修复，P→E→V 流程） |
| `byoe plan <name> --prototype` | 原型模式（P→D→E，无 Verify） |
| `byoe status` | 查看所有活跃变更状态 |
| `byoe release` | 归档已完成变更 |
| `byoe agents` | 列出所有领域专家 |
| `byoe agents -c <category>` | 按分类过滤（engineering / game / design / …） |
| `byoe agents --show <id>` | 查看专家完整详情（支持部分名称匹配） |

### Agent 命令

| 命令 | 说明 |
|------|------|
| `byoe chat` | 启动内置 Agent 交互式 REPL |
| `byoe chat -m <model>` | 指定模型（覆盖 `BYOE_MODEL`） |
| `byoe chat -p "..."` | 单次提示模式，执行后退出 |
| `byoe chat -r <session-id>` | 恢复已保存的会话 |
| `byoe run [tool]` | 同 chat，或启动外部工具 |

### 会话管理

| 命令 | 说明 |
|------|------|
| `byoe sessions` | 列出最近保存的会话 |
| `byoe sessions list` | 同上 |
| `byoe sessions show <id>` | 查看会话详情（消息历史 + 修改文件） |
| `byoe sessions delete <id>` | 删除会话 |

### Chat REPL 内置命令

在 `byoe chat` 交互界面中：

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助 |
| `/reset` | 清空对话历史（重新加载项目上下文） |
| `/model <name>` | 运行时切换模型 |
| `/tokens` | 查看 Token 用量及费用估算 |
| `/compact` | 手动触发上下文压缩 |
| `/diff` | 查看本次会话修改的文件列表 |
| `/save` | 保存会话到磁盘（显示 session ID） |
| `/sessions` | 列出所有已保存会话 |
| `quit` / `Ctrl+D` | 退出 |

---

## 支持的模型

所有实现 OpenAI Chat Completions API 的服务均可使用：

| 提供商 | `BYOE_MODEL` 示例 |
|--------|------------------|
| OpenAI | `gpt-4o`、`gpt-4o-mini` |
| DeepSeek | `deepseek-chat`、`deepseek-reasoner` |
| Qwen（通义千问） | `qwen3-max`、`qwen3-plus` |
| Kimi | `kimi-k2.5`、`moonshot-v1-128k` |
| Claude（via OpenRouter） | `anthropic/claude-sonnet-4-5` |
| Ollama（本地） | `qwen2.5-coder:32b`、`llama3.3` |

---

## 微信远程控制（byoe + wechatbot）

通过 [wechatbot](../wechatbot/README.md) 可以从微信直接指挥 AI 开发团队：

```
手机微信  ──消息──▶  wechatbot  ──▶  byoe_bridge  ──▶  byoe Agent
                                                    ├── 编排层（plan/status/release）
                                                    └── 执行层（bash/edit/read…）
```

### 快速启动

```bash
# 安装两者
pip install -e /path/to/byoe
pip install -r /path/to/wechatbot/requirements.txt

# 配置 LLM
export OPENAI_API_KEY=sk-...
export BYOE_MODEL=deepseek-chat

# 启动并激活 byoe 接管
cd /your/project
BYOE_WECHAT=1 python /path/to/wechatbot/main.py
```

### 工作流示例

```
你（微信）: /cd /home/user/myproject
Bot:        Working directory set to: /home/user/myproject

你: /init
Bot:        ✅ Crew 工作区已初始化
            生成文件: INSTRUCTIONS.md, crew.yaml, ...

你: /plan user-auth
Bot:        ✅ 创建变更计划: user-auth
            模式: standard

你: 帮我实现 JWT 登录，包括注册、登录、token 刷新接口
Bot:        ⚙️ [bash]  find . -name "*.py" | head -20
            📖 [read_file]  src/app.py
            ✏️ [edit_file]  src/auth.py
            ...（实时工具进度）
            已完成 JWT 认证模块，修改了 3 个文件：
            - src/auth.py（新建）
            - src/routes.py（新增 3 个路由）
            - requirements.txt（新增 PyJWT）

你: /diff
Bot:        Files changed this session:
              src/auth.py
              src/routes.py
              requirements.txt

你: /status
Bot:        活跃变更:
            ● user-auth  [standard]  进行中
```

详细说明见 [wechatbot/README.md](../wechatbot/README.md)。

---

## 上下文压缩

Agent 自动管理上下文，三级压缩策略：

| 触发阈值 | 策略 | 提示 |
|---------|------|------|
| 50% 上限 | Snip：截断工具输出 | `⚡ 工具输出已裁剪` |
| 70% 上限 | Summarize：AI 摘要压缩历史 | `⚡ 上下文已摘要压缩` |
| 90% 上限 | Collapse：硬重置，保留最近消息 | `⚡ 上下文已硬重置` |

---

## 会话持久化

会话保存在 `~/.byoe/sessions/`，内容包括：
- 完整对话历史
- 使用的模型名称
- 本次会话修改的文件列表

```bash
byoe chat                    # 正常使用
# 在 chat 中输入 /save      → 显示 session ID

byoe chat -r <session-id>    # 下次恢复
```

---

## 自定义定价

`~/.byoe/pricing.json` 可覆盖内置的 token 定价（每百万 token，美元）：

```json
{
  "my-private-model": [1.0, 2.0],
  "gpt-4o": [2.5, 10.0]
}
```

格式：`"model-name": [input_price, output_price]`

---

## 项目结构

```
byoe/
├── byoe/
│   ├── cli.py                  统一 CLI 入口（argparse）
│   ├── chat.py                 交互式 REPL（prompt_toolkit）
│   ├── engine/                 AI Agent 执行层
│   │   ├── agent.py            核心 Agent 循环（tool loop + 并行执行）
│   │   ├── llm.py              OpenAI 兼容多模型层（流式 + 计费）
│   │   ├── config.py           环境变量配置
│   │   ├── prompt.py           System prompt + Crew 上下文注入
│   │   ├── context.py          三层上下文压缩管理
│   │   ├── session.py          会话持久化（messages + model + changed_files）
│   │   └── tools/
│   │       ├── base.py         Tool 基类
│   │       ├── bash.py         Shell 命令执行（跨平台 + 危险命令检测）
│   │       ├── read.py         文件读取（带截断）
│   │       ├── edit.py         文件编辑（字符串替换）
│   │       ├── write.py        文件写入
│   │       ├── glob.py         文件路径匹配
│   │       ├── grep.py         内容搜索
│   │       └── agent.py        子 Agent 调用
│   └── orchestrator/           Crew 编排层
│       ├── utils.py            颜色输出、名称转换等工具
│       └── commands/
│           ├── init.py         byoe init
│           ├── plan.py         byoe plan
│           ├── status.py       byoe status
│           ├── release.py      byoe release
│           ├── agents.py       byoe agents
│           └── run.py          byoe run
├── agents/                     领域专家 Markdown 定义（30+ 个）
├── templates/
│   └── INSTRUCTIONS.md         项目初始化模板
└── tests/
    ├── test_tools.py           工具层测试（30 项）
    ├── test_orchestrator.py    编排层测试（26 项）
    └── test_prompt.py          Prompt 层测试（17 项）
```

---

## 测试

```bash
cd byoe
pytest tests/ -v
```

74 项测试，2 项在 Windows 上跳过（Unix 特定危险命令模式）。

---

## License

MIT

---

<div align="center">

**卜一智航 · BYOE** — 携智而来，决策随行

[卜一智元](https://byoe.net) © 2026 ｜ Build Your Own Engine

</div>
