BriefLoop 0.20.1

面向行业研究、战略与 IR 使用者的本地报告工作台：把分散材料整理成可编辑简报，逐项查看重要结论的依据、处理审阅问题，并保留原稿与修订版本。适合需要定期写报告、核数字和核口径的单人工作。

界面与文档为中文，报告正文可选中文或英文。研究深度取决于所选宿主自身的能力和本次报告的共享预算，本版不提供托管式 Deep Research 服务。

新建报告可选择通用报告，或商业报告下的行业周报／月报、工作进展周报与决策分析。内容方法贯穿规划、写作、修订与评价，并随报告保存实际版本；Word 模板单独控制版式。八类内置版式可继续使用，其余文档类型的专门内容流程将分批接入。

桌面 App

桌面安装包以发行页实际提供的版本为准；本次先发布 Python/CLI/Web 0.20.1，既有桌面包仍为 0.20.0。

从 GitHub Releases 选择与系统匹配的安装包。macOS Apple Silicon 使用 DMG；Windows x64 使用 EXE。桌面版与 WebUI 共用报告、材料和设置。

首次启动检测本机 Python 3.11+；已有兼容版本即可准备 App 专属依赖环境，缺少时页面提供安装入口。桌面版复用 Electron 内置 Node，无需为 BriefLoop 桥接单独安装 Node。模型 CLI 与账号仍由你选择并配置。

桌面版提供原生工作区选择、Word 另存、保存后退出，以及“设置 → 版本更新”。依赖准备需要网络；更新由用户发起，保存与任务停止完成后才开始安装。安装与更新步骤见 桌面使用指南。

WebUI 快速开始（Python 3.11+）

git clone https://github.com/Stahl-G/briefloop.git
cd briefloop
./start.sh

只需这一个仓库。首次启动自动创建 .venv、安装 Python 依赖（WikiSkill 已内联）、启动本地服务并打开网页；无需第二次 clone，也无需手动构建前端。

也可从 PyPI 安装已发布版本（分发名 briefloop，WikiSkill 已内联）。PyPI 版本可能晚于当前源码；先用 briefloop --version 核对，需要本次源码功能时使用上面的安装路径：

pip install briefloop
briefloop start --workspace /path/to/workspace

首次打开可点击 “先看合成示例（无需模型）”：在空工作区中保存示例来源和稿件，体验查看、修改、Word 导出。示例未评分、未独立审阅，自动学习关闭；导入与导出不调用模型。下一步实际生成需要自己选择并认证宿主与模型。

实际生成前需要：

• macOS 或 Windows，以及 Python 3.11 或更新版本。
• 至少一个已安装并完成认证的执行宿主：Codex CLI、Opencode CLI、Claude Code、Kimi、Hermes、DeepSeek Reasonix、MiMo Code 或 CodeBuddy Code。Codex 与 Opencode 走原生通道，其余 CLI 通过本地 bridge 接入；WebUI 安装需要 Node.js 20+，桌面 App 使用 Electron 内置 Node。
• 首次安装依赖需要网络。使用 Tavily 时另行配置自己的 Tavily Key。

也可指定目录、端口和后端：

./start.sh --workspace /path/to/workspace --port 8765 --no-open --backend opencode

Windows WebUI

Windows 也可不安装桌面 App，直接启动同一套 Python 服务与网页。支持中文工作区、编辑保存、Word 导出、互斥锁和退出重开。各宿主的实际验证范围见 Windows 说明。

安装 Python 3.11+ 后，在 PowerShell 中运行：

.\start.ps1 -Python 'C:\path\to\python.exe' --no-open

也可直接运行 python -X utf8 bootstrap.py --no-open。启动器打印本机网页地址；模型认证仍由所选宿主提供。详情见 Windows 验证边界。

数据会去哪里

BriefLoop 在本机运行，但它不是离线工具。开始用之前请先分清三件事：

• 会离开本机：你上传的材料，以及生成的稿件与图片，会发送给你所选宿主所连接的模型提供方，用于生成、评价与修订。开启联网检索时，请求会发送给所选搜索服务；使用 Tavily 时由 Tavily 处理，也可能使用宿主自带的搜索工具。
• 留在本机：工作区目录、数据库、来源原件、稿件版本、评分与审计包。模型与搜索凭据保存在本机相应配置中。日志和模型生成内容可能带有敏感信息，分享前仍需检查。
• 不对外提供访问：本地服务只监听本机地址，不向局域网或互联网暴露。

所以，请按材料本身的敏感程度选择宿主与模型，并遵守你所在机构关于材料外发的规定。把内部材料交给本地工具，和把内部材料交给某家模型厂商，是两件事。

模型的可用性和计费由所选宿主及提供方决定；BriefLoop 的本地服务不提供模型额度。

执行后端与模型

工作区默认使用 Codex（Responses 通道）。执行宿主可在启动时用 --backend 指定，或在网页设置页切换；已排队/已开始的任务冻结原后端，不跟随切换。设置页会检测本机已安装的 CLI，并读取各自的模型目录。

模型下拉只提供建议，任何宿主都接受手填模型 ID。默认 表示"用宿主自己配置的模型"：能读到宿主配置时（例如 Claude Code 的 ~/.claude/settings.json）会显示解析出的真实模型名，读不到时保持通用标签。角色模型（Evaluator、Wiki Maintainer、Skill Proposer）可以分别指定，留空继承主链。

输入区的控件跟随当前宿主的能力，而不是固定的 Codex 选项：权限档位来自 runtime 声明的 permission_modes（只有一种时不显示这个下拉）；立即补充 只在支持运行中追加的宿主出现；不支持读图的宿主在附图时直接提示。联网开关会向宿主放行它自己的联网工具（例如 Claude Code 的 WebSearch / WebFetch），放行后能否联网仍由宿主账号与权限决定。

• Opencode 模型填完整 provider/model（如 opencode-go/gpt-5.6-luna），以本机 opencode 已登录的可选模型为准；BriefLoop 不枚举、不限制 provider。
• 推理档位在 Opencode 下叫 variant（如 high / max），留空为默认；聊天沿用工作区主模型的 variant。
• 限制（以诚实为准）：Codex 之外的宿主没有每轮网络硬开关，关闭联网时靠指令与权限执行，宿主自带的 shell 仍可能联网；只有 Codex 支持运行中追加（Opencode 与 bridge CLI 会明确拒绝）；图片附件只在宿主支持读图时可用。
• 排查：任务失败先看任务日志；"模型 ID"类错误检查 provider/model 拼写与宿主登录状态；bridge 相关报错先确认 Node.js 20+ 与本机 CLI 已认证。可通过 BRIEFLOOP_NODE=/absolute/path/to/node 指定 Node；缺少 Node 不阻断 Codex / Opencode 的原生发现。

设置中的执行时限可选“不限时”（0 分钟），仍可手动停止。提供商返回的 429、503、额度不足等错误，以及宿主实际重试状态，会显示在对话中；不会用空白回复替代失败。报告等待权限时可直接打开绑定的任务对话处理。

Codex 使用官方 OpenAI provider 且配置支持时，输入区与角色配置显示 Fast 选项。Fast 是发送给宿主的服务档位请求，可用性与费用由宿主决定；它不是所有 CLI 共用的加速开关。

服务只监听本机。WebUI 关闭网页后任务继续；桌面 App 退出前先保存，有运行任务时提供继续工作或停止退出的选择。

当前同一对话仍固定执行宿主；切换宿主请新建对话。已排队报告继续使用冻结配置。

现在可以做什么

• 对话工作台：发消息、上传材料、选择模型、排队或中途补充要求，查看公开工具和子 Agent 活动。
• 工作区管理：打开已有目录或新建空工作区，各自保存对话、来源、稿件、评分与 Wiki。
• 对话整理：归档、移到回收站、恢复，或批量归档已结束对话；报告、来源与 Wiki 不跟随对话清理删除。
• 从公开资料写简报：不强制上传。开启联网后，由 Scout 查找并筛选资料；Analyst 写稿，Evaluator 独立评分。
• 从 MCP 取得报告材料：在设置中连接 HTTP 或本机 stdio 服务，再在新报告中明确选择资源、工具和预算。实际读取结果保存为来源与回执，供正文引用和离线核查。
• 直接改稿与学习：编辑正文或留下反馈；Wiki Maintainer 整理经验，Skill Proposer 提出技能，Evaluator 比较实际产物后决定是否采用。
• 明确的预算与篇幅：整次报告共享检索额度；正文目标字数和上限可直接修改。

第一次使用

1. 在“材料与需求”填写目的、读者、时间范围和字数要求。可上传材料、开启联网，或在“本轮连接器材料”中明确选择 MCP 材料。
2. 选择搜索工具。Tavily 的输入口就在联网开关下；保存 Key 不会自动验证或发起收费搜索。
3. 在“设置”确认执行宿主、主模型及角色模型。模型 ID 可自行填写；Codex 的 provider 填本机已配置的 Responses provider 名称，其它宿主用它自己的配置；需要接第三方 API 时在“API 提供商”里登记协议、Base URL、Key 和模型。
4. 点击生成。草稿保存后即可查看，评分独立完成；低分或评分失败不会隐藏原稿。
5. 按需修改正文、保存反馈或明确启动学习。注意自动学习开关：启用后，编辑静默约 30 秒会合并反馈并启动模型任务。

MCP 连接器材料

在“设置 → 数据连接器”保存连接配置，测试目录并启用；保存配置本身不会连接 HTTP 或启动本机程序。HTTP 可选择 Bearer 令牌或服务要求的原样 Authorization 值；stdio 使用已安装程序的绝对路径和逐项参数。凭据保存在工作区的独立受保护文件中，页面只显示是否已保存及认证类型。

在新报告的“本轮连接器材料”勾选具体资源或工具，并确认调用次数、材料总量上限。启用连接器不会自动授权每份报告，公开搜索的联网开关与此选择分开。任务启动前冻结选择与预算；未选资源和工具不能通过该任务的材料接口读取。工具声明“只读”不代表已经验证无副作用，请按其实际用途选择。

已选择、已接纳为来源、已被正文引用是三个不同结果。接纳会保存读取回执、原件哈希和来源 ID，材料仍须核查；Reviewer 使用已保存的核查包，不携实时连接器访问凭据。MCP 请求参数会发送给所选服务，取得的材料也可能进入所选模型的上下文。停止任务会撤销实时访问，保留已经保存的来源；未知结果不会自动重发，已撤销的任务需重新明确选择材料。

HTTP/stdio 的应用接口与生命周期说明见 连接器说明 和 材料授权与回执。Windows 已有原生协议及所属进程清理验证，具体边界见 Windows 验证记录；连接成功不代表任意企业服务、模型宿主或报告流程均已验收。

BriefLoop 与三个学习、评价角色

BriefLoop 用主链模型，另外三个角色可以在设置里分别指定、留空即继承主链；每次评价使用独立模型会话。候选技能已生成但验证未完成时，也能在 Wiki 页面查看；不会因为产生了文件就直接启用。

报告页的「已保存版本检查」分别展示断链引用、数值绑定、版式与导出提示；版式检查覆盖标题层级中断、空标题与缺表头表格，只报告不阻断。数值绑定需要原文摘录、明确来源位置（如 line 1、page 1 或证据定位 JSON）、正文唯一片段及其中的完整数值；程序按币种、单位和正负号核对，只对成功定位的项目计数。无绑定、单位不支持或改稿使定位失效时显示未检查。主体、期间、财务指标与政策条件由 Evaluator 对照原文评价。草稿可保存、修改和下载；含图表的独立交付请使用 Word 或包含图片的 Markdown 包。

研究预算

预算由整次报告中的 Scout 共享，不是每个 Scout 各拿一份，也不要求花完。失败的 Tavily Search 调用仍计次；同一 URL 的直接获取、Extract 回退及重试不重复扣全文 URL。达到额度后保留材料、说明缺口，不自动加额。

搜索请求和候选额度适用于受控 Tavily 工具；宿主自带的搜索（Codex、Opencode、各 CLI 的联网工具）无法在此精确计量，页面会明确区分。全文额度统计受控工具处理的不同 URL，不是 PDF 页数、阅读完成数量或所有 HTTP 请求次数。

正文篇幅

数字可直接修改。中文汉字每字计 1，连续英文或数字串计 1；格式、URL 和来源引用标记不计。原文摘录与定位放在来源记录中。页面显示保存后的实际计数，旧稿没有设置过数字要求时如实显示“未设置”。

正文图表与 Excel 复用

BriefLoop 按报告目的和历史参考决定哪里用图、哪里用表。可直接提取 XLSX 内嵌图片，并列出原生图表；原生图表需要可用渲染工具或同版本工作簿的已验证渲染，不能把重绘称作原图。新图可由 Agent 用实际数据生成，登记图像、来源、数据和脚本后，按指定位置进入网页、Word 和图文 ZIP。程序不再为新报告强制追加一张固定预测图。详见 图表与Excel。

图片与 PDF 页面

支持图片原件保存、预览，以及按宿主能力发送原生图片输入（Codex 用 localImage，bridge CLI 用归一化后的 PNG 附件，不支持读图的宿主会在附图时直接提示）；PDF 可按需渲染指定页，由研究或评价 Agent 查看图表。图片无需先转成 OCR 文本，读取失败会如实显示，不自动更换模型。只查看来源或本地渲染 PDF 不调用模型，发送给视觉模型则使用所选账户额度。详见 多模态来源。

行业定期报告

“材料与需求”可选择“行业定期报告”，填写行业、目标组织、报告日期和覆盖期间。默认目标 5,000、上限 5,500，可自由修改；六类章节依据行业和任务裁剪。公司、行业和历史稿保存在用户工作区，公共代码不包含特定客户数据。

• 已上传历史报告可以单独指定为结构与风格参考，不作为本期事实来源；不上传也能在开启联网后开始研究。
• 研究角色整理本期指标、前值、日期、单位和来源，调用确定计算工具；关键缺口可在剩余共享预算内定向补查，拿不到的数据列出缺口和影响。
• “数据与缺口”按钮可查看保存的原始值、变化和来源，不调用模型。
• Word 由“生成 Word”按钮触发，按固定报告版本制作并显示进度。保留通用模板，也支持上传单节 DOCX 准备工作区用户模板；完成后下载到 Word/WPS 查看；内置 36 套版式（7 类文体各 5 套主题，加 1 套固定公文版式），模板页点颜色即选，开箱可用。
• 网页以富文档保存内容、颜色、简单表格、图片和引用；Markdown 为兼容及导入/导出格式。用户改数后保留原始数据供核对，不把旧数据的核查状态套给新稿。

详细使用与数据接口见 行业报告。本次验证采用合成资料，未据此宣称真实行业覆盖率、事实正确率或成本改善。

富文档、用户模板与企业背景

网页可直接编辑富文档，保存后格式和内容一起形成版本。企业内部报告将正文与核查记录分开；可在独立评价后自动修订一次并复核，保留原稿。

“材料与需求”可选择通用/我的模板、设置人工填写小节，并选择是否维护企业背景知识库。公开披露更新保留来源与日期，用户资料冲突可在面板处理。图表由 BriefLoop 按要求修改，网页保留简单表格与图像操作。

Word 按按钮制作，完成后下载；不实时更新 Word，不提供网页分页预览或复杂电子表格。支持将外部 Word 修订导入到选定的基础版本，无法对齐时保留原件。详见 报告编辑与模板。

升级、边界与文档

0.20.1 新增本地外部任务入口：WorkBuddy 等可执行本机命令的 Agent 可连接已有工作区，提交报告、查询进度、保存指定版本的修订和下载 Word。使用说明见 WorkBuddy 外部入口；可使用 pip install --upgrade briefloop==0.20.1 安装；既有 0.20.0 桌面安装包不包含此入口。

会议纪要内容方法也在后续源码中接入：选择内置纪要模板即可建议相应用途，输入本次会议转写或笔记，整理决议、待办和未定事项。见 会议纪要说明与合成材料。

证券研究方法提供事件点评、公司研究和行业跟踪，按来源区分实际、预测与估值假设，使用有依据的数据生成图表。见 证券研究说明与合成材料。

0.17.0 是架构升级。旧提交和发布标签保留；旧版工作区不自动迁移。请保留旧目录，在新工作区按需要导入原始材料。升级说明

检索预算用于控制成本：达到额度后使用已有证据并列出重要缺口，不自动加额。评分与事实核验是两条独立的检查，页面分别显示各自结果。

• 产品定位与验证边界
• 合成周报示例
• 已知边界与问题反馈
• 贡献指南 · 安全问题
• 使用指南
• 多 Runtime 与模型设置
• 变更记录
• 来源与许可

开发

npm ci
npm run build
npm test
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python -m pytest -q

前端资源随包分发。服务启动时同时加载对应的前端和后端，构建或升级后需在任务结束后重启服务。开发测试不调用真实模型或 Tavily。

通用 Word 模板使用 Arial 排列西文和数字，中文交由阅读器选择本机字体，避免硬编码微软雅黑、宋体或 Office 主题字体。简体中文保留 zh-CN 语言提示。此策略不需要安装或嵌入字体，但不同系统、Word 与 WPS 的中文字形和分页可能略有差异；用户定制模板仍保留原字体，不会被自动替换。

企业报告与可追溯交付

新路径将重要主张绑定到具体原文行、PDF页、Excel单元格、图像和推断前提；网页可查看依据，正文修改后相应绑定需要复核。原始要求、研究方法、正文内容和写作偏好分别解释，企业报告正文不自动附内部检查清单。

Reviewer 使用本任务固定核查包，返回结构化发现及处理说明的复核结果。当前已实测的受限路径为 Opencode 原生只读文件工具：只开放包内明确文件，拒绝包外读取、shell和写入；如果宿主拒绝权限规则就失败，不降级。Codex同等限制仍需完成能力验证，不能将普通文件只读描述为全面受限审阅。

工作稿Word下载保持可用。“正式交付”另行检查当前版本的独立审阅、重要主张及必答内容、核心未核验、重大未决发现和冲突；高分不能抵消阻断项。审计包单独导出，逐来源选择原件、摘录或仅定位，缺省仅定位；离线校验为结构与一致性检查，不是事实真伪自动证明。旧正式件保留，更正或后续更新另建版本。

存在受限来源时，无法逐来源归属的审阅、回应、历史与内部研究自由文本会明确省略；包中保留身份、状态、定位和获准的证据片段。正式报告本身仍随包提供。旧版受限包需重新导出以应用完整权限投影，旧版全原件包继续支持下载和离线校验。

python -m briefloop.audit_bundle /absolute/path/report-audit.zip

来源复查在本轮联网选择和预算内实际重取，保留旧新快照、时间注释及影响范围；日期更新不自动意味着新版胜出。已确认修订接入既有WikiSkill，不另造学习循环。自定义Opencode模型可显式登记图片输入能力，未知模型不默认支持。

此前 Opencode 路径完成过真实网页的生成、审阅、一次修订、来源更正影响、Word 与审计包导出及学习闭环检查，并核对过 WPS 显示；这不等于每个后续版本和所有宿主均已完成真实模型闭环。每份报告仍按自身来源和独立审阅决定交付资格；一次修订后的未解决问题保留给用户处理，不因流程完成或模型返回成功而放行。

工作区动态

侧栏“动态”汇总报告任务开始、完成和失败，以及用户模板、Wiki 内容和可用版本更新；“我的报告”、模板、Wiki 与设置旁显示未读红点。可打开对应内容或选择“全部标为已读”，已读状态保存在当前工作区，刷新后保持。重复检查同一版本不会反复提醒，不弹出系统通知。

版本发布前后可运行 跨平台版本核对，比较实际 CLI、Mac App、Windows 程序和 PyPI；未提供的平台记录为未核验。

查看版本与更新

设置中的“版本与更新”读取当前后端的实际版本、构建标识和安装来源。桌面 App 与它管理的 CLI 共用环境，通过 App 更新；浏览器也可以检查 PyPI 的后端稳定版本，按页面提供的 pip、pipx 或 uv 命令更新后重启服务。开发源码单独标明，版本号相同不代表与发行包代码相同。

briefloop version 输出相同的版本信息；briefloop version --check 只检查 PyPI，不安装、不重启。Electron 壳仍通过桌面更新；不要对 App 管理的环境另外执行 pip 升级。