decision-arena · 多 Agent 办公决策系统

把一个开放议题交给一组角色（倡导者、反对者、各专业顾问、决策者），经过「倡导 → 质询 → 多轮论证 → 裁定」的多轮碰撞，收敛出可落地的决策结论，并产出带审计留痕的 Markdown 决策报告。

适用于技术选型、采购评审、招聘评估、风险审批等各类办公决策场景；也可基于用户提供的文档/材料（合同、方案、简历、报告、需求文档等）先解析内容，再进行分析决策。

核心特性

• 多角色辩论机制：按议题类型自动组队，倡导者提方案、反对者逐条质询、各专业顾问补充论据、决策者最终拍板。
• 防回声：内置基于字符 3-gram 的 Dice 相似度检测，重复观点会被识别并记入警告，避免讨论空转。
• 收敛判定：连续 N 轮讨论无新观点即提前收尾，节省时间与 token。
• 离线可演示：内置离线 Mock 模式，零依赖、无需网络与 API Key 即可体验完整流程。
• 可审计留痕：决策报告、完整转写过程记录、JSON 决议留痕三类产出物独立归档。

工作机制（六环节）

① 议题陈述   决策秘书立项（背景 / 目标 / 约束）
② 方案倡导   倡导者提出方案（可含备选 A/B）
③ 风险质询   反对者逐条质疑
④ 多轮论证   各顾问轮流补充，防回声 + 收敛判定（连续 N 轮无新观点则提前终止）
⑤ 决策书草拟 决策秘书汇总论证拟写决策书
⑥ 决策者裁定 决策者拍板：采纳 / 待议 / 否决 + 行动方案

前置条件

依赖的底层模块

系统复用 debate-arena（同一开发环境中的相邻项目）的 src 下三个底层能力模块，运行时会自动加载：

• llm.py：OpenAI 兼容的真实 LLM 客户端与离线 Mock 两套实现。
• memory.py：共享记忆（发言转写 / 观点清单 / 回声警告 / 上下文条数限制）。
• anti_echo.py：基于字符 3-gram Dice 相似度的防回声检测。

scripts/_bootstrap.py 会按以下顺序定位 debate-arena 的 src 目录（scripts/ 下的 agents.py、orchestrator.py 不会被遮蔽，仅复用其独有模块）：

1. 环境变量 DEBATE_ARENA_SRC（显式指定）；
2. 与 decision-arena 平级的默认位置（即两者位于同一父目录下）；
3. 常见绝对路径兜底。

若均未命中会抛出异常，请设置 DEBATE_ARENA_SRC 指向 debate-arena 的 src 目录。

依赖库

模式	依赖
离线 Mock 模式	无（零依赖）
真实 LLM 调用	requests>=2.28（见 requirements.txt，可直接复用 debate-arena 的虚拟环境）

快速开始

# 1) 查看可用议题类型与角色组合
python scripts/decision.py --list-types

# 2) 离线演示（无需 API Key）
python scripts/decision.py --type 技术选型 \
    --topic "是否引入 PostgreSQL 作为核心数据库？" --mock

未设置 LLM_API_KEY / LLM_BASE_URL 时程序会自动进入离线 Mock 模式；可用 --mock 显式指定。

使用方法

真实调用 + 导出决策报告

export LLM_BASE_URL=https://api.deepseek.com/v1
export LLM_API_KEY=sk-xxx
export LLM_MODEL=deepseek-chat

python scripts/decision.py --type 采购决策 \
    --topic "是否采购 X 云服务？" \
    --background "存量系统即将到期" \
    -c "预算上限 100 万" -c "年内必须上线" \
    --output ./output/采购决策报告

基于文档分析决策

用户可提供待决策的文档/材料（如 PDF、Word、Excel、Markdown、图片等），也可只口头描述议题：

• 提供了文档：先调用与文档类型对应的解析 Skill（pdf / docx / xlsx 等）提取文本，再提炼「议题 / 背景 / 约束」注入决策流程。建议采用提炼式注入：关键信息进 --background、要点逐条进 -c，避免全文直灌带来的 token 与转义问题；文档极长时可仅将摘要进 --background，全文留作参考。
• 未提供文档：跳过解析，直接按上文正常执行。

python scripts/decision.py --type 采购决策 \
    --topic "是否采购 X 云服务？" \
    --background "已从合同文档解析出背景：存量系统即将到期、供应商资质齐全" \
    -c "预算上限 100 万" -c "年内必须上线" \
    --output ./output/采购决策报告

CLI 参数

参数	别名	说明
--type	-y	议题类型，默认 通用决策（--list-types 查看可用类型）
--topic	-t	决策议题，如「是否引入 PostgreSQL？」
--background	-b	议题背景说明（可选）
--constraint	-c	约束条件，可多次传入，如 -c "预算 100 万"
--rounds	-r	多轮论证轮数上限，覆盖 settings.json 的 debate_rounds
--mock	-	强制使用离线 Mock 模式（无需 API Key）
--output	-o	导出路径，自动生成 .md 与 .json 文件
--list-types	-	列出可用议题类型后退出

产出物

• Markdown 决策报告：议题背景 → 论证过程 → 决策结论 → 采纳/驳回论点 → 遗留风险 → 行动方案（责任人/截止时间/优先级）→ 可审计转写记录。
• Markdown 决策过程记录（*.process.md）：完整收录每个环节、每位角色（含议题陈述、决策者裁定）的发言原文，与决策报告分开独立留档。
• JSON 决议留痕：完整转写 + 决议结论，供归档与审计。

目录结构

decision-arena/
├── README.md                  # 本说明
├── SKILL.md                   # Skill 说明（角色与工作机制细节）
├── requirements.txt           # 真实调用依赖
├── config/
│   ├── roles.json             # 议题类型 → 角色团队（动态组队）
│   └── settings.json          # 温度/轮数/防回声阈值等参数
├── scripts/
│   ├── decision.py            # CLI 入口（单人单机使用）
│   ├── orchestrator.py        # 决策流程编排 + 报告渲染导出
│   ├── agents.py              # 决策角色 Agent + 离线 Mock
│   └── _bootstrap.py          # 底层模块路径引导（自动加载 debate-arena/src）
└── references/
    └── decision-flow.md       # 决策流程与角色分工说明

预置议题类型

议题类型	角色组合
技术选型	决策秘书、倡导者、反对者、架构师、研发负责人、运维负责人、决策者
采购决策	决策秘书、倡导者、反对者、采购专员、财务、法务、决策者
招聘决策	决策秘书、倡导者、反对者、HR、用人部门、薪酬顾问、决策者
风险审批	决策秘书、倡导者、反对者、风险官、财务、合规、决策者
通用决策	决策秘书、倡导者、反对者、资深顾问、财务、运营、决策者

配置说明

config/roles.json —— 角色与议题类型

按议题类型定义角色团队。角色字段：

字段	说明
name	角色唯一标识
display	显示名
kind	角色职责：secretary（秘书）/ advocate（倡导者）/ opponent（反对者）/ advisor（专业顾问）/ decision_maker（决策者）
system_prompt	角色人设与行为约束

config/settings.json —— 运行参数

参数	默认值	说明
temperature	0.7	LLM 采样温度
max_tokens	900	单次生成最大 token 数
max_continue_retries	5	生成截断时的续写重试次数
echo_threshold	0.72	防回声相似度阈值（≥ 判定为重复观点）
convergence_stall_rounds	2	连续 N 轮无新观点即收敛
debate_rounds	2	多轮论证轮数上限
history_limit	40	注入上下文的历史消息条数上限
timeout	180	LLM 请求超时（秒）

自定义扩展

• 改角色 / 新增议题类型：编辑 config/roles.json，新增 teams 下的一组成员即可。
• 调参数：编辑 config/settings.json，如调整 debate_rounds、convergence_stall_rounds、echo_threshold。
• 换底层模型：通过环境变量 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL 接入任意 OpenAI 兼容接口。