brief bar_

Brief Bar — 评分服务（briefs.welance.com）

→ briefs.welance.com — 公共页面，已上线

Welance Directory	由此评分服务提供支持的引导式需求说明构建器和市场
Brief Bar	服务功能介绍 · 控制台 · 规则
API 文档	OpenAPI，每个字段均有说明
集成	四种接入工作流的方式：控制台 · 提示词 · MCP · API
你的需求说明，你的密钥	数据会传到哪里、我们会保留什么，以及如何使用你自己的密钥
隐私 · 条款	托管服务及其 MCP 连接器：由谁运行、会保留哪些数据以及保留多久、公平使用
llms.txt	面向机器编写的评分标准——让你的助手读取它

支持八种语言，无需构建步骤，不进行跟踪。页面和 API 由同一源提供。

---

根据一套开放、带版本的规则集评估数字产品需求说明。评分说明需求说明写得有多好；单独的门槛则说明是否允许发布。大模型只负责评判（在服务端运行，密钥不会离开服务器）；所有数值、门槛和决定均由确定性代码负责。

产品目标是让需求说明明确预期并开放讨论，使客户和供应商在承诺合作之前，能够了解是否合作以及如何合作。参见产品决策和当前规则覆盖情况审计。审计提出了改进建议；不会改变当前评分。

本仓库提供的是服务。规则集和引擎位于其中，作为可安装的软件包（brief_bar/），以后可以拆分成独立的开源仓库，并作为固定版本的依赖项供本服务使用——边界已经划定。

brief_bar/     the open ruleset + deterministic engine (the OSS core)
  rules/*.yaml       14 rules, weights sum to 100, ★ = gate requirement
  scoring.yaml       the €10k floor, the 4-requirement gate (anonymised is directory-context, deactivatable), the bands
  score.py           weighted average + gate + decision (no model here)
  judge.py           MockJudge (keyword, offline) + LLMJudge protocol
  llm.py             batched-judge & suggestion prompts (versioned with rules)
  fixtures/*.yaml    labelled briefs = the regression corpus / CI immune system
app/                 the FastAPI service
  main.py            routes, rate limit, CORS; mounts site/ at /
  scorer.py          mock/LLM orchestration + Redis verdict cache
site/                THE public pages: landing, console, rules — served both
                     by GitHub Pages and by the service itself (one surface)
CLAUDE.md · PLAN.md  bootstrap + phased mission for an agentic coding session
GOVERNANCE.md · CONTRIBUTING.md · CODEOWNERS · LICENSE   the open-bar machinery (MIT)
docker-compose.yml   api + redis (the only stateful dependency: ephemeral cache)

快速开始

cp .env.example .env          # add a spend-capped PB_OPENROUTER_API_KEY
make up                       # docker compose up --build -d  (api + redis)
make health                   # GET /v1/healthz
open http://localhost:8000    # the console (mock judge works with no key)

没有 API 密钥时，服务仅以模拟模式运行（即时关键词引擎，完全确定性）——足以用于开发和运行完整测试套件。添加密钥即可启用 llm 评判器和 /v1/suggest。

API

控制台可以导入不超过 10 MB（10,000,000 字节）的 PDF、UTF-8 TXT 和 Markdown 文档。文本提取在本地通过随附的 PDF.js display API 和 worker 运行；原始文件不会上传。使用 AI 评分前，请先检查提取出的文本。对导入的文档评分时会设置 no_cache: true。

API 单独的文本长度限制默认为 1,000,000 个字符（PB_REQUEST_MAX_CHARS）。现有环境变量覆盖设置仍然适用。提供方的上下文限制可能更低；成功导入不代表每个模型都能评判该文档。文本绝不会被静默截断或摘要。PDF 提取最多处理 1,000 页，且限时 60 秒；拒绝没有可提取文本的页面、受密码保护的 PDF 和格式错误的文件。必要时，请在导入前运行 OCR 或移除空白页。没有 multipart/文件存储 API。

POST /v1/score

{ "brief": "…", "locale": "it", "judge": "mock" }   // judge: "mock" | "llm"

{ "score": 92.0, "band": "Directory-ready", "decision": "blocked",
  "decision_label": "Blocked — hard requirements unmet",
  "gate": { "passed": false, "missing": ["anonymised"] },
  "verdicts": [ { "rule_id": "anonymised", "status": "fail", "confidence": 0.8,
                  "quote": "Stripe … [email protected]", "note": "identifying info present",
                  "weight": 8, "severity": "high", "gate": "pass" }, … ],
  "review_required": false, "low_confidence": [],
  "ruleset_version": "1.0.0+83107baec655", "engine": "[email protected]+83107baec655",
  "judge": "mock", "cached": false }

ruleset_version 是你的审计记录：它会精确标明评判需求说明所用的评分标准版本，而且每项评判都会附上需求说明中的原文引述作为证据——即使特定模型早已不复存在，人类仍可检查。（模拟评判器永远可复现；大模型评判器以温度 0 运行，并按 (ruleset_version, model, brief) 缓存，但温度 0 并不保证提供方更新后仍具确定性——只有这些引述永不过期。） Welance 使用 OpenRouter（PB_OPENROUTER_API_KEY）。发布评分使用 deepseek/deepseek-v4-pro；交互式建议生成使用 google/gemini-3.1-flash-lite。可自托管部署仍可配置可选的直接 Anthropic 适配器，但它不属于 Welance 部署的一部分。使用 OpenRouter 时，请求可以从服务器的允许列表中选择 model（PB_OPENROUTER_MODELS，带供应商前缀的精确模型标识，以逗号分隔）；其他值都会被拒绝并返回 422。 每项评分都会返回最终使用的模型，以便留下可复现的审计记录。 建议生成可以使用由 PB_SUGGEST_MODEL 选定的低延迟模型。单条规则建议属于可编辑的人工选项，默认只调用一次生成接口；设置 PB_SUGGEST_VERIFY=true 可恢复第二次 LLM 审核。权威评分和多项缺口修复循环会保留原有的验证行为。如果运行了验证，建议响应会注明验证模型。 服务会复用 OpenRouter 连接池，并设置独立且有上限的 输出令牌数（PB_SUGGEST_MAX_TOKENS、PB_SUGGEST_ALL_MAX_TOKENS 和 PB_VERIFIER_MAX_TOKENS），因为简短的建议 JSON 不需要评审模型那么大的额度。服务承担费用且成功生成的建议会被缓存； BYOK 调用始终绕过该共享缓存。

评审模型通常会在一次提供商调用中给出全部 14 项判定。 PB_JUDGE_BATCH_SIZE=5 则会按确定性的 5/5/4 规则分批处理，最多同时发起 PB_JUDGE_CONCURRENCY=3 次调用，然后再合并结果并进行相同的确定性汇总。这是用于调整运行延迟的选项，不是评分模式：任何批次不完整或失败，都会导致整个评分被拒绝。在已部署模型通过实时 make test-llm-batching 对比测试之前，请将其保持为默认值 0。

自带密钥：发送 X-LLM-Key: <your OpenRouter key>，调用就会使用你的密钥运行；除非此部署设置了 PB_BYOK_MODELS，否则允许使用任何有效的 OpenRouter 模型标识（费用由你承担）。密钥仅用于当前请求，不会存储或记录。BYOK 评分会有意绕过共享判定缓存，因此每次调用都由所提供的密钥支付，并会发起新的调用。请使用设有支出上限的密钥。控制台会在实时模式下将其显示为可选字段。

将密钥发送给他人的服务，值得了解的不止这一段说明。有关每个接触密钥的环节、密钥可确定不会触及的环节以及诚实说明的限制，请参阅 briefs.welance.com/security.html；tests/test_byok_leak.py 会强制执行相关要求：如果密钥出现在日志、缓存写入或响应中，该测试就会失败。

其他端点：

• POST /v1/suggest {brief, rule_id, locale, model?} → 针对单项缺口提供定制修复方案（LLM）。
• POST /v1/suggest/all {brief, rule_ids?, locale, model?} → 为每项未通过的规则提供一条修复方案；省略 rule_ids 可自动检测（LLM）。
• GET /v1/rules → 完整目录（id、title、weight、gate、criteria、references），供目录界面使用。
• GET /v1/models → 已启用的评审模型（default + available），供模型选择器使用。
• GET /v1/healthz → 服务版本、规则集版本、引擎及 LLM 可用性。
• GET / → 交互式控制台。

建议响应会包含 X-PB-Generation-Ms、X-PB-Verification-Ms、 X-PB-Cached、X-PB-Cache-Ms、X-PB-Model 和标准的 Server-Timing 标头，以便调用方区分模型延迟与网络／界面延迟，而不暴露提示词或文档内容。/v1/healthz 也会报告可选的 Redis 缓存／速率限制存储当前是否已连接。

MCP：免费，使用你自己的模型

https://briefs.welance.com/mcp 是一个免费的远程 MCP 服务（Streamable HTTP，无状态 JSON）。我们不会运行自己的模型。 由你助手自带的模型使用服务评审员的专用提示词评估简介；评分器代码会验证这些判定，并使用与 /v1/score 相同的引擎计算结果。

工具	功能
get_rules	实时目录：标准、权重、门槛、策略上下文、状态分数、等级和版本
get_brief_template	根据实时规则生成的 Markdown 简介模板，包含每个章节所需的输入
get_judge_prompt	评审提示词（与服务端逐字一致）及判定 JSON Schema，供你的模型使用
get_improvement_prompt	供你的模型改进简介时使用的门槛优先工作顺序
check_brief	仅执行确定性检查（联系人、注明的预算／时间线、数据线索、占位符）——语义覆盖不完整，绝不会给出分数
aggregate_verdicts	验证你模型的判定（每条规则恰好一次、逐字引用、实时版本）并汇总结果
bar_status	实时规则集版本和功能

也可作为提示词（score_with_your_model——完整工作流，门槛优先——judge_brief、improve_brief、brief_template）和资源（perfect-brief://rules、…/template、…/judge-prompt、…/verdict-schema）使用。同一套接口也提供纯 HTTP 形式，地址为 /v1/byo/*（参见 /docs）。

仅供参考，绝非权威。 汇总结果会标记为 evaluation_source: "client"、authoritative: false，并包含规则集版本、证据错误和模式冲突，以及 Find a team on welance/directory → 链接（PB_DIRECTORY_URL）。此结果不能用于授权发布：welance/directory 会自行通过 /v1/score 为每份简介评分。

安装

Claude（claude.ai、Desktop）：Settings → Connectors → Add custom connector → https://briefs.welance.com/mcp。Claude Code：

claude mcp add --transport http perfect-brief https://briefs.welance.com/mcp

ChatGPT：Settings → Apps & Connectors → Advanced → enable developer mode → Create → URL https://briefs.welance.com/mcp，无需身份验证 （是否可用取决于套餐）。

Cursor（~/.cursor/mcp.json 或 .cursor/mcp.json）：

{ "mcpServers": { "perfect-brief": { "url": "https://briefs.welance.com/mcp" } } }

VS Code（.vscode/mcp.json，或 MCP: Add Server… → HTTP）：

{ "servers": { "perfect-brief": { "type": "http", "url": "https://briefs.welance.com/mcp" } } }

本地（stdio）——适用于任何可运行命令的客户端，工具相同：

{ "mcpServers": { "perfect-brief": { "command": "uvx",
  "args": ["--from", "git+https://github.com/welance/perfect-brief#subdirectory=mcp-server", "perfect-brief-mcp"] } } }

协议：通过 initialize 协商 2024-11-05 → 2025-11-25 修订版（遇到未知版本时，会以 2025-11-25 响应）；也提供无状态的 2026-07-28 封装（server/discover）。不接受 JSON-RPC 批处理请求，返回 400。无会话，无事件流。

较早的连接器会调用服务评审员来执行 score_brief／suggest_fixes，地址为 /mcp-hosted，除非设置 PB_MCP_HOSTED_ENABLED=true，否则默认关闭；启用后也受相同的每地址请求限制。Official MCP Registry 的草稿条目位于 registry/。

welance.com/directory 如何使用它

Directory 只是纯粹的使用方。它负责呈现判定结果；不包含任何评分逻辑：

const res = await fetch("https://briefs.welance.com/v1/score", {
  method: "POST",
  headers: { "content-type": "application/json", "x-api-key": KEY },
  body: JSON.stringify({ brief, locale, judge: "llm" }),
}).then(r => r.json());
// res.decision drives publish/blocked/with-reservation; res.gate.missing lists why.
// persist res together with res.ruleset_version for a reproducible audit trail.

用户输入时（防抖处理）以及提交时都会评分。otto.welance.com 需要持久化判定结果时，会通过服务器间调用访问同一端点。

设计说明

• 无状态服务。 评分是 (brief, ruleset_version) 的纯函数。 没有数据库。Redis 仅保存临时的判定缓存和速率限制计数器；即使 Redis 故障，服务也能平稳降级。
• 将规则集作为依赖项。 brief_bar/ 是一个可安装的软件包，有自己的 版本和 CI 测试语料库。目前它随此处代码库一起提供；将其提取到 welance/brief-bar 并固定一个标签，只需原样迁移，无需更改代码。
• 门禁取代严重程度上限。 关键缺项是明确的发布要求（clear-title、problem-defined、budget-floor、anonymised）， 而不是对分数施加隐性扣减。
• 运营者公约。 规则评判简介； OPERATOR-COVENANT.md 评判我们——不挖掘潜在客户、不使用简介训练模型，对 welance 自己的简介采用同一标准（welance 也会以团队身份在 Directory 上发布项目简介），并标明每项承诺的执行方式；代码能够覆盖之处均由 CI 测试。
• 治理。 任何人都可以通过 PR 提议规则变更；CI 中的测试样本库是免疫系统——任何导致分数变化的变更，也必须公开更新相应测试样本。规则变更 PR 会经过 7 天的社区讨论期，之后才能合并——PR 模板会引导你完整填写提案，而 GOVERNANCE.md 则详细说明讨论时限。 对评分标准持不同意见，也是这个代码库所支持的一种重要用法。

决策

影响重大的架构决策记录在 docs/decisions/ 中，形式为 ADR：

• 0001 — 跨模型验证： 说明为什么每条 AI 建议都由第二个模型审核（避免自我偏好偏差），以及为什么审核模型目前与生成模型来自同一实验室（成本原因；修改一行环境配置即可恢复跨实验室审核）。
• 0002 — 默认模型选择： 说明选择标准、支持 DeepSeek V4 Pro/Flash 搭配方案的带日期价格快照，以及何时重新评估。

开发与测试

pip install -e ".[dev]"
make test        # fixture corpus + API tests, all on the deterministic mock judge
make lint        # ruff
make typecheck   # mypy
make dev         # uvicorn --reload on :8000

部署（OVH Kubernetes）

镜像是一个运行在 :8000 上的无状态 HTTP 服务，带有 /v1/healthz 存活探针——采用标准的 Deployment、Service 和 Ingress，外加一个小型 Redis（用于缓存，因此单副本或托管实例均可）。通过 Secret/ConfigMap 设置 PB_*；将 PB_CORS_ORIGINS 限定为 Directory 的来源。API 可水平扩展；缓存通过 Redis 共享。

文本与文档边界

API 接受文本，不接受上传文件：brief 是一个有长度限制的字符串。Directory 可以在浏览器本地读取受支持的 PDF、DOCX 和文本类文档，并将提取出的文本作为不可信上下文传入。原始字节、图像和任意二进制文件不会发送到此服务、由此服务存储，也不会作为附件发布。通过 Multipart 发布到 Directus 属于 Directory 的独立流程。

捆绑的控制台默认使用 模拟 评判器（离线、即时响应）。其实时模式会调用此服务的 /v1/score 和 /v1/suggest；除非调用方明确提供按请求使用的 BYOK 密钥，否则提供商凭据始终保留在服务端。