内容
# Althing
[](https://pypi.org/project/althing/)
[](https://github.com/DataViking-Tech/Althing/actions/workflows/ci.yml)
[](LICENSE)
[](https://pypi.org/project/althing/)
[](https://github.com/DataViking-Tech/Althing/blob/main/docs/mcp.md)
[](https://github.com/DataViking-Tech/Althing/pkgs/container/althing)
[](https://ko-fi.com/dataviking)
官网：<https://althing.dev> · 基准测试：<https://synthbench.org>
**Althing 是用于 AI 代理的合成人口 MCP 服务器。**
当您的代理需要了解代表性的人类样本会对某个决策（定价、命名、摩擦点、文案等）有何看法时，它只需调用一个工具：
```jsonc
// MCP 工具调用
{
"tool": "run_panel",
"arguments": {
"pack_id": "general-consumer",
"questions": [{ "text": "您会为此启动层支付 $49 或 $79 吗？" }],
"decision_being_informed": "选择启动层价格"
}
}
// 响应（来自 `run_panel` 和 `panel run --output-format json` 的相同信封）
{
"result_id": "result-20260510-abc123",
"model": "claude-haiku-4-5",
"synthesis": {
"summary": "人群分歧在 $79；价格是主要的反对理由。",
"themes": [...],
"agreements": [...],
"disagreements": [...],
"surprises": [...],
"recommendation": "..."
},
"rounds": [{ "name": "default", "results": [...], "synthesis": null }],
"path": [],
"warnings": [],
"total_cost": "$0.0142",
"total_usage": { "input_tokens": 4231, "output_tokens": 1102, ... },
...
}
```
您将获得一个结构化的 `synthesis` 块 - 主题、同意、不同意、惊喜和一行建议，您的代理可以据此采取行动 - 以及 `rounds`[] 下的完整逐面板记录和逐次成本遥测。**请自带 LLM 密钥 - Claude、OpenAI、Gemini 或本地。** 适用于 Claude Code、Cursor、Windsurf、LangChain、CrewAI、OpenAI 代理 SDK。
> **注意（v1.0.6）：** v1.0.0 `panel_verdict` 工件（`headline`、`convergence`、`dissent_count`、`flags[]`、`schema_version`）已在 MCP 面板工具（`run_panel`、`run_quick_poll`、`extend_panel` 在 BYOK 模式下）的成功路径上发出：它位于信封的 `panel_verdict` 键下，与上面的 `synthesis` 块一起，并且响应门在出口处验证它。采样模式和集成运行不会持久化记录并且不携带裁决；CLI `panel run` 信封保持不变 - 请参阅 [docs/response-contract.md](docs/response-contract.md)。错误响应使用类型信封（`error_code`、`schema_version`、`retry_safe`）。
```bash
pip install althing
```
**冻结的契约：** v1.0.0 模式位于包中，位于 [`althing/schemas/v1.0.0.json`](src/althing/schemas/v1.0.0.json)，并且在每个持久化面板成功信封和每个类型错误（`schema_version: "1.0.0"`）上回显。按字段参考：[docs/response-contract.md](docs/response-contract.md)。从 v0.12 迁移？[docs/migration-v1.md](docs/migration-v1.md)。方法和可检查性：[docs/methodology.md](docs/methodology.md)。
**在任何支持采样的 MCP 主机中零配置**（Claude Desktop、Claude Code、Cursor、Windsurf）- 将配置放入并运行 `run_prompt` 和小型 `run_quick_poll` 调用（最多 3 个人）**无需设置 API 密钥**。主机代表您运行模型，使用其自己的订阅。完整的面板、集成和可复制的模型固定需要您自己的提供者密钥。人和仪器是普通的 YAML；每个响应都经过模式验证，并带有逐次成本遥测。
## 为什么
传统的焦点小组费用为 $5,000-$15,000，需要数周时间。合成小组的费用仅为几美分，时间仅为几秒。它们不能取代真正的用户研究，但它们非常适合：
- **预先筛选** 调查工具，以避免在真正的参与者上花费预算
- **快速迭代** 产品名称、文案和定位
- **假设生成** 跨人口统计学段
- **概念测试** 达到思想的速度
## 代理快速入门
> **新来者？** [**docs/agent-quickstart.md**](docs/agent-quickstart.md) 是完整的端到端演练 - 安装 → 验证 → 试运行 → 运行 → 30-40 人物投票 → 保存 → 发出 JSON，适用于 CLI 和 MCP 接口，具有结构化输出示例。下面是代码片段的简要版本。
将 MCP 服务器连接到您的编辑器（参见下面的 [与 Claude Code / Cursor / Windsurf / Zed 结合使用](#use-with-claude-code--cursor--windsurf--zed)），并从代理代码调用四个研究工具。每个运行面板的调用都需要一个 `decision_being_informed` 字段（12-280 个字符，单行）- 没有它，面板就不会运行。
```jsonc
// run_panel - 完整的合成焦点小组
{
"tool": "run_panel",
"arguments": {
"pack_id": "general-consumer",
"instrument_pack": "pricing-discovery",
"decision_being_informed": "选择启动层价格"
}
}
// run_quick_poll - 针对多个个人的一个问题
{
"tool": "run_quick_poll",
"arguments": {
"question": "哪个名称感觉最优质：Core、Plus 或 Pro？",
"pack_id": "general-consumer",
"decision_being_informed": "命名付费层"
}
}
// extend_panel - 追加一个临时后续回合
{
"tool": "extend_panel",
"arguments": {
"result_id": "result-20260503-abc123",
"questions": ["如果它明天发布，您会为此支付多少？"],
"decision_being_informed": "验证独立定价上限"
}
}
```
阅读 `synthesis.recommendation` 获取标题调用，`synthesis.disagreements` 获取异议，`rounds[].results[]` 获取每个面板的记录。有关完整的 v1.0.0 信封，请参阅 [docs/response-contract.md](docs/response-contract.md)（截至 v1.0.6，`panel_verdict` - `headline`、`convergence`、`dissent_count`、`flags[]` 在 MCP 面板工具的成功路径上发出；请参阅开头的注释，了解采样模式/集成异常）。
**结构化投票是代理的默认设置。** 对于选择、Likert、置信度和标签主题的问题，请传递一个有界的 `response_schema`，以便面板成员返回解析的 JSON 而不是散文。无需正则表达式，无需事后解析。请参阅 [docs/structured-polling.md](docs/structured-polling.md)，获取完整的模式目录和可运行的 35 人优先级示例。
## 人类操作员快速入门
更喜欢终端？相同的引擎，CLI 接口。根据您使用 Python 工具的方式选择安装路径：
| 路径 | 何时 | 命令 |
|------|------|---------|
| **pip** （在您的项目虚拟环境中） | 您正在将 Althing 作为库集成 | `pip install althing` |
| **pip + MCP** （在您的项目虚拟环境中） | 您还想要用于代理集成的 MCP 服务器 | `pip install 'althing[mcp]'` |
| **pipx** （全局，隔离） | 您希望在 PATH 上安装 `althing` 而不污染任何项目 | `pipx install althing` |
| **uvx** （零安装） | 您只想运行一次 - 根本不需要安装 | `uvx --from althing althing --help` |
| **source** （最新未发布） | 您希望在下一个 PyPI 版本之前使用主分支修复 | `pip install git+https://github.com/DataViking-Tech/Althing.git@main` |
安装后，请在配置提供者之前验证 CLI 是否在您的 PATH 上并且运行时正常：
```bash
althing --version # 测试：包元数据 + 入口点调度
althing doctor --install-only # 仅安装健康检查 - 无需凭据
althing doctor # 完整预飞行检查（安装 + 凭据）
althing whoami # 哪些提供者（如果有）有凭据
```
### 包名与模块名
PyPI 发行版和 CLI 入口点均为 **`althing`** （一个单词）。可导入的 Python 模块 - 历史上的 PEP 8 拼写方式 - 为 **`althing`** （两个单词，蛇形命名）：
```python
import althing # 规范
from althing import run_panel, sdk # 库使用
```
```bash
althing --version # CLI
python -m althing --version # 规范模块形式
python -m althing --version # 单词别名也有效（sy-het）
```
这两个拼写方式都解析为相同的代码。单字模块 `althing` 是一个薄壳（`__path__` 重定向 + `__main__.py`），用于确保通过 `python -m <pypi-name>` 猜测的代理不会遇到障碍。新代码仍应首选 `import althing` - 它是 `__all__`、文档和模式所引用的内容。
`doctor` 在缺少内容时退出并带有可行性指导（未配置提供者、错误的 Python、缺少 MCP 额外内容等）- 它是规范的“安装是否干净？”检查，并且 `clean-install-smoke` 在 CI 中运行相同的序列，对于每次推送都会针对构建的轮进行检查，因此所有三个命令都是受支持的契约的一部分。
使用 `althing doctor --install-only` 立即在 `pip install althing` 后验证包、依赖项和捆绑包，而无需配置提供者密钥 - 该模式下的退出 0 表示安装健康，即使尚未配置凭据。JSON 输出（`--output-format json doctor --install-only`）将 `install_ok`、`credential_configured` 和 `checks_ok` 分开，以便代理和 CI 可以独立地在每个表面分支。
然后提供一个 API 密钥（Claude、OpenAI、Gemini、xAI 或任何 OpenAI 兼容的提供者）- 要么在您的 shell 中导出它，要么通过 `althing login` 持久化：
```bash
export ANTHROPIC_API_KEY="sk-..."
# 或
althing login --provider anthropic --api-key sk-... # 存储在
# ~/.config/althing/credentials.json，模式 0600
althing whoami
# 运行单个提示
althing prompt "您认为 Traitprint 这个名称对于职业应用来说意味着什么？"
# 运行完整的面板
althing panel run \
--personas examples/personas.yaml \
--instrument examples/survey.yaml
```
## 兼容列表
Althing 是 **MCP 原生** 的 - 它附带了一个 MCP 服务器，并且每个主要的代理框架现在都支持 MCP 作为一级工具源。这意味着 Althing 与任何支持 MCP 的框架无缝协作，无需安装特定的框架包装器。每个框架的可运行示例都位于
[`examples/integrations/`](examples/integrations/README.md)。
| 框架 | 示例 | 桥接 | 一行安装 |
|-----------|---------|--------|------------------|
| [OpenAI 代理 SDK](https://openai.github.io/openai-agents-python/mcp/) | [openai_agents.py](examples/integrations/openai_agents.py) | 内置 `MCPServerStdio` | `pip install openai-agents althing[mcp]` |
| [LlamaIndex](https://docs.llamaindex.ai/) | [llamaindex_tool.py](examples/integrations/llamaindex_tool.py) | `llama-index-tools-mcp` | `pip install llama-index-tools-mcp llama-index-llms-anthropic althing[mcp]` |
| [CrewAI](https://docs.crewai.com/) | [crewai_tool.py](examples/integrations/crewai_tool.py) | `crewai-tools[mcp]` | `pip install "crewai-tools[mcp]" crewai althing[mcp]` |
| [LangChain](https://python.langchain.com/) | [langchain_tool.py](examples/integrations/langchain_tool.py) | `langchain-mcp-adapters` | `pip install langchain-mcp-adapters langchain-anthropic althing[mcp]` |
| [LangGraph](https://langchain-ai.github.io/langgraph/) | [langchain_tool.py](examples/integrations/langchain_tool.py) | `langchain-mcp-adapters` | `pip install langchain-mcp-adapters langgraph langchain-anthropic althing[mcp]` |
| [Microsoft 代理框架 1.0](https://learn.microsoft.com/en-us/agent-framework/) | [microsoft_agent.py](examples/integrations/microsoft_agent.py) | 内置 `MCPStdioTool` | `pip install agent-framework althing[mcp]` |
| [n8n](https://n8n.io/) | [n8n_workflow.json](examples/integrations/n8n_workflow.json) | 内置 MCP 客户端工具 | 在 n8n 运行器上 `pip install althing[mcp]` |
| [通过 Composio 的 LangChain](https://composio.dev/) | [composio_langchain.py](examples/integrations/composio_langchain.py) | `althing.integrations.composio`（进程内，非 MCP） | `pip install composio composio_langchain langchain langchain-anthropic althing` |
| [通过 Composio 的 CrewAI](https://composio.dev/) | [composio_crewai.py](examples/integrations/composio_crewai.py) | `althing.integrations.composio`（进程内，非 MCP） | `pip install composio composio_crewai crewai althing` |
还支持 [Zapier MCP](https://zapier.com/mcp) （30K+ 动作）、[VS Code AI 工具包](https://code.visualstudio.com/api/extension-guides/ai/mcp)、Windsurf、Cursor、Zed、Claude Code 和 Claude Desktop，方式相同 - 所有客户端都通过 `pip install althing[mcp]` 和一行 MCP 配置项进行安装（参见[与 Claude Code / Cursor / Windsurf / Zed 结合使用](#use-with-claude-code--cursor--windsurf--zed)）。
> **看不到您的框架？** 几乎所有主要的代理框架都有可用的 MCP 桥接器。从
> [`examples/integrations/README.md`](examples/integrations/README.md)
> 开始 - 每个示例中的模式相同（将客户端指向
> `althing mcp-serve` via stdio）- 或
> [提交问题](https://github.com/DataViking-Tech/Althing/issues)
> 以便我们添加一个同伴示例。
## 使用 Docker 运行
预构建的镜像发布到
[GitHub 容器注册表](https://github.com/DataViking-Tech/Althing/pkgs/container/althing)
和 Docker Hub 上的每个标记版本。使用它进行短暂或无服务器调用（Lambda、Cloud Run、GitHub Actions、n8n），您更愿意启动容器而不是 pip 安装。
```bash
# 拉取（任一注册表都有效 - 相同的镜像，多架构：amd64 + arm64）
docker pull ghcr.io/dataviking-tech/althing:latest
docker pull althing/althing:latest
# 单次提示
docker run --rm \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
althing/althing \
prompt "什么使得一个名称值得信赖？"
# 统计输入的MCP服务器（默认CMD - 将其连接到代理的MCP配置）
docker run --rm -i \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
althing/althing
# 面板运行，带有挂载的仪器文件
docker run --rm \
-e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
-v "$PWD":/work -w /work \
althing/althing \
panel run --personas personas.yaml --instrument survey.yaml
```
镜像的默认 `CMD` 是 `mcp-serve`，因此省略命令将启动MCP标准输入服务器。可以传递任何 `althing` 子命令作为参数来覆盖。提供者密钥从环境变量中读取
（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY`、`GOOGLE_API_KEY`/`GEMINI_API_KEY`、`XAI_API_KEY`）- 传递您模型所需的任何一个。
在生产环境中，请固定到版本标签而不是 `:latest` - 准确的发布版本（`:1.5.7`）或浮动的主次版本标签（`:1.5`），两者都在稳定版本发布时发布。
## 作为Python库使用
CLI和MCP服务器可以做的所有事情也可以从Python调用。无需子进程，无需额外安装 - 只需导入即可。
```python
from althing import quick_poll, run_panel, run_prompt
# 一次LLM调用
reply = run_prompt("什么使得一个名称值得信赖？")
print(reply.response, reply.cost)
# 向捆绑的个人资料包询问一个问题
poll = quick_poll(
"哪个定价层名称感觉最优质：Core、Plus还是Pro？",
pack_id="general-consumer",
)
print(poll.synthesis["recommendation"])
# 对捆绑包运行完整的分支仪器
panel = run_panel(
pack_id="general-consumer",
instrument_pack="pricing-discovery",
)
print(panel.path) # e.g. ["discovery", "probe_pricing", "validation"]
print(panel.total_cost)
```
包根目录公开了八个函数和三个类型化的返回
数据类 - `PromptResult`、`PollResult`、`PanelResult`。每个结果都是字典兼容的（`result["model"]`），因此以前使用MCP JSON有效负载的代码保持不变。
| 函数 | 功能 |
|----------|--------------|
| `run_prompt(prompt, *, model=...)` | 单个LLM调用 - 无个人资料 |
| `quick_poll(question, pack_id=...)` | 面板上的一个问题 + 综合分析 |
| `run_panel(pack_id=..., instrument_pack=...)` | 完整的分支面板运行 |
| `extend_panel(result_id, questions)` | 追加一个临时后续回合 |
| `list_personas()` / `list_instruments()` | 发现已安装的包 |
| `list_panel_results()` / `get_panel_result(id)` | 重新加载已保存的结果 |
在性能瓶颈处（Jupyter，serverless，CI）或您希望在三行代码中将Althing包装在LangChain / LlamaIndex工具中时使用此路径。参阅
[`examples/sdk_usage.py`](examples/sdk_usage.py)，获取一个可运行的端到端演练示例。
### 使用 Pydantic 进行类型化提取 (1.0.4)
`run_panel` 直接接受 `pydantic.BaseModel` 子类作为 `extract_schema` 参数。Althing 通过 `model_json_schema()` 生成 wire JSON 模式，并在每个 panelist 的提取有效载荷上运行 `model_validate` — 验证失败会作为 `extraction_validation_error` 在每个响应中显示（即使 LLM 生成的 wire-valid JSON 违反了类型约束，例如 `rating: 7` 与 1..5 的 `Likert` 量表）。
```python
from pydantic import BaseModel, Field
from althing import run_panel
class 功能选择(BaseModel):
功能: str = Field(..., min_length=1)
置信度: int = Field(..., ge=1, le=5)
result = run_panel(
pack_id="developers",
questions=[{"text": "我们应该优先发布哪个功能？"}],
extract_schema=功能选择, # 在 SDK 边界接受类型化类
)
for r in result.results:
extracted = r["responses"][0].get("extraction")
if extracted is not None:
choice = 功能选择.model_validate(extracted)
print(choice.功能, choice.置信度)
```
相同的参数仍然接受内置名称（`"sentiment"`、`"likert"`、`"pick_one"` 等）或内联 JSON 模式字典 — 类型化类是一种额外的调度方式，而不是替换。
## MCP 服务器（代理集成）
Althing 附带一个 MCP 服务器，以便 AI 代理可以运行合成焦点小组作为工具调用。
```bash
pip install althing[mcp]
althing mcp-serve
```
添加到编辑器的 MCP 配置（Claude Code、Cursor、Windsurf）：
```json
{
"mcpServers": {
"althing": {
"command": "althing",
"args": ["mcp-serve"],
"env": { "ANTHROPIC_API_KEY": "sk-..." }
}
}
}
```
### 通过采样进行零配置首次运行
没有 API 密钥？没问题。当调用 MCP 客户端（Claude Desktop、Claude Code、Cursor、Windsurf）宣传 `sampling` 功能时，Althing 會退回到要求客户端代表其运行 LLM 补全 — 使用客户端自己的订阅。这意味着 `run_prompt` 和小型 `run_quick_poll` 调用（最多 3 个角色）可以在零环境设置下工作：
```json
{
"mcpServers": {
"althing": {
"command": "althing",
"args": ["mcp-serve"]
}
}
}
```
采样模式非常适合首次接触 UX 和快速探索性投票。对于跨提供商的集成、更大的面板和可复制的模型版本控制，请在 `env` 中设置提供商密钥以升级到 BYOK。请参阅 [docs/mcp.md#model-resolution-order](docs/mcp.md#model-resolution-order) 以获取完整的采样触发矩阵和每个提供商密钥选择的默认模型。
### 工具（12）
| 工具 | 描述 |
|------|-------------|
| `run_prompt` | 向 LLM 发送单个提示 — 不需要角色 |
| `run_panel` | 运行具有并行 panelists 和综合的完整合成焦点小组面板 |
| `run_quick_poll` | 跨角色的快速单问题投票，带有综合 |
| `extend_panel` | 将临时后续轮次追加到已保存的面板结果 |
| `list_persona_packs` | 列出所有已保存的角色包（捆绑 + 用户保存） |
| `get_persona_pack` | 按 ID 获取特定的角色包 |
| `save_persona_pack` | 保存角色包以供重复使用 |
| `list_instrument_packs` | 列出已安装的仪器包（捆绑 + 用户保存） |
| `get_instrument_pack` | 按名称加载已安装的仪器包 |
| `save_instrument_pack` | 安装具有验证的仪器包 |
| `list_panel_results` | 列出所有已保存的面板结果 |
| `get_panel_result` | 获取具有所有轮次和综合的特定面板结果 |
`run_panel` 接受内联 `instrument` 字典或 `instrument_pack` 名称用于 v3 分支运行。`extend_panel` 追加一个临时轮次 — 它 **不是** 重新进入 v3 DAG。请参阅 [docs/mcp.md](docs/mcp.md) 以获取完整的工具模式、资源和提示模板。
## 与 Claude Code / Cursor / Windsurf / Zed 结合使用
适用于任何受支持的编辑器的单行命令（写入下面部分中所示的 JSON，合并到现有的配置中，非破坏性）：
```bash
althing mcp install --host auto # 检测已安装的编辑器并确认每个
```
或显式选择主机：`--host claude-code | claude-desktop | cursor | windsurf | zed`。`--dry-run` 预览更改；`althing mcp uninstall` 删除它管理的确切条目。除非您传递 `--env`，否则不会写入 API 密钥 — 在环境中设置提供商密钥或运行 `althing login`（支持采样的主机根本不需要密钥）。
更喜欢手动编辑？将您编辑器的 JSON 代码段复制到列出的配置文件中，设置您的 API 密钥，然后重启编辑器。`althing mcp-serve` 按需通过 stdio 启动 — 无需管理长期运行的进程。
<details>
<summary><b>Claude Code</b></summary>
```bash
althing mcp install # ~/.claude.json（所有项目）
althing mcp install --scope project # ./.mcp.json（检查）
```
或添加到项目根目录的 `.mcp.json`（或 `~/.claude.json` 用于所有项目）：
```json
{
"mcpServers": {
"althing": {
"command": "althing",
"args": ["mcp-serve"],
"env": { "ANTHROPIC_API_KEY": "sk-..." }
}
}
}
```
或安装捆绑插件（添加 `/althing-poll <question>` 斜杠命令和五个技能 — `focus-group`、`name-test`、`concept-test`、`survey-prescreen`、`pricing-probe`）：
```
/plugin install althing
```
不是使用 Claude Code，还是更喜欢手动安装？请参阅 [`docs/agent-skills.md`](docs/agent-skills.md) 以获取基于 `cp` 的安装步骤和每主机指南。
</details>
<details>
<summary><b>Cursor</b></summary>
```bash
althing mcp install --host cursor # ~/.cursor/mcp.json（所有项目）
althing mcp install --host cursor --scope project # ./.cursor/mcp.json
```
或添加到项目根目录的 `.cursor/mcp.json`（或 `~/.cursor/mcp.json` 用于所有项目）：
```json
{
"mcpServers": {
"althing": {
"command": "althing",
"args": ["mcp-serve"],
"env": { "ANTHROPIC_API_KEY": "sk-..." }
}
}
}
```
</details>
<details>
<summary><b>Windsurf</b></summary>
```bash
althing mcp install --host windsurf # ~/.codeium/windsurf/mcp_config.json
```
或添加到 `~/.codeium/windsurf/mcp_config.json`（或打开 **设置 → Windsurf 设置 → MCP 服务器 → 查看原始配置**）：
```json
{
"mcpServers": {
"althing": {
"command": "althing",
"args": ["mcp-serve"],
"env": { "ANTHROPIC_API_KEY": "sk-..." }
}
}
}
```
</details>
<details>
<summary><b>Zed</b></summary>
```bash
althing mcp install --host zed # ~/.config/zed/settings.json（context_servers 模式）
```
或手动编辑 — Zed 使用 `context_servers`（不是 `mcpServers`）。添加到 `~/.config/zed/settings.json`：
```json
{
"context_servers": {
"althing": {
"source": "custom",
"command": "althing",
"args": ["mcp-serve"],
"env": { "ANTHROPIC_API_KEY": "sk-..." }
}
}
}
```
</details>
<details>
<summary><b>Hermes</b></summary>
Hermes 使用 YAML 配置文件，包含 `mcp_servers` 和显式超时字段。将以下代码块添加到您的 Hermes 配置文件中：
```yml
mcp_servers:
althing:
command: "althing"
args: ["mcp-serve"]
timeout: 180
connect_timeout: 60
env:
ANTHROPIC_API_KEY: "sk-..."
```
或在不进行全局安装的情况下，通过 `uvx` 按需运行：
```yml
mcp_servers:
althing:
command: "uvx"
args: ["--from", "althing[mcp]", "althing", "mcp-serve"]
timeout: 180
connect_timeout: 60
env:
ANTHROPIC_API_KEY: "sk-..."
```
180 秒的 `timeout` 涵盖了完整的面板运行；60 秒的 `connect_timeout` 为子进程在首次启动时导入 MCP SDK 留出了空间。
</details>
<details>
<summary><b>Claude Desktop</b></summary>
```bash
althing mcp install --host claude-desktop # 平台特定的配置路径
```
或打开 **设置 → 开发者 → 编辑配置**（或直接编辑文件）：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"althing": {
"command": "althing",
"args": ["mcp-serve"],
"env": { "ANTHROPIC_API_KEY": "sk-..." }
}
}
}
```
重启 Claude Desktop 后编辑。
</details>
> **使用非Anthropic提供商？** 将 `ANTHROPIC_API_KEY` 替换为 `OPENAI_API_KEY`、`GEMINI_API_KEY`、`XAI_API_KEY` 或 `OPENROUTER_API_KEY` — 请参阅 [LLM 提供商支持](#llm-provider-support)。`althing` 二进制文件必须位于编辑器的 `PATH` 中；如果您安装到虚拟环境中，请将 `command` 指向其绝对路径（例如 `/path/to/.venv/bin/althing`）。
## 您获得的内容
```
============================================================
角色：Sarah Chen（产品经理，34）
============================================================
问：您的工作流程中最令人沮丧的部分是什么？
答：文档版本控制不进入适当的系统...
费用：$0.0779
============================================================
角色：Marcus Johnson（小企业主，52）
============================================================
问：您的工作流程中最令人沮丧的部分是什么？
答：我会将菜单更新发送给我的经理，经理进行更改，然后发送回来...
费用：$0.0761
============================================================
总计：estimated_cost=$0.2360
```
每个角色都以其独特的语气、关切和视角作出回应。成本被跟踪并打印每个角色和总计。
### 事后 Markdown 报告（`althing report`）
已经有一个保存的面板结果，并希望一个可读的共享结果？将结果渲染为 Markdown：
```bash
# 首先保存一个运行。--save 打印结果 ID 和确切的后续命令
# （报告 / 结果显示 / 结果列表），因此无需刮取散文或搜索
# 文件系统中的工件。
althing panel run \
--personas examples/personas.yaml \
--instrument examples/survey.yaml \
--save
# 渲染到 stdout，可以通过结果 ID 或路径到结果 JSON
althing report <result-id>
althing report path/to/result.json
# 写入文件
althing report <result-id> -o report.md
```
**机器可读句柄（代理）：** 将 `--save` 与 `--output-format json` 配对，在 stdout JSON 中添加了两个稳定的顶级键 — `result_id`（保存的句柄）和 `saved_path`（其绝对路径）。将 `result_id` 直接输入 `report`、`results show`、`analyze` 或 MCP 工具，无需刮取 stderr `Result saved:` 行或猜测文件位置。这些键仅在 `--save` 激活时存在；检查点运行还会显示其检查点 `run_id`。人类面向的 `Result saved:` 提示仍然输出到 stderr，保持 stdout 纯粹的 JSON。
#### 发现保存的结果（`althing results`）
`--save` 将写入结果存储（`~/.althing/results`），该存储 **不同于** `althing runs list` 显示的检查点存储。要通过其稳定 ID 重新发现保存的运行：
```bash
althing results list # 所有保存的结果，新建的排在最前面
althing results show <result-id> # 源代码 + 规范的 saved_path
```
`results show` 打印记录的源代码（Althing/Python 版本、配置哈希、定价快照日期）和规范的 `saved_path`；在 `--output-format json` 中，它会发出完整的 结果信封 和 `saved_path`。保存的结果现在嵌入了一个 `metadata` 块，因此 `report` 新保存运行的源代码是填充的，而不是 `(unknown)`。
每个渲染的报告都以强制的合成面板横幅开头，并以匹配的页脚结尾，因此输出不能被误认为是真实用户研究：
```markdown
# 面板报告：<result-id>
> **合成面板.** 以下所有回答均由 AI 角色生成，
> 而不是人类受访者。不要将其作为用户研究数据引用。
...
_Generated by althing report. Synthetic panel — AI-generated responses, not human data._
```
`report` 仅限于 Markdown v1 — 源代码、每个模型的汇总、角色摘要、综合和失败统计。HTML 和图表渲染被推迟到 v2。存在一个 `report` 可选依赖项额外文件（`pip install althing[report]`），可以干净地安装，但目前为空 — 它是一个前向兼容插槽，用于 v2 HTML 依赖项，今天添加了什么。
完整规格：[`specs/sp-viz-layer/`](specs/sp-viz-layer/).
## 包：内置 vs 注册表
Althing 有两种类型的包，这种区别在您搜索包时很重要：
- **内置包** 位于 `althing` 轮中。安装 `pip install althing` 后，它们可以立即通过名称解析 — 无需 `pack import`，无需网络。在任何接受 `--personas` 或 `--instrument` 参数的位置，都可以引用它们（统一解析器也接受 YAML 路径）。
- **注册表包** 由社区作者创建。它们位于第三方 GitHub 仓库中，列在 [`DataViking-Tech/althing-registry`](https://github.com/DataViking-Tech/althing-registry) 中。您可以使用 `althing pack import gh:user/repo` 导入它们；导入后，它们可以像内置包一样通过名称解析。请参阅 [docs/registry.md](docs/registry.md) 以获取 URI 形式、验证、离线缓存和提交流程。
### 内置角色包（14，共 232 个角色）
| 包 | 角色 |
|------|----------|
| `ai-eval-buyers` | 20 |
| `broad-professionals` | 20 |
| `developer` | 15 |
| `enterprise-ai-buyers` | 18 |
| `enterprise-buyer` | 15 |
| `general-consumer` | 15 |
| `healthcare-patient` | 15 |
| `job-seekers` | 15 |
| `market-research-critics` | 16 |
| `product-research` | 20 |
| `recruiters-talent` | 15 |
| `skeptical-executives` | 18 |
| `startup-founder` | 15 |
| `students` | 15 |
`althing pack list`（或 MCP `list_persona_packs`）枚举这些以及任何用户保存的包。选择适合您任务的包？请参阅 [docs/task-recommendations.md](docs/task-recommendations.md) 以获取任务 → 包 → 模型配置矩阵，并附有复制和粘贴命令。
### 内置仪器包（8，所有 v3 分支）
`churn-diagnosis`、`feature-prioritization`、`general-survey`、`landing-page-comprehension`、`market-research`、`name-test`、`pricing-discovery`、`product-feedback`。
`althing instruments list` 枚举这些以及任何已安装的包。
如果您在注册表中搜索上述名称时发现为空，则这是预期的 — 它们是 SDK 内置项，而不是注册表条目。在 `panel run --personas <name>` 或 `--instrument <name>` 时直接使用名称。
## 定义角色
```yml
# personas.yaml
personas:
- name: Sarah Chen
age: 34
occupation: 产品经理
background: >
在一家中型 SaaS 公司工作。8 年技术经验，
曾是软件工程师。管理一个 5 人团队。
personality_traits:
- 分析型
- 务实
- 注重细节
- name: Marcus Johnson
age: 52
occupation: 小企业主
background: >
经营一个有 3 个地点的家族餐厅。
不太懂技术，但认识到数字工具的必要性。
personality_traits:
- 务实
- 对技术持怀疑态度
- 重视人际关系
```
### 合并额外角色（`--personas-merge`）
在不编辑原始文件的情况下，将额外的角色叠加到基准文件（或导出的包）上。 `--personas-merge` 是可重复的，按顺序追加；如果后续角色的 `name` 与前面的角色匹配，则在原位替换：
```bash
althing panel run \
--personas developer.yaml \
--personas-merge contrarian.yaml \
--personas-merge intern.yaml \
--instrument pricing-discovery \
--var problem="choosing a project management tool"
```
## 社区包
您可以直接从 GitHub 导入角色包：
```bash
# 在 althing 注册表中列出 - 通过 gh: URI 导入
althing pack import gh:dataviking-tech/example-pack
# 尚未在注册表中 - 显式选择加入
althing pack import gh:alice/my-pack --unverified
```
注册表本身是一个开放的、基于 PR 的索引，位于
[`DataViking-Tech/althing-registry`](https://github.com/DataViking-Tech/althing-registry)。请参阅 [docs/registry.md](docs/registry.md) 以获取完整的参考资料 — 支持的 URL 形式、缓存 + 离线行为、冲突规则以及发布您自己的包的流程。
## 定义仪器
```yml
# survey.yaml
instrument:
questions:
- text: >
在与其他人合作时，您当前的工作流程中最令人沮丧的部分是什么？
response_schema:
type: text
follow_ups:
- "您能描述一个最近的具体例子吗？"
- text: >
如果您可以改变一件事来改善您与技术每天的工作方式，那么是什么？
response_schema:
type: text
```
### 附件 — 向小组成员展示截图、实时网址、PDF 或 HTML
工具可以携带一个**附件库**，以便小组成员对某些视觉或外部内容做出反应，而不是（或除了）问题文本。在工具中声明一个顶级 `attachments:` 映射，并通过 ID 从问题的 `attachments:` 列表中引用条目。支持四种类型：
| 类型 | 来源 | 使用场景 |
|------|--------|----------|
| `image` | `base64`、`url` 或 `file_id` | 截图、模型图或照片。 |
| `document` | `base64`、`url` 或 `file_id` | PDF（规格、简介、合同）。 |
| `url` | 运行时获取的实时网址 | 真实的、当前在线的页面。 |
| `html` | 内联字符串 | 字面标记片段（定价块、电子邮件、复制变体）。 |
```yaml
instrument:
version: 3
attachments:
landing_page:
type: url
url: https://example.com
fetch_mode: screenshot # auto | html_text | markdown | screenshot
rounds:
- name: reaction
questions:
- text: "这个工作室做什么，它是否适合像你这样的人？"
attachments: [landing_page]
```
> **两个需要注意的重要问题：**
> - **`image` / `screenshot` 附件需要具备视觉能力的模型。** 纯文本模型（例如 `claude-3.5-haiku`）会快速被拒绝，并出现明确的错误 — 请使用诸如 `claude-haiku-4.5`、`gpt-4o-mini` 或 `gemini-2.0-flash` 等多模态模型。
> - **`fetch_mode: screenshot` 需要视觉额外功能：** `pip install 'althing[visual]'`（安装 Playwright；然后 `python -m playwright install chromium`）。文本模式（`markdown` / `html_text`）不需要它。
完整指南和可运行的启动器：[docs/cookbook/with-attachments.md](docs/cookbook/with-attachments.md)。
## 自适应研究（0.5.0）：分支工具
v3 工具是*轮次*的小型有向无环图（DAG）。在每个轮次之后，路由谓词会根据合成器的主题和建议决定下一个运行的轮次。小组选择自己的探测路径 — 无需人工干预，无需手动编码条件流程。
```bash
# Show HN 演示：~$0.20，一个命令，面板决定
# 是否深入探讨痛点、定价或替代方案。
althing panel run \
--personas examples/personas.yaml \
--instrument pricing-discovery \
--var problem="choosing a project management tool"
```
`pricing-discovery` 是八个捆绑的 v3 工具包之一（参见上面的[内置工具包](#builtin-instrument-packs-8-all-v3-branching)）。使用 `althing instruments list` 列出它们。
输出现在包含一个 `path` 数组，记录了实际触发的路由决策：
```
discovery -> probe[themes contains price] -> probe_pricing -> validation
```
渲染任何工具的 DAG：
```bash
althing instruments graph pricing-discovery --format mermaid
```
### CLI 标志支持多轮运行
`panel run` 通过与 MCP 和 SDK 接口相同的路由器驱动引擎执行多轮（v2 线性 / v3 分支）工具。大多数标志的工作方式相同；目前只有几个功能仅在单轮路径中启用，并且**会提前拒绝**（退出 1，在任何 LLM 开支之前），而不是静默降级：
| 支持多轮工具 | 拒绝（目前仅限单轮） |
|---|---|
| `--model`、加权 `--models m:w,...`、每人 YAML 模型覆盖、`--best-model-for` | `--models a,b` 集成比较、`--blend` |
| `--temperature`、`--top-p`、`--seed` | `--variants`（鲁棒性扰动） |
| `--schema`、`--extract-schema` | `--resume`、`--checkpoint-dir`、`--checkpoint-every`、`--allow-drift`、`--force-overwrite`（检查点） |
| `--synthesis-model`、`--synthesis-prompt`、`--synthesis-temperature` | `--max-cost`（运行时成本门控）、`--question-failure-budget` |
| `--var` / `--vars-file`、`--prompt-template`、工具嵌入的 `system_prompt_template` | `--convergence-*`、`--auto-stop`、`--calibrate-against`、`--submit-to-synthbench` |
| `--save`、`--strict`、`--failure-threshold` | `--synthesis-strategy=map-reduce`、`--synthesis-auto-escalate` |
| `--max-concurrent`、`--rate-limit-rps`、`--skip-preflight`、`--personas-merge` | `--allow-empty-attachments` |
| `--dry-run`（预览 DAG 并命名引擎） | 分支工具上的 `--no-synthesis` — `route_when` 评估的是每轮合成。 （在具有无 `route_when` 的线性 v2/v3 工具上允许。） |
兼容性审计也在 `--dry-run` 上运行，因此 dry-run "OK" 总意味着真实运行是可运行的。请注意，对于分支工具，dry-run 问题/调用/成本数据涵盖每个声明的轮次，是一上限 — 路由在运行时决定执行的路径。
### 谓词参考
`route_when` 是一个按顺序评估的从句列表。第一个匹配的从句获胜；`else` 从句是**必填**的，作为最后一个条目。
```yaml
route_when:
- if: { field: themes, op: contains, value: price }
goto: probe_pricing
- if: { field: recommendation, op: matches, value: "(?i)wait|delay" }
goto: probe_objections
- else: __end__
```
| 字段 | 来源 |
|-------|--------|
| `themes` | `SynthesisResult.themes`（列表，子字符串匹配） |
| `recommendation` | `SynthesisResult.recommendation`（字符串） |
| `disagreements`、`agreements`、`surprises` | `SynthesisResult`（列表） |
| `summary` | `SynthesisResult.summary`（字符串） |
| 操作符 | 含义 |
|----|---------|
| `contains` | 针对任何列表条目或字符串的子字符串匹配 |
| `equals` | 精确的字符串匹配 |
| `matches` | Python 正则表达式匹配（使用 `(?i)` 进行不区分大小写） |
保留目标 `__end__` 终止运行；到目前为止的路径将提供最终的合成。
### 主题匹配：R3 警告
> **谓词与合成器的*精确*主题字符串匹配。**
`themes contains price` 仅在合成器实际发出包含子字符串 `price` 的主题时触发。LLM 合成器转述 — “成本问题” 或 “价格冲击” 不会匹配。捆绑的软件包通过在工具顶部添加注释块来缓解这个问题，提示合成器应首选的规范主题标签：
```yaml
# 合成器指南：发出 `themes` 时，请优先使用下面的简短
# 规范标签，以便 `route_when` 谓词可靠匹配：
# - "pain" （工作流程痛点、沮丧、现状不佳）
# - "price" （成本问题、感知价值、价格冲击）
# - "alternative" （现有工具、变通方法、竞争对手）
```
当您编写自己的 v3 软件包时，**始终**添加类似的标签提示块。合成器读取它并倾向于使用规范标签；您的 `contains` 谓词然后可靠地路由。如果您跳过此步骤，请预计路由会静默地落入 `else`，因为合成器的主题标签与您的谓词值不匹配。
首选简短的、小写、单令牌标签（`price`、`pain`、`confusion`）而不是长短语。`contains` 执行子字符串匹配，因此 `price` 也将匹配 `pricing`、`priced` 等。
### `instruments` 子命令
```bash
althing instruments list # 捆绑 + 已安装的软件包
althing instruments show pricing-discovery # 完整的 YAML 正文
althing instruments install ./my-pack.yaml # 添加本地软件包
althing instruments graph pricing-discovery # 文本 DAG
althing instruments graph pricing-discovery \
--format mermaid # mermaid 流程图
```
统一的工具解析器（由 `panel run --instrument` 使用）接受 YAML 路径*或*已安装的软件包名称，因此您可以迭代本地文件，然后在稳定时`安装`它。
## 示例
[`examples/`](examples/) 目录提供了一个角色包和每个格式（v1 平面、v2 线性、v3 分支）的工具。从 [`examples/README.md`](examples/README.md) 开始，获取完整的索引和注解的演练 — 包括两个 v3 分支模式（人口细分和 A/B 概念测试），您可以将其适应于自己的研究。
## LLM 提供商支持
althing 与任何 LLM 提供商合作。设置相应的环境变量：
| 提供商 | 环境变量 | 模型标志 |
|----------|---------------------|------------|
| Anthropic (Claude) | `ANTHROPIC_API_KEY` | `--model sonnet` |
| Google (Gemini) | `GOOGLE_API_KEY` 或 `GEMINI_API_KEY` | `--model gemini` |
| OpenAI | `OPENAI_API_KEY` | `--model gpt-4o` |
| OpenRouter | `OPENROUTER_API_KEY` | `--model openrouter/anthropic/claude-haiku-4-5` |
| xAI (Grok) | `XAI_API_KEY` | `--model grok` |
| 任何 OpenAI 兼容 | `OPENAI_API_KEY` + `OPENAI_BASE_URL` | `--model <model-id>` |
```bash
# 使用 Claude（默认）
althing panel run --personas p.yaml --instrument s.yaml
# 使用 GPT-4o
althing panel run --personas p.yaml --instrument s.yaml --model gpt-4o
# 通过 Ollama 使用本地模型
OPENAI_BASE_URL=http://localhost:11434/v1 \
althing panel run --personas p.yaml --instrument s.yaml --model llama3
```
> **大型面板和 OpenRouter 默认值（synthbench#261）：** 当省略 `--model` 时，默认值从存在哪个键中解析 — 对于 OpenRouter-only 环境，这是 `openrouter/auto`，其自动路由器可以选择慢速推理模型并使 20 人面板等待 15 分钟以上。因此，对于 **≥ 10 个角色** 且没有显式模型的运行，althing 会自动选择快速等效模型（`openrouter/anthropic/claude-haiku-4.5`）并打印一行注释。这在 CLI、SDK 和 MCP 接口上均适用。显式传递 `--model openrouter/auto`（或 `model="openrouter/auto"`）以选择返回自动路由器 — 将其视为“最高保真度，接受延迟”选项。少于 10 个角色的运行保持正常默认值。
### 模型别名
althing 带有简短的别名（`sonnet`、`opus`、`haiku`、`grok`、`gemini`、`gemini-pro`），映射到规范的模型标识符。您可以覆盖或扩展这些而不更改代码：
**解析顺序（优先级最高赢）：**
1. **`ALTHING_MODEL_ALIASES` 环境变量** — 别名→模型对的 JSON 字符串
2. **`~/.althing/aliases.yaml`** — YAML 文件
3. **硬编码默认值** — 内置于包中
```bash
# 通过环境变量覆盖（JSON）
export ALTHING_MODEL_ALIASES='{"sonnet": "claude-sonnet-4-6-20250414", "fast": "claude-haiku-4-5-20251001"}'
althing prompt "Hello" --model fast
```
```yaml
# ~/.althing/aliases.yaml
aliases:
fast: claude-haiku-4-5-20251001
smart: claude-opus-4-6
sonnet: claude-sonnet-4-6-20250414
```
环境变量条目覆盖文件条目，文件条目覆盖硬编码默认值。所有层的别名都被合并，因此您只需要指定要添加或更改的别名。
### SynthBench 驱动的模型选择器
`--best-model-for` 咨询 [SynthBench](https://synthbench.org) 排行榜，并使用给定主题或数据集的排名最高的模型：
```bash
althing panel run --personas p.yaml --instrument s.yaml \
--best-model-for "Economy & Work"
```
排行榜在 `~/.althing/synthbench-cache.json` 缓存 24 小时。有关完整规则、离线行为和使用案例 → 顶部模型表的详细信息，请参见 [docs/recommended-models.md](docs/recommended-models.md)。
如果排名最高的条目公开显示标签（例如 `Althing (Gemini Flash Lite)`），而不是可运行的提供商模型 ID 在其 `model` 字段中，`--best-model-for` 替换可运行的 `model_id`，排行榜发布它旁边，因此您获得一个真实的可运行模型，而不是拒绝。只有当无法解析可运行的 ID 时，它才会拒绝戳记 — 打印可操作的消息并回退到现有的 `--model`/默认值。将 `--dry-run` 与 `--best-model-for` 结合使用，以查看挑选的模型（和任何此类拒绝）在任何 LLM 调用之前。
### 模型包（代理指导）
`--best-model-for` 选择一个模型；**模型包** 选择一个*混合*模型，根据决策的风险程度进行校准 — 例如 `fast-cheap-preflight`（用于烟雾测试的单个廉价模型）与 `balanced-research-ensemble`（`haiku,sonnet,gemini-2.5-flash`用于“真实”决策）与 `high-stakes-validation`（具有 `--blend` 的 4 家模型集合）。这些文档化的预设编译为现有的 `--models` 标志 — 请参见 [docs/model-packs.md](docs/model-packs.md)，了解七种推荐的配置、SynthBench 发现的动机和模型集合，以及代理商在匹配包和声明强度时需要遵循的检查清单。
## 架构
althing 是一个研究工具，而不是 LLM 包装器。它协调研究工作流程：
```
personas.yaml ──┐
├──> 调度器 ──> 小组成员 1 ──> LLM ──> 响应
instrument.yaml ─┘ ├──> 小组成员 2 ──> LLM ──> 响应
└──> 小组成员 N ──> LLM ──> 响应
│
聚合报告 <──┘
```
### 组件
| 模块 | 目的 |
|--------|---------|
| `llm/` | 提供者无关的 LLM 客户端（Anthropic、Google、OpenAI、xAI） |
| `runtime.py` | 代理会话循环（回合、工具调用、压缩） |
| `orchestrator.py` | 并行小组成员执行与工作者状态跟踪 |
| `structured/` | 通过工具使用强制执行模式验证的响应 |
| `cost.py` | 令牌跟踪、模型特定定价、预算强制执行 |
| `persistence.py` | 会话保存/加载/分叉（JSON + JSONL） |
| `plugins/` | 基于清单的扩展系统，具有生命周期钩子 |
| `mcp/` | 用于代理本地调用的 MCP 服务器（stdio 传输） |
| `cli/` | 带有斜杠命令、输出格式化的 CLI 框架 |
### 设计原则
- **最小依赖** — Python 3.10+，使用 `httpx` 进行 HTTP 和 `pyyaml` 进行 YAML 解析。可选：`mcp` 用于 MCP 服务器
- **代理原生** — 从终端或 AI 代理的 MCP 工具调用中调用
- **提供者无关** — 更换 LLM，无需更改研究定义
- **成本透明** — 每个 API 调用都被跟踪和定价
- **可复制** — 相同的角色 + 相同的工具 = 可比较的输出
- **默认结构化** — 响应符合声明的模式
## 输出格式
```bash
# 人类可读（默认）
althing panel run --personas p.yaml --instrument s.yaml
# JSON（管道到 jq，存储在数据库中）
althing panel run --personas p.yaml --instrument s.yaml --output-format json
# NDJSON（流式处理，每行一个事件）
althing panel run --personas p.yaml --instrument s.yaml --output-format ndjson
```
## 预算控制
```bash
# 为面板设置美元预算
althing panel run --personas p.yaml --instrument s.yaml --config budget.yaml
```
成本跟踪器强制执行软预算限制 — 当前的小组成员将完成，但如果预算超额，则不会启动新的小组成员。
## 角色提示模板变体
`templates/` 目录包含四个用于基准测试的提示模板变体，测试角色提示构造如何影响响应质量：
| 模板 | 文件 | 字段 | 目的 |
|----------|------|--------|---------|
| **当前** | `templates/current.txt` | 名称、年龄、职业、背景、个性特征 | 控制 — 记录默认提示样式 |
| **演示** | `templates/demo.txt` | 名称、年龄、职业、教育水平、收入等级、城乡、政治倾向、背景 | 丰富的人口统计数据 — 添加 SubPOP/OpinionsQA 分层轴 |
| **价值观** | `templates/values.txt` | 名称、年龄、职业、背景、核心价值观、决策风格 | 丰富的价值观 — 添加信仰和决策背景 |
| **最小** | `templates/minimal.txt` | 名称、年龄、职业 | 消融控制 — 测试叙事的重要性 |
用法：
```bash
althing panel run --personas personas.yaml --instrument survey.yaml --prompt-template templates/demo.txt
```
模板使用 Python 格式字符串语法 (`{field_name}`)。缺少的角色字段将保持原样 `{field_name}` 在输出中。
## 可复制性 (`--seed`)
传递 `--seed N` 给 `panel run` 以实现提供者支持种子参数的重复采样（OpenAI、Gemini、xAI、OpenRouter）：
```bash
althing panel run --seed 42 --personas p.yaml --instrument s.yaml
```
althing **可以** 承诺：
- 将种子转发给支持它的提供商。
- 在运行的 `metadata.parameters.seed` 和检查点指纹中记录种子，以便不同的种子运行会大声失败，而不是静默混合样本。
althing **无法** 承诺：
- Anthropic 的 Messages API 没有 `seed` 参数。当在 Claude 模型上设置 `--seed` 时，althing 每提供商日志记录单个警告，并继续不确定性地运行。使用 `--temperature 0` 以接近确定性的 Claude 输出，但预期在模型版本之间存在差异。
- 即使在支持提供商的情况下，“种子”采样也是尽力而为：模型服务基础设施和无声服务器端更新仍可能在运行之间改变输出。
`--seed` 用于您希望可复制的**新**运行。要完全重放先前缓存的运行，请使用 `althing panel run --resume <run-id>` — 该路径直接提供缓存的响应，与 `--seed` 无关。有关完整的图片，请参见 [docs/reproducibility.md](docs/reproducibility.md)。
## 方法论说明
合成研究适用于探索、假设生成和快速迭代。 **不是** 取代与真实人类交谈。
已知局限性：
- 合成响应趋于聚集在均值周围
- 大型语言模型表现出唯唯诺诺（趋向于取悦）
- 文化和人口统计学代表性存在盲点
- 变量之间的高阶相关性复制较差
使用 althing 进行预筛选和迭代，然后用真实参与者验证。
## 多模型集成（0.7.0）
使用多个模型运行相同的面板，并混合他们的响应分布以获得更高保真度的结果。[SynthBench 实验](https://github.com/DataViking-Tech/synthbench/blob/main/FINDINGS.md) 显示 3 模型集成通过 +5-7 个点提高人机对比得分。
```bash
# 在此处输入您的代码
```
运行3个模型，权重相等，并混合分布
althing panel run \
--models haiku:0.gemini:0.33,gpt-4o-mini:0.34 \
--blend \
--personas personas.yaml \
--instrument survey.yaml
# 每个角色分别接受所有3个模型的采访。
# --blend 参数会平均跨模型的响应分布，
# 生成更具代表性的人工调查数据。
混合输出包括每个模型的分布和加权集成分布，
允许您检查各个模型的观点和共识视图。
## 大规模运行
对于500到10,000+名参与者的群体，althing可以通过Jensen-Shannon散度实时跟踪响应分布的收敛情况，
并可选地在每个有界问题（Likert / 是-否 / 单选 / 枚举）稳定后自动停止。
运行后的JSON文件新增了一个顶级的`convergence`部分，
显示每个敛所需的最小`n`值，
这样您可以自信地运行更小的样本规模。
```bash
althing panel run \
--personas large-panel --instrument pricing-discovery \
--var problem="choosing a project" \
--convergence-check-every 20 \
--auto-stop \
--output-format json > result.json
jq '.convergence.overall_converged_at, .convergence.auto_stopped' result.json
473
# true
```
参见 [docs/convergencedocs/convergence.md)方法论、调优的 `--convergence-baseline` 参数，
该参数将您的运行结果与 [SynthBench](https://github.comiking-Tech/synthbench) 的真实人类基准进行比较 `pip install 'althconvergence]'` 安装### 将校准到SynthBench
的面板运行（使用ibrate-against DATASET:QUESTION` 生成）
会生成针对已知人类分布的每个问题的分数，
这是 [SynthBench排行榜](https://synthbench.org) 跟踪分数。
添加 `--submitynthbench` 参数，
在运行完成后自动上传结果：
```bash
export SYNTHBENCH_API_KEY=sk_synthbench_... # 在synthbench.org/account上获取
althing panel run \
--personas examples/personas.yaml \
--instrument happiness-probe \
--calibrate-against gss:HAPPY \
--convergence-check-every 20 \
--submit-to-synthbench
```
首次使用时会显示一个屏幕上的隐私声明（记录在 `~/.althing/synthbench-consent.json` 中，
运行不会再次提示；
yes` 参数适用于CI环境时会发出警告但运行失败，
因此Syn的缓慢不会影响您的面板运行。
参见 [docs/synthbench-integration.md](docs/synthbench-integration.md) 了解完整的隐私模型、
上传和失败模式。
## 版本
| 版本 | 主要更新 |
|---------|-----------|
| 1.5.x *(当前)* | `althing mcp install --host auto` 一行命令注册主机；四个标准角色包；确定性的 `poll-summary` 合并；MCP自动10个角色的面板选择快速模型；`results list`/`results show` 用于保存的结果存储；`python -m althing` 别名；失败时大声报错的空附件和类型化的 `response_schema` 强制执行；合成路由跟随面板的提供者；PyPI受信任发布 + 自动标记版本漂移保护 |
| 1.4.0 | 在 `EnsembleResult`、`ModelRunResult` 和 `SynthesisResult` 上显式 `cost_estimated_usd` / `cost_actual_usd`（+ `per_model_breakdown`）— 估计值与账单对账，无需检查原始使用情况 |
| 1.3.0 | `trafilatura` 移动到 `[full]` 额外依赖，因此裸 `pip install althing` 在 pyodide/Cloudflare Python Workers 上有效（无需 `lxml` C 扩展） |
| 1.2.0 | Pyodide 安全 / 异步 DI 接口，用于 `althing.ensemble.synthesize_panel` — 通过您自己的异步 LLM 客户端驱动 judge 调用 |
| 1.1.0 | `althing.ensemble` 冻结为支持的公共 API，用于集成/商议核心 |
| 1.0.6 | 跨城狗粮摩擦扫描 v1.0.x 线；`panel_verdict` 在 MCP 成功路径上发出；发布狗粮协议编纂 |
| 1.0.0 | 冻结 MCP 合同（`schemas/v1.0.0.json`，`schema_version` 在每个响应和类型错误中回显）；多模态附件（图像，URL，PDF，内联 HTML）具有分层交付和 URL 获取安全边界 |
| 0.12.0 | `--best-model-for TOPIC[:DATASET]` SynthBench 驱动的模型选择器，`--submit-to-synthbench`，`althing pack calibrate`，六个捆绑包加深 5 → 15 个角色 |
| 0.11.0 | `sp-i2ub` 缩放编排史诗：面板级检查点与 `--resume <run-id>` 和 SIGINT/SIGTERM 自动检查点（每 K=25 个面板），`--max-cost <USD>` 运行中预计总成本门控，带有有效部分 JSON 的温和停止，和有效部分 JSON 纪律在每个中止路径（速率耗尽，SIGINT，成本门控，面板失败）带有 `run_invalid: true` + 特定 `abort_reason` 和退出代码 2；6 个 bug 大声噪音扫描，在别名解析，合成部分有效载荷，MCP `extend_panel`，条件评估器，编排器后续异常和 `test_aliases` 夹具上将无声失败转为大声报错；自动标记现在在未标记的发布 PR 上失败；`pip-audit` 忽略 pip 26.0.1 中的 CVE-2026-3219 |
| 0.10.0 | `althing report` 事后 Markdown 渲染器，用于保存的面板结果（在 `[report]` 额外依赖后面）；通过 `panel run --calibrate-against DATASET:QUESTION` 进行内联 SynthBench 校准，带有自动导出的 `pick_one` 模式和 `per_question[key].calibration` 子对象线格式；去中心化包注册表 — `pack import gh:<user>/<repo>` 带有 `--unverified`，`pack search`，`pack list --registry`，24 小时缓存 + 离线备用；带有选择性影子警告的角色包上的可选 `version:` 字段 |
| 0.9.9 | `--synthesis-strategy=auto` 现路由到上下文溢出时的映射减少，而不是硬故障；OpenRouter 别名解析收紧用于亚 1¢ 本地表健全性检查；`--personas-merge` 在捆绑包冲突时警告（或通过 `--personas-merge-on-collision` 错误）名称冲突；版本从 `src/althing/__version__.py` 单一来源，并带有模板站点渲染 |
| 0.9.8 | 失败合成（上下文溢出飞行前检查 + 结构化 `synthesis_error`），每个问题的映射减少合成（`--synthesis-strategy=single\|map-reduce\|auto`），带有确定性分布的响应模式验证，用于有界问题类型，速率限制感知客户端（`--max-concurrent`，`--rate-limit-rps`），实时收敛遥测 + `--auto-stop`，4 个新的捆绑角色包（`job-seekers`，`recruiters-talent`，`product-research`，`ai-eval-buyers`）将已发货角色从 24 提升到 84 个，`/althing-poll` 斜杠命令 |
| 0.9.7 | 提供者报告的成本是权威的 — 当提供者返回 `usage.cost`（例如 OpenRouter）时，该值会被逐字记录，而不是从本地定价表中重新计算；当模型降级到 `DEFAULT_PRICING` 时，会显示 `pricing_fallback` 警告；集成舍入不再无声丢弃低权重模型 |
| 0.9.5 | 在仪器/角色中未替换的 `{placeholder}` 变量上失败快速；`--personas-merge PATH` 用于分层角色包；`--dry-run` 预运行预览；具有退化运行的 `run_invalid` 标志；MCP BYOK 检测通过凭证存储路由 |
| 0.9.4 | `althing login` / `logout` / `whoami` 凭证存储 CLI；MCP 识别 `OPENROUTER_API_KEY` 为 BYOK 并选择一个合理的默认值；GHCR + Docker Hub 多架构的 Docker 镜像；`run_prompt` 和 `run_quick_poll` 的 MCP 采样备用 |
| 0.9.0 | 公共翻转后首次发布。存储库重命名为 `Althing`（PyPI 名称 `althing` 不变） |
| 0.8.0 | 用于合成格式提供者字符串的 `lookup_pricing_by_provider` 公共帮助程序；多问题 CLI 成本形状对称性（`total_cost` / `panelist_cost` / `total_usage` / `panelist_usage`）|
| 0.7.0 | 多模型集成混合（`--blend`），OpenRouter 提供者支持，温度/ `top_p` 控制，提示模板自定义 |
| 0.6.0 | `--models` 加权模型规范，`--temperature` / `--top_p` 标志，角色提示模板，包生成，域模板，MCP 改进 |
| 0.5.0 | v3 分支仪器，路由器谓词，5 个捆绑仪器包，`instruments` 子命令（列表/显示/安装/图），MCP `*_instrument_pack` 工具，圆形面板输出，`extend_panel` 即席圆形工具 |
| 0.4.0 | `--var KEY=VALUE` 和 `--vars-file` 用于仪器模板，对所有提供者错误大声报错，默认 `--model` 尊重可用凭证，`pack show <id>` 别名，发布工作流程修复 |
| 0.3.0 | 通过工具使用强制执行结构化输出，成本跟踪，MCP 服务器（stdio），角色包持久性 |
参见 [CHANGELOG.md](CHANGELOG.md) 了解详细的发行说明。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置、测试以及如何提交更改。
## 在SynthBench上评测
althing 生成代表性合成受访者的能力通过 [SynthBench](https://synthbench.org) 测量，
这是一个用于合成调查质量的开放基准测试（一个由 Althing 维护者运营的 DataViking 子项目）。
- **想要证明它有效？** 浏览 [排行榜](https://synthbench.org) — 3 模型集成混合评分 SPS 在 opinionsqa 上为 0.877，在 subpop 上为 0.858，在 globalopinionqa 上为 0.813（排行榜于 2026-07-17 生成；数字会随着排行榜重新计算而变化）。
- **有优秀的配置？** [提交您的分数](https://synthbench.org) 并与基准比较。
- **贡献适配器？** 大型 PR 具有实质性行为变化，从 SynthBench 结果中受益 — 审查者经验质量，而不仅仅。参见 [docs/adapter-guide.md](docs/.md) 了解器工作流程。
## 许可证
MIT
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器