Metadata-Version: 2.4
Name: briefloop
Version: 0.22.3
Summary: Local multi-runtime agent workbench for sourced briefings, independent review and skill learning
Author: Stahl-G
License-Expression: MIT
Project-URL: Homepage, https://briefloop.ai
Project-URL: Repository, https://github.com/Stahl-G/briefloop
Project-URL: Changelog, https://github.com/Stahl-G/briefloop/blob/main/CHANGELOG.md
Keywords: agent,research,reporting,provenance,traceability,briefing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: Chinese (Simplified)
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: tzdata>=2025.2
Requires-Dist: mcp==2.2.0
Requires-Dist: pydantic<3,>=2
Requires-Dist: markdown-it-py<5,>=3
Requires-Dist: python-docx>=1
Requires-Dist: pypdf>=5
Requires-Dist: Pillow>=11
Requires-Dist: pypdfium2<6,>=4
Requires-Dist: openpyxl<4,>=3.1
Provides-Extra: docx
Requires-Dist: python-docx>=1; extra == "docx"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# BriefLoop

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

界面与文档为中文，报告正文可选中文或英文。研究在所选本机宿主中执行，使用本次报告的共享预算。提供快速、标准和深度研究档位，以及生成后的可选独立事实核查；安装版可用功能以实际发行版本为准。见 [深度研究与事实核查](docs/深度研究与事实核查.md)。

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

运行时设置显示本地图标、简介、实际版本与模型信息；未安装工具按卡片浏览。首页仅保留宿主选择器，更新失败会区分检查、下载和安装阶段。见 [运行时选择与检测](docs/运行时选择与检测.md)。

## 0.22：多渠道研究与可见进度

新工作区默认优先 Tavily，同时允许宿主自带搜索补查；可主动启用博查、智谱搜索或 DuckDuckGo，按跨市场覆盖或具体缺口补查。受控渠道共用本轮预算，搜索失败、实际发现渠道与原文分别保留。Tavily 需要 API Key，额度以服务账号为准；宿主自带搜索取决于实际工具与权限。

报告开始前可预览系统日期、时间范围和时区；任务开始后冻结。我的报告显示研究、已保存材料、审阅与修订的实际进展，原稿生成后即可查看。见 [使用指南](docs/使用指南.md)。

## 桌面 App

桌面安装包以发行页实际提供的版本为准；App、CLI 与 PyPI 使用同一产品版本和冻结后端 wheel，各渠道是否发布以版本核验结果为准。

从 [GitHub Releases](https://github.com/Stahl-G/briefloop/releases) 选择与系统匹配的安装包。macOS Apple Silicon 使用 DMG；Windows x64 使用 EXE。桌面版与 WebUI 共用报告、材料和设置。

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

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

## WebUI 快速开始（Python 3.11+）

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

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

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

```sh
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、博查或智谱搜索时，另行配置对应服务的 Key。

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

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

## Windows WebUI

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

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

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

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

## 隐私提示：文件和内容会去哪里

**BriefLoop 将工作区保存在本机；使用云端模型处理材料时，相关内容会经所选宿主发送到其配置的服务。关闭“联网检索”并不等于停止向模型发送内容。**

| 你执行的操作 | 文件或内容的去向 |
|---|---|
| 上传、解析和查看文件 | 文件先保存到本机工作区，内置解析在本机执行。仅上传或本地预览不会自动把整份文件发送给模型。 |
| 对话、研究、写稿、审阅、修订或学习 | 任务要求、对话，以及 Agent 读取的材料内容、图片、稿件、反馈等，会进入相应模型的上下文。具体可能是摘录、全文或图片，取决于实际读取和附件方式。主链、Evaluator、Wiki Maintainer、Skill Proposer 可分别使用不同提供方。 |
| 搜索和读取网页 | 搜索词发送给本轮允许且实际调用的搜索服务（Tavily、博查、智谱搜索、DuckDuckGo 或宿主自带工具），网页请求发送到目标网站；使用 Tavily 提取时，目标 URL 也会发送给 Tavily。Agent 生成的搜索词可能包含任务中的公司名称、主题或其他信息。 |
| 使用 MCP 连接器 | 资源地址、工具参数和必要的认证信息发送给配置的连接器服务。本地 stdio 程序也可能自行联网；连接器返回的材料保存为来源后，还可能被读取并发送给模型。连接器的逐报告授权与公开检索开关分开管理。 |
| 保存、生成和下载 Word | 稿件版本、审阅记录和导出文件保存在工作区；普通 Word 导出由本机程序完成，不额外调用模型。下载到同步盘、用第三方办公软件打开或主动分享后，后续去向由这些软件和你的操作决定。 |
| 由 WorkBuddy 等外部 Agent 调用 | 外部 Agent 可通过本地接口读取其请求的来源、稿件和结果；这些内容可能随后进入外部 Agent 自己的模型服务。由它提交的生成任务，仍使用 BriefLoop 工作区配置的宿主。 |

**实际接收方以宿主配置为准。** 自定义 Base URL、代理或模型网关可能先接收请求，再转发给模型厂商；仅凭模型名称不能判断文件内容最终经过哪些服务。第三方的保存期限、日志和训练使用规则取决于其服务与账户配置，BriefLoop 不统一控制这些规则。

工作区中的数据库、来源原件、稿件、Wiki、日志和审计包均可能包含敏感信息。删除本地文件不会自动删除第三方已经接收的内容；分享工作区、日志或审计包前，请检查其中的材料与个人信息。凭据保存在本机相应宿主或连接器配置中，不要把凭据文件随工作区或代码一起分享。

本地服务默认只监听 `127.0.0.1`，不直接开放公网访问。Agent 能读取哪些文件、执行哪些命令，由当前宿主实际支持的权限控制决定；“只读”不代表读取到的内容不会发送给云端模型，检索开关也不等同于所有宿主的网络隔离。

安装依赖、检查版本和下载更新还会访问相应的软件分发服务，这些请求与报告材料处理分开。使用内部或保密材料前，请确认所选宿主、模型、代理、搜索和连接器符合你的材料外发要求。

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

## 执行后端与模型

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

| 宿主 | 接入方式 | 模型目录 |
| --- | --- | --- |
| Codex | 原生 app-server | 原生 `debug models` |
| Opencode | 本机原生服务 | 本机 provider/model 配置 |
| Claude Code | bridge（stream-json） | 本机路由；无路由时给内置建议 |
| Kimi、Hermes | bridge（ACP） | ACP 模型目录；读取失败给内置建议 |
| Reasonix | bridge（ACP） | 原生 `doctor --json` |
| MiMo | bridge（JSON 事件流） | 原生 `models --verbose` |
| CodeBuddy Code | bridge（原生 `--acp`） | ACP 原生模型目录；支持手输模型 ID |

模型下拉只提供建议，任何宿主都接受手填模型 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 的应用接口与生命周期说明见 [连接器说明](src/briefloop/connectors/README.md) 和 [材料授权与回执](src/briefloop/connectors/MATERIALS.md)。Windows 已有原生协议及所属进程清理验证，具体边界见 [Windows 验证记录](docs/windows.md)；连接成功不代表任意企业服务、模型宿主或报告流程均已验收。

### BriefLoop 与三个学习、评价角色

| 角色 | 职责 |
| --- | --- |
| BriefLoop（主 Agent） | 与你对话、规划研究、调用 Scout 与 Analyst 产出稿件，并执行后续修订 |
| Evaluator | 给产物评分；比较候选产物，判断是否改善 |
| Wiki Maintainer | 将反馈和执行经验整理成 Wiki |
| Skill Proposer | 根据 Wiki 提出或改进 Skill |

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

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


## 搜索渠道

新工作区默认优先 Tavily，同时允许宿主自带搜索补充。两者可以在同一报告中使用；宿主仍需实际具备搜索工具及相应权限。Tavily 需要配置 Key，免费额度有上限。博查、智谱搜索和 DuckDuckGo 为可选补充渠道，不默认启用；也可更换首选或选择仅首选。没有强制搜索提供方。

补充策略可选择「检查跨市场覆盖并补缺」「仅遇缺口补查」或「只用首选」。市场与语言用于研究规划；公众号、小红书暂无专门接入。多渠道不保证消除偏差或覆盖全部平台内容。任务开始后冻结选择，修改设置只影响新任务。

搜索记录展示实际调用渠道、用途、错误和候选数量，来源页可按发现渠道筛选。同一网页由多家搜索服务找到仍是一份来源；发现链接、取得正文和事实核实分别记录。详见[使用指南](docs/使用指南.md#搜索渠道与来源)。

## 研究预算

| 预设 | 搜索调用尝试 | 去重候选 URL | 全文来源 URL |
| --- | ---: | ---: | ---: |
| 周报 | 30 | 150 | 60 |
| 月报 | 80 | 400 | 150 |

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

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

## 正文篇幅

| 预设 | 目标字数 | 字数上限 |
| --- | ---: | ---: |
| 速览 | 350 | 500 |
| 简短 | 800 | 1,000 |
| 标准 | 1,500 | 2,000 |
| 详细 | 2,000 | 2,500 |

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

## 正文图表与 Excel 复用

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

## 图片与 PDF 页面

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

## 行业定期报告

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

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

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

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

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

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

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

## 升级、边界与文档

外部 Agent 可通过 `briefloop external` 连接本机已运行的工作区，提交报告、查询进度、读取来源与稿件、保存指定版本修订并下载 Word。当前公开发行包含此入口；安装 CLI 使用 `python -m pip install --upgrade briefloop`。

```sh
briefloop external --workspace "/absolute/workspace" discover
briefloop external --workspace "/absolute/workspace" skill
briefloop external --workspace "/absolute/workspace" request --file request.json
```

先确认 `discover` 返回 `ready=true`，再按随包 Skill 构造请求；不会自动创建工作区或启动服务。生成使用工作区配置的模型，外部 Agent 的 `revise` 只保存其已完成的修改。写操作保留同一 `request_id` 与原内容以安全重试。

详见 [外部 Agent 调用文档](docs/WorkBuddy外部入口.md)、[随包 Skill 与请求示例](src/briefloop/skill_assets/briefloop-external/SKILL.md)；官网提供 [调用指南](https://briefloop.ai/docs/external-agent.html)。

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

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

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

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

- [0.21.0 工程技术报告](docs/technical-report-0.21.0/technical-report.md) · [证据索引](docs/technical-report-0.21.0/evidence-index.md)
- [产品定位与验证边界](docs/产品定位与验证.md)
- [合成周报示例](examples/internal-weekly-report/README.md)
- [已知边界与问题反馈](KNOWN_ISSUES.md)
- [贡献指南](CONTRIBUTING.md) · [安全问题](SECURITY.md)
- [使用指南](docs/使用指南.md)
- [多 Runtime 与模型设置](docs/多Runtime与模型.md)
- [变更记录](CHANGELOG.md)
- [来源与许可](THIRD_PARTY_NOTICES.md)

## 开发

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

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

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

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

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

### 工作区动态

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

版本发布前后可运行 [跨平台版本核对](docs/版本一致性检查.md)，比较实际 CLI、Mac App、Windows 程序和 PyPI；未提供的平台记录为未核验。

### 查看版本与更新

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

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

### 定时报告

首页可管理每日、每周、每月预设与自定义间隔计划，暂停、编辑或立即运行。仅工作区服务运行期间执行，离线时点不补跑；每期复用报告流程与当前已启用的 WikiSkill。详见[定时报告指南](docs/定时报告.md)。
