briefloop 0.18.0__tar.gz → 0.20.3__tar.gz

briefloop-0.20.3/.gitattributes

@@ -0,0 +1,3 @@
+# Build checks compare these generated artifacts byte-for-byte on every platform.
+/src/briefloop/static/app.js text eol=lf
+/src/briefloop/static/frontend-licenses.txt text eol=lf

{briefloop-0.18.0 → briefloop-0.20.3}/CHANGELOG.md

@@ -1,5 +1,85 @@
 # 变更记录
 
+## 0.20.3 — 发布准备中
+
+本节记录待发行的修复；安装包、PyPI 和更新入口以实际渠道提供的版本为准。尚未完成本版各平台安装与更新验收，不表示已统一发布。
+
+- 统一发行检查要求桌面后端与同一份发行 wheel 的 SHA-256 一致；导入的跨平台检查失败不会被相同版本号覆盖成通过。
+- 纳入下方 0.20.2 的运行时卡片改进，并接入 DeepSeek Harness、Antigravity 和 Pi 的原生会话；聊天中可选择宿主实际支持的权限。模型、账户可用性及受限审阅能力仍以实际宿主为准。
+- 修复桌面主进程异常退出后的后台归属清理；停止时先保存已接纳的本地修改，再取消外部 MCP 调用。工作区切换先检查目标，启动失败时提供恢复路径；桌面一次管理一个活动工作区。
+- OpenCode 服务绑定启动它的 Python 进程；macOS/Linux 上父进程被强制结束后回收所属服务及进程组，Windows 沿用所属 Job 清理。不按程序名称清理用户的其他 CLI。
+- OpenCode 与 Codex 后台按需启动，无活动回合、子任务或在途配置请求时空闲 30 秒回收；保留已保存的原生会话供下一回合恢复。OpenCode 模型列表缓存命中时不重新启动服务。
+- 通用 CLI Bridge 空闲 30 秒释放，活动调用和会话事件订阅保留连接；退出时清理它启动的模型目录探测与执行子进程。网页空闲/隐藏时降低轮询频率，回到前台立即刷新，慢请求不重叠。
+- 后台任务队列空闲时逐步降低查库频率，同服务入队后立即唤醒；其他进程提交保留最多 5 秒的发现间隔。独立 CLI 服务不会因为关闭网页或长时间无操作而自动停止。
+- 修复运行时发送背压、进程死亡后会话不结束，以及子任务同名工具的新调用被进度去重遗漏的问题；无变化的心跳不重复写成进展。
+- 相同 Word 输入的并发导出共用一个任务，文件缺失或损坏可重新制作。修复富文档行业报告的重复首标题、图表来源遗漏与非法图片导致保存状态无法恢复的问题。
+- Markdown 导入需要明确确认转换；普通保存保留富文档的颜色、表格、图片和引用，历史版本仍可查看。上传前显示文件大小限制，超限不先读入整份附件。
+- 修复软性要求的条款 ID 被误当成硬性要求；事实矛盾继续按事实问题处理。审阅发现可引用本次固定包内的来源陈述，来源陈述不会因此自动成为正文已核实的主张。
+- 学习比较核对冻结的内容方法与评价条件；初始化中断可恢复，过滤后没有可用材料的案例说明原因，不记为候选技能收益。
+- 损坏 PDF/XLSX 的已知解析错误定位到对应材料；连接器配置损坏时保留原文件和诊断，历史稿件仍可查看。任务结束释放所属连接器资源。
+- 研究轮次变更、企业背景事实与冲突登记采用原子提交，避免并发覆盖和中断留下无法处理的记录。
+- 补齐日志凭据遮蔽、连接器动态加载环境变量限制，以及私有 GET 接口的跨站来源检查；正常网页下载和本地外部客户端沿现有接口使用。
+- 连接测试保留独立历史入口，错误和取消结果可查看；普通最近会话不再混入连接测试。统一聊天工具栏文字样式。
+- 尚未选择模型时仍可查看和下载已有报告、读取来源及打开设置；开始新对话或新报告时再确认执行模型。
+
+## 0.20.2 — 源码改动，未独立发行
+
+以下改动已合并源码，将随 0.20.3 一同发行；没有单独的 0.20.2 PyPI 包或桌面安装包。
+
+- 运行时卡片加入本地品牌图标、简介、检测版本和当前模型；图标随应用分发，离线可见。未安装运行时展开为双列卡片，窄屏自动变成单列。
+- 去掉首页聊天框重复的“当前：runtime”，保留可操作的宿主选择器和回合执行记录。
+- 修复 Kilo、Kiro、Vibe 已有 ACP 适配却被可选宿主名单阻挡的问题；安装检测、协议适配和实际调用结果分别呈现，不把模型目录当作账号调用成功。
+- 更新失败分别显示检查失败、下载未完成、安装未完成；检查失败不附带旧版本目标，重试按失败阶段执行，保留具体错误与限流恢复时间。
+
+
+## 0.20.1 — 2026-09-13
+
+本次发布 Python / CLI / Web 包；桌面源码版本同步，未重新发行 Mac / Windows 安装包。
+
+- 新增工作区动态与侧栏未读红点：报告任务开始、完成和失败，用户模板、Wiki 内容及可用版本更新。支持查看对应页面、全部标为已读，刷新或重开后保留已读状态，重复事件不重复提醒。
+
+- 新增跨平台版本核对：从 pyproject.toml 读取目标版本，比较源码、实际 CLI、Mac/Windows 程序及其内置 wheel、PyPI 最新版和包哈希；缺少平台证据不算一致。
+- 统一 App、网页版与 CLI 的实际后端版本、安装来源和 PyPI 更新检查；桌面更新限流显示恢复时间并避免重复请求。
+
+- 接通证券研究内容方法及券商模板建议，支持事件点评、公司研究和行业跟踪；核对指标口径、预测类别与估值输入。默认模板移除泛化免责声明和固定评级占位，保留具体风险分析。
+- 修复 WPS 表头单独留在上一页页底；内置模板导出清理旧 Courier 声明，保留用户模板字体。新版生成使用新导出指纹，历史 Word 文件保持原样。Windows WPS 的该字体提示已验证消除；Mac WPS 仍可能提示缺失字体。
+- Word 表格继承模板单元格段落样式，列数与模板样例不同时按内容分配宽度，并保持单行完整，避免长指标挤窄或跨页断行。
+- 修复列表结尾报告首次聚焦时自动产生空段落并误保存用户修订的问题。
+
+- 接通会议纪要内容方法和内置纪要模板建议：依据实际转写或笔记区分讨论、决议、建议、改口与未定事项；无会议记录时阻止生成，材料提示同步说明输入要求。方法随任务保存，独立评价核对负责人和期限依据。
+
+- 同一对话可显式选择下一回合宿主并回切，交接可见历史，保留原生会话归属和已冻结任务；详见 [对话宿主切换](docs/对话宿主切换.md)。
+- 新增 WorkBuddy 等本地 Agent 使用的外部 CLI 与 Skill：只读发现已有服务、提交和查询报告、读取材料与稿件、按 base_version 保存富文档修订、导出并校验下载指定版本 Word。写请求通过稳定 request_id 重试，复用原任务和原版本。
+
+## 0.20.0 — 2026-09-13
+
+- 新增 Electron 桌面 App：原生工作区选择、Word 另存、保存后退出、所属服务停止与重开；提供 macOS Apple Silicon DMG 和 Windows x64 EXE。
+- 精简桌面安装内容：复用 Electron 内置 Node，检测本机 Python 3.11+，使用 App 专属虚拟环境安装依赖；缺少 Python 时给出安装入口。沿用普通安装包，不新增在线安装器。
+- 设置新增版本更新：检查官方发布、下载进度和用户发起安装；安装前保存编辑并停止所属任务，失败保留错误及恢复路径。
+- CodeBuddy 接入原生 ACP：宿主模型目录、自定义模型 ID、对话续接、文件授权、读写与取消。受限 Reviewer 仍要求宿主实际支持。
+- Codex 官方 OpenAI provider 的适用配置可选择 Fast；配置随消息、任务和角色模型保存，恢复继续沿用原配置。
+- 通用报告与商业报告接通独立内容方法，包含行业周月报、工作进展周报和决策分析；实际方法版本随报告保存，Word 版式单独选择。
+- MCP 材料按报告明确选择、冻结授权与预算；实际读取保存原件、回执和来源。修复旧凭据格式与可选空目录影响设置使用的问题。
+- 执行时限支持“不限时”，保留手动取消。对话显示提供商错误及实际重试状态，报告等待权限时提供任务对话入口。
+- 修正评价条款引用校验、行动建议被误判为既成事实的问题；区分原稿、当前修订与历史导出版本，修复保存与运行状态更新。
+
+本版仍不提供同对话跨宿主切换、WorkBuddy 外部任务入口，或会议纪要／证券研究的专门内容流程。八类 Word 版式不等于八条内容流程。桌面签名、公证和首次安装系统提示见 [桌面指南](docs/桌面安装与更新.md)。
+
+## 0.19.0 — 2026-09-12
+
+- 首次使用可在空工作区导入合成周报，直接查看、编辑、导出；标明未调用模型、未评分，关闭自动学习，保留模型选择。并发导入和中途中断重试共用同一份示例。
+- 数值检查真正限定原文行、PDF 页或结构化证据位置，不再在整份来源中借用摘录；定位不明仍显示未检查，已确认数值错配阻断正式交付。主体、期间、口径仍需审阅。
+- 排队时冻结并发上限，研究计划与实际提示词使用同一快照。Node 可通过 BRIEFLOOP_NODE 指定；缺少 Node 时保留 Codex / Opencode 原生发现。
+- 修复空工作区状态栏异常、编辑含引用报告时被链接空属性阻断保存，以及显式 runtime 被未选择默认模型误拒绝。
+- 新增 350／500 字速览预设；统一使用指南中的研究预算和模板名称。
+- PyPI 元数据补齐 README、许可证和项目链接；wheel/sdist 携带原始第三方许可，前端按实际 bundle 输入生成许可清单，缺许可构建失败。CI 检查产物漂移并运行全部前端行为检查。
+- 增加产品定位、已知边界、数据流向、贡献与安全反馈说明；不把交付条件、一次学习拒绝或合成测试写成事实正确率与学习净收益保证。
+
+- 同稿换版式导出：导出菜单可选任一就绪模板，对已保存版本按新模板重排生成 Word；正文不变，导出指纹随版式区分。
+- 「已保存版本检查」新增版式检查：标题层级中断、空标题、缺表头行的表格，确定性报告、不阻断交付；检查结果同时进入独立审阅输入包。
+- 行业定期报告与内置研报版式的 Word 输出新增目录页：标题写入稳定书签，提供可点击目录与缓存文本，支持更新域的阅读器可刷新页码；通用简报输出不变，导出身份号升级以刷新缓存。
+- 内置版式矩阵随包分发：7 类文体（通用/商务/学术/年报/合同/纪要/券商研报）各 5 套主题（品牌绿/极简蓝/珊瑚红/石墨黑/典雅灰），加 1 套固定公文版式，共 36 套；公文按 GB/T 9704 固定红头与字体只出正典一格。模板页为画廊布局：文体卡片（图标与适用说明）+ 配色点选主题，底部「已选」栏与「使用该模板」确认后设为默认并跳转新建表单；设置页下拉按文体分组。工作区首次打开自动注册；标题按章节名匹配模板样式（含序号归一），不再要求手工锚点。
+
 ## 0.18.0 — 2026-09-11
 
 - 公开发布身份统一：Python 分发名 `briefloop-local` → `briefloop`，CLI 仍为 `briefloop`。

briefloop-0.20.3/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# 贡献与反馈
+
+普通问题请使用仓库的 Bug report 模板，附最小复现。优先描述丢稿、版本混用、错误放行、停止失效等用户行为，不必提供整份工作区。
+
+## 可复现的信息
+
+1. `briefloop --version`、操作系统版本、所选宿主名称和 CLI 版本。
+2. 从空工作区开始的操作步骤，预期结果、实际结果和错误发生时间。
+3. 能触发问题的合成材料；来源、正文和截图都应先去除真实客户与内部信息。
+4. 如需日志，只截取错误前后必要片段。`server.log`、任务公开日志、截图与审计包可能包含材料正文、路径、提示词、网址和账号信息。手动检查并删去 Key、Authorization、Cookie、会话令牌、私有 endpoint、个人路径等内容；自动脱敏不是完整保证。
+
+不要上传 `.env`、宿主认证文件、完整数据库、工作区压缩包或未经检查的 `briefloop status` 输出。安全问题不要在公开 Issue 中附利用细节或敏感样本，见 [SECURITY.md](SECURITY.md)。
+
+## 开发检查
+
+```sh
+python3 -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]' build
+npm ci
+node runtime-bridge/build.mjs
+npm run build
+npm test
+node --test runtime-bridge/bridge.test.mjs
+.venv/bin/python -m pytest tests -q
+.venv/bin/python -m build
+.venv/bin/python tests/check_distribution.py dist/*.whl dist/*.tar.gz
+```
+
+前端修改后同时提交生成的 `app.js` 和许可证清单；CI 会检查是否漂移。第三方代码保留原始许可和来源。新增依赖需要明确用途并检查发行包包含相应许可。
+
+回归检查应保护真实行为，优先复用已有用例，不增加只锁文案或复制常量的测试。涉及保存、恢复、交付或隔离时，提供实际失败场景与修复证据。常规自动检查不调用模型、搜索服务，也不使用真实私有材料。
+
+提交代码时请确认你有权贡献这些内容，并接受仓库 MIT 许可证。请勿提交凭据、运行数据、私有方案或第三方受限材料。

briefloop-0.20.3/KNOWN_ISSUES.md

@@ -0,0 +1,21 @@
+# 已知边界与问题反馈
+
+适用于 0.20.0。这里区分当前能力和仍需人工核对的部分。
+
+| 范围 | 当前边界与处理方式 |
+| --- | --- |
+| 平台 | 桌面首批支持 macOS Apple Silicon 与 Windows x64；Linux 仅有 WebUI/离线 CI。安装与平台验收范围见 [桌面指南](docs/桌面安装与更新.md) 及 [Windows 说明](docs/windows.md)。 |
+| 后续能力 | 同对话跨宿主切换、WorkBuddy 外部入口、会议纪要及证券研究专门内容方法尚未提供；已有同名 Word 版式可使用。 |
+| 首次使用 | 欢迎页可在空工作区导入合成示例，不需要模型或搜索 Key。实际生成、独立审阅和学习需要自己已认证的宿主与模型。 |
+| 数值检查 | 只比较已明确绑定的正文数值和指定来源位置，支持的币种/单位可规范化。不完整、无法定位或不支持的绑定显示“未检查”；没有覆盖任意正文中的所有数字。已确认不匹配会阻断正式交付。 |
+| 语义与覆盖 | 主体、期间、口径、因果、预测和遗漏需要 Agent / Reviewer 核对。证据匹配和交付条件不构成正确率保证；没有登记缺口或冲突，也不说明检查完整。 |
+| 跨段与来源类型 | 尚无对任意文本的自动跨段同指标一致性检查，也没有按来源类型自动裁决真伪。可比较结构化行业记录，登记分歧，并保留双方原文交由 Reviewer 核对。 |
+| Reviewer | 受限能力取决于宿主实际隔离，不能用“只读”提示词代替权限。当前可用条件见 README；缺能力时不会降级为已审阅。 |
+| 宿主与 Node | Codex / Opencode 原生通道不依赖 bridge 的 Node。WebUI 下其余宿主需要 Node.js 20+；桌面 App 复用 Electron Node。WebUI 可用 `BRIEFLOOP_NODE=/absolute/path/to/node` 指定。命令能找到不证明账号登录和模型调用成功。 |
+| 来源读取 | 扫描 PDF、图片和复杂表格可能需要视觉核对；读取失败保留缺口。仅有搜索摘要不算已读取全文。 |
+| Word | 用户模板暂限单节 DOCX；复杂合并单元格、浮动对象、跨节布局不保证保真。不同阅读器字体、分页和目录页码刷新可能不同，正式使用前打开实际导出件。 |
+| 工作簿 | 能读取表格和复用图像，但不是在线 Excel，也不导出可编辑的复杂工作簿。 |
+| 学习 | 默认候选满足比较策略后自动启用，保留旧版和回退；Wiki 是经验，当前任务通过启用技能使用经验，不把 Wiki 当本期事实。尚无可推广的净收益结论。 |
+| 运行 | 关闭浏览器后后台任务继续；关闭本地服务或电脑会中断。定时、无人值守批量、局域网团队服务和移动端尚未提供。 |
+
+遇到问题先保留工作区，在新空目录用合成材料复现。记录版本、系统、宿主、步骤、预期与实际现象；按 [CONTRIBUTING.md](CONTRIBUTING.md) 只分享已检查的必要日志。安全问题按 [SECURITY.md](SECURITY.md) 私下报告。

briefloop-0.20.3/MANIFEST.in

@@ -0,0 +1,22 @@
+recursive-include docs *.md
+include KNOWN_ISSUES.md SECURITY.md CONTRIBUTING.md
+include VERSION README.md THIRD_PARTY_NOTICES.md CHANGELOG.md bootstrap.py start.sh start.ps1 package.json package-lock.json .gitattributes
+recursive-include frontend *.js
+include scripts/check_versions.py
+include desktop/electron/package.json desktop/electron/package-lock.json
+include scripts/build_frontend.mjs scripts/build_frontend_licenses.mjs scripts/test_frontend.mjs
+include tests/frontend_*.mjs tests/check_distribution.py
+recursive-include src/briefloop/static *
+recursive-include src/briefloop/skill_assets *.md
+recursive-include src/briefloop/template_assets *
+recursive-include src/briefloop/workflow_assets *.json *.md
+prune workspaces
+prune private_planning
+global-exclude __pycache__ *.py[cod] .DS_Store
+
+recursive-include runtime-bridge *.ts *.mjs *.json *.md
+recursive-include third_party/open-design *
+recursive-include examples *.md *.txt
+prune output
+
+recursive-include probes/mcp_m0 *.py *.md *.txt

briefloop-0.20.3/PKG-INFO

@@ -0,0 +1,312 @@
+Metadata-Version: 2.4
+Name: briefloop
+Version: 0.20.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: 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 0.20.2
+
+面向行业研究、战略与 IR 使用者的本地报告工作台：把分散材料整理成可编辑简报，逐项查看重要结论的依据、处理审阅问题，并保留原稿与修订版本。适合需要定期写报告、核数字和核口径的单人工作。
+
+界面与文档为中文，报告正文可选中文或英文。研究深度取决于所选宿主自身的能力和本次报告的共享预算，本版不提供托管式 Deep Research 服务。
+
+新建报告可选择通用报告，或商业报告下的行业周报／月报、工作进展周报与决策分析。内容方法贯穿规划、写作、修订与评价，并随报告保存实际版本；Word 模板单独控制版式。八类内置版式可继续使用，其余文档类型的专门内容流程将分批接入。
+
+0.20.2 的运行时设置新增本地图标、简介、实际版本与模型信息；未安装工具按卡片浏览。首页仅保留宿主选择器，更新失败会区分检查、下载和安装阶段。见 [运行时选择与检测](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 时另行配置自己的 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 提取时，目标 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 包。
+
+
+## 研究预算
+
+| 预设 | 搜索调用尝试 | 去重候选 URL | 全文来源 URL |
+| --- | ---: | ---: | ---: |
+| 周报 | 30 | 150 | 60 |
+| 月报 | 80 | 400 | 150 |
+
+预算由整次报告中的 Scout 共享，不是每个 Scout 各拿一份，也不要求花完。失败的 Tavily Search 调用仍计次；同一 URL 的直接获取、Extract 回退及重试不重复扣全文 URL。达到额度后保留材料、说明缺口，不自动加额。
+
+搜索请求和候选额度适用于受控 Tavily 工具；宿主自带的搜索（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)。
+
+## 升级、边界与文档
+
+0.20.1 新增本地外部任务入口：WorkBuddy 等可执行本机命令的 Agent 可连接已有工作区，提交报告、查询进度、保存指定版本的修订和下载 Word。使用说明见 [WorkBuddy 外部入口](docs/WorkBuddy外部入口.md)；可使用 `pip install --upgrade briefloop==0.20.2` 安装；既有 0.20.0 桌面安装包不包含此入口。
+
+会议纪要内容方法也在后续源码中接入：选择内置纪要模板即可建议相应用途，输入本次会议转写或笔记，整理决议、待办和未定事项。见 [会议纪要说明与合成材料](docs/会议纪要.md)。
+
+证券研究方法提供事件点评、公司研究和行业跟踪，按来源区分实际、预测与估值假设，使用有依据的数据生成图表。见 [证券研究说明与合成材料](docs/证券研究.md)。
+
+0.17.0 是架构升级。旧提交和发布标签保留；旧版工作区不自动迁移。请保留旧目录，在新工作区按需要导入原始材料。[升级说明](docs/升级说明.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 升级。