bensz-router Python 客户端

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

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

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

也可使用 uv tool install bensz-router；其命令通常位于 ~/.local/bin。安装 Skill 与安装 CLI 是两件事，请在 Claude Code 或 Codex 的 Shell 中执行 command -v bensz-router。macOS 图形界面启动的 Harness 可能缺少终端的 PATH；公开 Skill 会有界检查 ~/.local/bin/bensz-router 和 /opt/homebrew/bin/bensz-router。需要在常用命令目录暴露 CLI 时，可将安装器生成的命令链接到该 Harness 的 PATH 目录，保持 Python 包本身位于隔离环境。

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：

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 与幂等键发给服务端；服务端重新校验候选边界、角色、互斥组与冲突，并返回版本固定的应用清单（强制项 → 引用依赖 → 智能命中）：

# 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 在下一条用户可见回复中显示一次；只有强制项、无匹配或失败开放时不显示命中提醒。提醒只展示解析结果中已确认的工作流名称。

服务端成功返回包含智能命中或固定模板的预检结果后，管理台“使用记录”按这次预检计一次；同次命中多个工作流或幂等重试不会重复计数。仅拉取目录或仅有强制项不计入。记录表示流程已返回给 Harness，不代表后续任务完成；公开工作流无须额外调用 run 才能留下使用记录。

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

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

# 先在管理台“自动化 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 在管理台核对变更并通过浏览器会话审批。