Metadata-Version: 2.4
Name: bensz-router
Version: 1.0.0
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"

# bensz-router Python 客户端

这是 bensz-router Agent Workflow API 的公开 Python SDK、CLI 与 Harness adapter。它不包含受保护工作流的完整流程图、隐藏评分规则或其它商业秘密。

普通用户从 PyPI 安装：`python3 -m pip install bensz-router`，并按 [用户使用指南](skills/bensz-router/README.md) 操作。以下命令用于持有本仓库源码的开发者安装：

```bash
python -m pip install -e .
bensz-router skill sync --harness all
bensz-router login --harness codex
bensz-router catalog --json
```

CLI 默认连接 `https://router.benszresearch.com`。只有约定使用其他站点时才设置 `BENSZ_ROUTER_URL`，或在单次命令前加 `--server <地址>`；显式 `--server` 优先于环境变量。登录、目录读取和 Harness 预检必须使用同一地址。

`skill sync` 同时承担首次安装和更新；`--dry-run` 预演，`skill status --json` 检查缺失或本地漂移，`--scope project` 改为当前项目级安装。旧的 `install-skill --harness ...` 继续兼容。

Codex 只读沙盒若无法访问 macOS 系统密钥环，CLI 会简短报告 `系统 keyring 不可用` 并退出；需要授权的目录与预检应在可访问密钥环的终端或 Harness 环境执行。

使用系统级 `install-bensz-skills` 安装器，并指定 `--source packages/bensz-router/skills --skill bensz-router` 时，`skill status` 也会按该安装器的可安装文件清单校验内容，不把安装清单及省略的说明文档误报为漂移。

工作流数量不会写进 `SKILL.md`。客户端每次读取公开目录并应用本机可见性偏好，因此大量流程仍能保持短小、稳定的 Skill：

```bash
bensz-router workflow list
bensz-router workflow hide <workflow-id>
bensz-router workflow show <workflow-id>
bensz-router catalog --all
```

默认预检读取公开目录和本人智能方案列表；当前 AI 在 `is_default=true` 的方案候选范围内结合用户请求语义选择 Workflow ID，不把用户 Prompt、历史上下文、文件原文或凭据交给 CLI/服务器。平台默认方案由管理员启用的智能工作流动态组成，用户可设置个人方案为默认并随时切回。服务不可用、无权限或无匹配时，Harness 应继续处理用户原任务。

智能路由预检由 AI 依据公开目录语义选择模板 ID，再把模板 ID、方案 ID、Harness 与幂等键发给服务端；服务端重新校验候选边界、角色、互斥组与冲突，并返回版本固定的应用清单（强制项 → 引用依赖 → 智能命中）：

```bash
# AI 先阅读 catalog 和默认方案，再提交语义选择的模板 ID
bensz-router catalog --json
bensz-router profiles --json
bensz-router preflight --harness codex --selected-template-id software-development --manifest
bensz-router preflight --harness claude-code --profile-id sp_xxx --json
bensz-router profiles
```

`--manifest` 在服务端确认智能命中或固定模板时，以 `🚀✨ bensz-router 温馨提醒：本次任务命中工作流「工作流名称」 ✨🚀` 开头。展示时单独使用 `--manifest`，机器读取时单独使用 `--json`；两者同时传入时优先输出简短应用清单。已安装的 Skill 要求 Harness 在下一条用户可见回复中显示一次；只有强制项、无匹配或失败开放时不显示命中提醒。提醒只展示解析结果中已确认的工作流名称。

线上低副作用连通性检查可使用仓库的 `scripts/bensz-router-online-smoke.sh`；它只执行一次目录读取、预检和幂等运行推进，不使用不存在的 `/ping` 端点。


Workflow 管理是独立的显式命令，不参与默认预检，也不复用 `brw_` Token：

```bash
# 先在管理台“自动化 API”创建 brm_ 密钥
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 publish-version workflow.json --base-revision 4 --json
bensz-router automation propose publish demo --base-revision 3 --definition workflow.json --json
bensz-router automation proposal <proposal-id> --json
```

`automation login` 通过隐藏输入读取 `brm_`，将长期 Key 与派生的短期 `bra_` 分别保存到独立系统 keyring；SDK 在 Token 缺失或返回 401 时至多自动交换一次。管理员 Key 不作为命令行参数，明文只应从管理台“自动化 API”的创建结果复制。草稿和候选版本写入使用内容哈希、幂等键与基线 revision；候选版本不会自动改变激活指针。管理请求失败会返回非零状态并停止；真正生效仍需 system admin 在管理台核对变更并通过浏览器会话审批。
