Metadata-Version: 2.4
Name: bensz-router
Version: 1.1.2
Summary: Public CLI and Harness adapters for the bensz-router Agent Workflow API
Author: bensz-router contributors
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: keyring>=24
Provides-Extra: test
Requires-Dist: build>=1; extra == "test"
Requires-Dist: keyring>=24; extra == "test"

<div align="center">

# bensz-router Python 客户端

[![Python](https://img.shields.io/badge/Python-3.9%2B-blue?style=flat-square)](https://pypi.org/project/bensz-router/1.1.1/) [![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)](https://pypi.org/project/bensz-router/1.1.1/)

**在自己的 Codex 或 Claude Code 中发现并执行版本化工作流。**

[English](README_EN.md) · [PyPI](https://pypi.org/project/bensz-router/1.1.1/) · [Skill 指南](skills/bensz-router/README.md)

</div>

`bensz-router` 1.1.1 提供专用 MCP 工具与按需触发的 hooks，可直接从 PyPI 安装；Codex 默认接入 MCP，Claude Code 可选接入 MCP。客户端提供 Python SDK、CLI、Harness adapter 与公开 Agent Skill。服务端负责目录、设备授权和步骤契约；客户端继续使用本地工具和自己的模型，不代理模型请求。需要 Python 3.9+ 和可用的系统 keyring。

1.1.1 将 `import-sub2api --apply` 改为提交管理员发布提案（审批后生效，不再创建个人草稿），并修复无 `owner` 元数据导入被误加 `usr_` 前缀的 ID 一致性问题；`prompts validate/build` 改为纯本地命令，无需登录或系统 keyring。随父 Skill 安装的 `diy-flow` 子 agent 与管理端提案、批量审批能力保持不变。

从安装到首次任务的完整说明见[使用教程](https://router.benszresearch.com/tutorial.zh-CN.md)；自建站点使用同站点的教程地址。

## 安装与登录

```bash
python3 -m pip install --upgrade bensz-router==1.1.1
bensz-router --version
bensz-router skill sync --harness all
bensz-router skill status --harness all --json
bensz-router login --harness codex
bensz-router catalog --json
```

设备登录打开浏览器授权页，批准后把短期 `brw_` Token 保存到系统 keyring。Claude Code 用户使用 `--harness claude-code`。CLI 默认地址为 `https://router.benszresearch.com`；`--server <地址>` 优先于 `BENSZ_ROUTER_URL`，登录和预检须使用同一站点。

也可运行 `uv tool install bensz-router==1.1.1`。在 Harness 的 Shell 中执行 `command -v bensz-router` 检查路径；macOS 图形界面启动的 Harness 可能缺少终端 PATH，Skill 会有界检查用户级与 Homebrew 命令目录。keyring 不可用时命令明确失败，不保存明文凭据。

`bensz-router --version`（或 `-V`）无需登录或联网，预期输出 `bensz-router 1.1.1`。持有源码的开发者也可在仓库根目录使用 `uv tool install --force ./packages/bensz-router` 安装本地版本。

安装后执行 `bensz-router skill status --harness all --json`，确认 Codex 与 Claude Code 的公开 Skill 状态均为 `synced`。

## 发现与预检

```bash
bensz-router catalog --json
bensz-router profiles --json
# AI 根据公开元数据选择模板，再提交 ID；不传用户 Prompt
bensz-router preflight --harness codex --selected-template-id software-development --manifest
bensz-router workflow list
bensz-router workflow hide <workflow-id>
bensz-router workflow show <workflow-id>
```

AI 在默认智能方案候选范围内本地选择工作流，服务器复核权限、依赖、冲突与版本。`--manifest` 提供可见应用清单，`--json` 用于机器读取；同时指定时 manifest 优先。模板 ID 必须来自当前目录。 提醒、清单标题及结束标记使用管理员配置的站点名称（服务端响应的 `site_name`）；旧服务端缺少名称时显示“工作流服务”。

成功命中的预检记录表示契约已返回，不证明任务完成。Harness 应逐项执行、核对证据；无匹配、无权限或远程不可用时有界停止并继续原任务。客户端拒绝 HTTP 重定向，不转发凭据。

## 可选 hooks 与恢复

当前源码新增 Codex 自动接入，尚未发布：运行 `hooks install` 即可补齐缺失 MCP，以当前环境绝对入口验证本地启动及七个工具后安装 hooks；`--dry-run --json` 仅预演，冲突或禁用配置保留。新版 `hooks doctor` 的 `mcp.status` 可定位未注册、工具过滤和启动问题，失败返回非零。配置通过后仍须重启 Codex；IDE 用 `Restart extension` 或 `Developer: Reload Window`，再新建会话核验工具。公开 1.1.1 及更早版仍需下面的独立注册步骤。

安装 Python 客户端 1.1.1 后即可配置 Codex 或 Claude Code 的 MCP 接入。固定注册服务名 `bensz_router`：

```bash
codex mcp add bensz_router -- bensz-router --server https://router.benszresearch.com mcp --harness codex
```

然后安装 hooks、在 `/hooks` 审核信任，并新建会话在 `/mcp` 核对工具。MCP 注册是用户级配置；不要在参数中写凭据。AI 使用专用 `catalog`、`profiles`、`preflight` 工具，以原样 `session_ref` 选择一次工作流；PostToolUse 只匹配该服务的受管工具，普通 Shell 不触发 router。生命周期和子代理隔离 hooks 保留。受保护步骤用同名 `run`、`current`、`advance` 工具，结束或切换任务用 `release`；工具仍遵守宿主审批。

Claude 沿用 Shell 接入；Codex 显式加 `--transport shell` 可回退。下述独立单行 CLI 规则仅适用于 Shell 模式，MCP 模式无需在普通工具前后检查 router。已有 hooks 必须在原 scope 重复安装，避免旧用户级 Bash hooks 继续触发；配置注册不证明 MCP 可用或正文已送达。

```bash
bensz-router hooks install --harness codex --scope project --dry-run --json
bensz-router hooks install --harness codex --scope project
bensz-router hooks doctor --harness codex --scope project --json
```

Codex 需通过 `/hooks` 信任。hooks 提供跨进程单次预检、认证/项目/子代理隔离和当前契约恢复；SessionStart 给出的 `--session-ref` 必须原样传入受管命令。Codex 接入 developer 上下文，Claude hooks 接入 system reminder。配置注册不代表实际送达或执行完成。

每个受管 `preflight`、`run`、`current`、`advance` 或 `session release` 必须是一次 Shell 调用中的唯一单行命令，使用确认过的 CLI 路径、字面参数并保留完整输出。组合 `cd`、变量、管道、重定向或其他命令会阻断 hook 桥接核验。

Codex 的受管上下文 handler 设置 `additionalContextLimit: 0`，完整传入正文，adapter 不设正文长度上限。更新包后按原 scope 重复执行 `hooks install` 并在 `/hooks` 审核新定义，已有配置才会获得该设置。Claude 上下文仍限制为 9,000 字符，超限明确降级。

受保护工作流必须以预检的 `resolution_id` 启动，再读取或显式推进本人运行：

```bash
bensz-router run <workflow-id> --harness codex --resolution-id <resolution-id>
bensz-router current <run-id>
bensz-router advance <run-id> <step-id> --outcome completed
```

受管命令另加 `--session-ref <session-ref>`；任务结束或切换用 `session release`，本地文件条件用 `session verify --require-file <项目内相对文件>`。这些检查不替代质量判断。`claude-start` 只用于新会话的固定 system 快照；hooks 无法删除宿主历史指令。详见 [Harness 接入](https://github.com/huangwb8/bensz-router/blob/main/docs/harness-hooks.md)（需要私有仓库访问权限）。


客户端支持 Claude Code 可选 MCP 接入，直接从 PyPI 安装即可使用。在用户级注册固定名称 `bensz_router` 的服务，并切换同一 scope 的 hooks：

```bash
claude mcp add --scope user --transport stdio bensz_router -- bensz-router --server https://router.benszresearch.com mcp --harness claude-code
bensz-router hooks install --harness claude-code --scope user --transport mcp
```

新建 Claude 会话后在 `/mcp` 确认连接。Claude 的默认接入仍为 Shell；选择 MCP 后普通 Shell 不触发 router，正文仍通过 system reminder 送达并保留 9,000 字符预算。

## 管理自动化与安全

```bash
bensz-router automation login
bensz-router automation capabilities --json
bensz-router automation validate workflow.json --json
bensz-router automation save-draft workflow.json --base-revision 3 --json
bensz-router automation approve brp_example --json
bensz-router automation batch-approve brp_first brp_second --json
```

管理员在管理台“API 密钥”创建 `brm_`，由隐藏输入保存到独立 keyring 并交换短期 `bra_`。默认 Workflow 预检不使用管理凭据；管理失败立即停止，候选版本不会自动激活。 工作流审批只走管理员 API，不使用浏览器 Cookie/CSRF；授予 `proposals:approve`，或保留已有完整写权限组合 `workflows:versions:publish`、`proposals:create` 和 `proposals:read`。管理协议与审批见 [管理自动化](https://github.com/huangwb8/bensz-router/blob/main/docs/workflow-management-automation.md)（需要私有仓库访问权限）。

默认不上传用户 Prompt、历史上下文或本地文件正文；服务端只记录低敏状态。已下发正文可能保存在宿主历史。外部副作用始终需人工确认；`bug-report --scan` 仅在明确授权时上传同目录配对的 `bug-context.json` 与 `BUG_REPORT.md` 脱敏记录。

## 开发与许可证

持有源码的开发者在包目录执行：

```bash
uv sync --frozen
uv run python -m pytest tests -q
```

Skill 源码位于 `skills/bensz-router`，随包分发；`skill sync` 支持首次安装、更新和 `--dry-run`，`skill status --json` 检查漂移。SDK 入口为 `bensz_router.client.WorkflowClient`。本包采用 MIT License。
