1. 项目概述：一个被误读的开源研究协作范式
“OpenResearch”这个词最近在开发者社区里频繁出现，但很多人一看到就下意识联想到某个具体工具、CLI命令或AI编码插件——比如把 orx 当成类似 codex cli 或 claude cli 那样的命令行助手，甚至有人在飞书群聊里问“orx 怎么接入飞书机器人”，或者在 Windows 终端里反复执行orx --version却报错 “unable to locate the binary”。这其实是个典型的语义漂移现象：当一个抽象理念（Open Research）被压缩成一个简短代号（OpenResearch），再叠加 CLI、local-first 等技术热词，它就很容易被当作某个可下载、可安装、可配置的软件产品来对待。但事实并非如此。
OpenResearch 不是一个 npm 包，不是 GitHub 上某个 star 过万的 CLI 工具，也不是某家大厂刚发布的 AI 编程套件。它是一套正在成型的研究协作方法论，核心是把科研工作流从中心化平台（如 arXiv、PubMed、ResearchGate）逐步迁移到本地优先（local-first）、可验证、可复现、可组合的个人知识基座上。这里的 “open” 指的不是开源代码意义上的 open，而是指研究过程的开放性——数据来源可追溯、实验步骤可重放、推理链条可审计、协作痕迹可版本化。而 “research” 也早已不限于学术论文，它涵盖产品需求验证、竞品功能逆向、A/B 测试归因、用户行为建模、甚至内部 SOP 的持续迭代——只要是需要证据支撑的决策过程，都属于 OpenResearch 的实践场域。
我从去年开始用这套思路重构团队的技术文档体系，把原来散落在 Confluence、Notion、飞书文档、GitLab Wiki 里的 200+ 个技术方案页，全部迁移进一个基于本地 Git 仓库 + Markdown + 自定义元数据的结构化知识库。过程中发现：真正卡住落地的，从来不是 CLI 工具好不好用，而是“谁来定义研究问题”、“数据从哪来、怎么清洗”、“结论如何与原始证据锚定”、“协作时如何避免版本冲突又不牺牲透明度”这些底层机制。orx 这个缩写，其实是社区自发形成的 shorthand，全称是 open research exchange，它指向的是一组约定俗成的接口规范、元数据 schema 和最小可行协作协议，而不是一个二进制文件。你可以在终端里敲orx init，但这个命令背后调用的，是你自己写的 Python 脚本、Shell 函数，或是用 Rust 封装的本地 SQLite 查询器——只要它遵循 orx 定义的 artifact manifest 格式，它就是合法的 OpenResearch 工具链一环。
所以如果你正被 “unable to locate the orx binary” 这类报错困扰，先别急着重装 Node.js 或检查 PATH；真正该做的，是打开你电脑上的一个空文件夹，新建一个research/目录，在里面创建第一个2024-06-15-user-onboarding-flow.md文件，手动写上三行：
--- title: 新用户引导路径转化率分析 date: 2024-06-15 sources: [prod-logs-20240614.json, survey-q3-raw.csv] ---这就是 OpenResearch 的起点——不是 CLI，而是你对“什么是可靠证据”的一次主动声明。
2. 核心设计逻辑：为什么必须 local-first，而不是 cloud-first？
2.1 local-first 不是技术怀旧，而是信任模型重构
很多人把 local-first 理解为“把文件存在自己硬盘上”，这没错，但远远不够。真正的 local-first 是一套信任分配机制的重置：它把“可信计算环境”的锚点，从远程服务器（你无法审计其日志、内存状态、网络策略）转移到你本地可控的执行上下文（你的终端、你的 VS Code 插件沙箱、你笔记本上运行的轻量级服务）。这不是为了对抗云，而是为了在云无处不在的时代，重新夺回对“证据链完整性”的最终解释权。
举个实际例子：我们曾用某 SaaS 分析平台做漏斗归因，平台显示“注册页跳出率下降 12%”，但当我们导出原始事件日志，在本地用 Pandas 重跑一遍计算，发现结果是 +3.7%。差异来自平台默认启用了会话采样（session sampling），而文档里只在 FAQ 第 7 条小字注明“采样率 92%”。如果整个分析流程都跑在云端，你永远不知道那个 92% 是怎么算出来的，更没法验证它是否随时间漂移。但换成 local-first 模式：所有原始日志存本地 SSD，清洗脚本用 Git 版本管理，计算结果用 Merkle Tree 哈希存证，每次报告生成时自动附带git log -n 5和sha256sum raw_logs/*.json输出——这时，“注册页跳出率”就不再是一个黑盒数字，而是一条可追溯、可质疑、可复现的证据链。
提示：local-first 的关键指标不是“文件是否在本地”，而是“任意环节的输入输出是否可独立验证”。如果一个 CLI 工具声称支持 local-first，但它调用的远程 API 返回的是加密 blob，且没有提供解密密钥或验证签名，那它只是 local-storage，不是 local-first。
2.2 CLI 作为 glue layer，而非功能主体
现在市面上大量打着 “CLI” 旗号的工具（codex cli、claude cli、trae cli），本质是把 LLM 接口包装成命令行，让用户用cli query "帮我写个正则"替代网页点击。这种 CLI 是功能层（feature layer），它的价值完全依赖后端模型的可用性与响应质量。而 OpenResearch 所需的 CLI，是 glue layer —— 它不生成内容，只负责连接、转换、验证和路由。
比如一个符合 OpenResearch 规范的orxCLI，它的核心命令可能只有四个：
orx ingest <source>：把外部数据源（API 响应、CSV、PDF 文本）标准化为本地artifacts/目录下的结构化 JSON-LD 文件，并生成 provenance 记录（谁、何时、用什么脚本、从哪拉取）；orx link <artifact-id> <evidence-id>：在两个本地 artifact 之间建立语义链接（例如“这份用户访谈记录支持‘支付失败主因是风控误判’这一结论”），链接本身也存为独立文件，便于 diff 和审计；orx render <report-id>：根据预设模板（Jinja2 / Mustache），把一组 linked artifacts 渲染成 HTML/PDF 报告，渲染过程全程离线，所有引用资源（图表、截图）必须已存在于assets/目录；orx sync：将本地变更推送到 Git 远程，同时触发 CI 流水线执行orx verify—— 这个命令会检查所有链接是否有效、所有引用 artifact 是否存在、所有 provenance 时间戳是否逻辑自洽。
你会发现，这里没有orx ask、orx think、orx generate这类命令。因为 OpenResearch 的立场很明确：研究过程中的“思考”和“生成”必须由人完成，工具只负责确保思考有据可依、生成有迹可循。CLI 在这里就像实验室里的移液枪——它不决定实验结论，但保证每次取样的体积精确、路径可追溯、污染可排除。
2.3 autoresearch 的真实含义：自动化证据链维护，而非自动化研究
“autoresearch” 这个词常被误解为“让 AI 替你做研究”，这是危险的幻觉。真正的 autoresearch，是指用自动化手段维护研究证据链的完整性、一致性和时效性。它解决的是“人容易忘记”、“人会犯错”、“人没时间重复验证”这些现实瓶颈，而不是替代人的判断。
我们团队实践 autoresearch 的典型场景是竞品监控。过去靠人工每周截图、整理、比对，效率低且易遗漏。现在我们用一个 80 行的 Python 脚本（封装为orx ingest competitor-ui）每天凌晨自动抓取 5 家竞品首页 DOM，提取关键元素（价格标签、CTA 文案、新功能 banner），存为artifacts/competitor-ui-20240615.json。更重要的是，脚本会自动生成provenance/competitor-ui-20240615.prov.json，记录：
- 抓取时间（UTC）
- 目标 URL 及 HTTP 状态码
- 使用的 User-Agent 字符串
- DOM 提取 XPath 表达式
- 生成 artifact 的 SHA-256 哈希
然后另一个 cron job 每小时运行orx verify --since yesterday，检查是否有 artifact 缺失、provenance 时间戳倒置、或链接到不存在的 evidence ID。一旦发现问题，立刻发企业微信告警：“artifacts/competitor-ui-20240614.json的 provenance 中记录的抓取时间为 2024-06-14T03:15:22Z，但文件 mtime 为 2024-06-14T02:48:11Z —— 可能存在时钟不同步或文件篡改”。
这才是 autoresearch：它不告诉你竞品改了什么，但它确保你看到的每一个改动，都有完整、可信、可验证的证据支撑。自动化在这里是守门员，不是主教练。
3. 实操落地：从零搭建你的 OpenResearch 工作区
3.1 目录结构设计：为什么不用单文件，而要分层存储
很多新手想快速上手，直接建一个research.md开始写。短期可行，长期必崩。OpenResearch 的威力在于跨 artifact 的关联能力，而这依赖于清晰、一致、机器可读的目录结构。我们采用四层结构，已在 3 个业务线稳定运行 18 个月：
research/ ├── artifacts/ # 所有原始证据与衍生结论的存放地（不可编辑，只由 ingest 生成） │ ├── user-survey-20240610.json │ ├── a-b-test-v2-results.csv │ └── api-response-payment-fail-20240612.json ├── evidence/ # 人工撰写的分析、推论、假设（可编辑，Markdown 格式） │ ├── hypothesis-payment-fail-root-cause.md │ └── analysis-survey-qualitative.md ├── links/ # artifact 与 evidence 之间的语义链接（JSON 格式，自动生成） │ ├── link-001.json # { "from": "artifacts/user-survey-20240610.json", "to": "evidence/hypothesis-payment-fail-root-cause.md", "relation": "supports" } │ └── link-002.json └── assets/ # 所有渲染报告所需的静态资源（截图、图表 SVG、字体文件） └── screenshots/这个结构的设计逻辑非常务实：
artifacts/目录强制只读（chmod -R 444 artifacts/），任何修改都必须通过orx ingest命令触发，确保所有原始数据都有 provenance 记录；evidence/目录允许直接编辑，但每个文件顶部必须包含 YAML front matter，声明其依赖的 artifacts（sources:字段）和生成的结论（conclusions:字段），这是后续orx verify的检查依据；links/目录不手动维护，由orx link命令生成，文件名按 UUID 命名，避免命名冲突，内容严格遵循 JSON Schema（我们开源了 schema 定义）；assets/目录的存在，是为了让orx render能生成完全离线的报告——所有图片必须本地化，不能引用 CDN 链接，否则报告在断网时就失效。
注意：不要试图用 Git LFS 存储大文件到
artifacts/。我们试过，结果是每次git status都卡顿。正确做法是：对大于 1MB 的文件（如原始视频、大型日志包），只存其哈希值和元数据到artifacts/，真实文件存 NAS 或对象存储，用orx fetch <hash>按需拉取。这样既保持仓库轻量，又不破坏证据链完整性。
3.2 元数据 schema：用最少字段承载最大语义
OpenResearch 的力量，70% 来自结构化元数据。我们不追求大而全的 schema，只定义 5 个核心字段，覆盖 95% 的研究场景：
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
id | string | ✓ | 全局唯一标识，格式为type-YYYYMMDD-NNN | survey-20240610-001 |
title | string | ✓ | 人类可读标题，不超过 80 字 | Q3 用户付费意愿深度访谈（上海组） |
sources | array of strings | ✓ | 直接来源的 artifact ID 列表 | ["api-response-payment-fail-20240612.json"] |
provenance | object | ✓ | 证明来源的元数据对象 | { "ingested_by": "orx ingest", "ingested_at": "2024-06-15T02:30:00Z", "ingest_script_hash": "sha256:abc123..." } |
conclusions | array of strings | ✗ | 由此 artifact 直接支持的结论 ID 列表 | ["hypothesis-payment-fail-root-cause.md"] |
这个 schema 的精妙之处在于sources和conclusions的双向绑定。当你在evidence/hypothesis-payment-fail-root-cause.md里写“支付失败主因是风控误判”，你必须在它的 front matter 里声明sources: ["user-survey-20240610.json", "a-b-test-v2-results.csv"]；而orx verify会检查：这两个 source artifact 是否真实存在？它们的conclusions字段里，是否包含了当前 evidence 文件的 ID？如果缺失，就报错：“user-survey-20240610.json声明支持hypothesis-payment-fail-root-cause.md，但后者未在sources中声明此 artifact —— 证据链断裂”。
我们曾用这个机制揪出一个严重疏漏：市场部同事提交了一份竞品分析报告，引用了某份第三方数据，但那份数据的sources字段为空（因为是手动复制粘贴的 Excel 表格），导致orx verify直接拒绝合并 PR。这逼着他们重新走了一遍orx ingest流程，最终发现原始数据里有个隐藏的筛选条件没写进报告——避免了一次重大误判。
3.3 CLI 工具链：用 Bash + jq + Git 构建最小可行 orx
你不需要 Rust 或 Go 来写orxCLI。我们生产环境的orx就是一个 320 行的 Bash 脚本，依赖只有jq、git、curl和sha256sum。它证明了一个观点：OpenResearch 的门槛不在技术复杂度，而在设计一致性。
以下是orx ingest的核心逻辑（已脱敏）：
#!/bin/bash # orx ingest <source-type> <source-url-or-path> set -e SOURCE_TYPE=$1 SOURCE_REF=$2 ARTIFACTS_DIR="research/artifacts" TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ") ARTIFACT_ID="${SOURCE_TYPE}-$(date -u +"%Y%m%d")-$(printf "%03d" $(ls ${ARTIFACTS_DIR}/${SOURCE_TYPE}-*.json 2>/dev/null | wc -l | xargs))" case $SOURCE_TYPE in "api") # 用 curl 获取 JSON，添加 provenance curl -s "$SOURCE_REF" | jq -n \ --arg id "$ARTIFACT_ID" \ --arg type "$SOURCE_TYPE" \ --arg timestamp "$TIMESTAMP" \ --arg ref "$SOURCE_REF" \ '{ id: $id, title: "API response from \($ref)", sources: [], provenance: { ingested_by: "orx ingest", ingested_at: $timestamp, source_url: $ref, ingest_script_hash: "sha256:$(sha256sum "$0" | cut -d" " -f1)" }, conclusions: [] }' > "${ARTIFACTS_DIR}/${ARTIFACT_ID}.json" ;; "csv") # 用 csvkit 处理 CSV，转为 JSON-LD if ! command -v csvjson &> /dev/null; then echo "Error: csvjson not found. Install with 'pip install csvkit'" >&2 exit 1 fi csvjson -I "$SOURCE_REF" | jq -n \ --arg id "$ARTIFACT_ID" \ --arg type "$SOURCE_TYPE" \ --arg timestamp "$TIMESTAMP" \ --arg ref "$SOURCE_REF" \ '{ id: $id, title: "CSV data from \($ref)", sources: [], provenance: { ingested_by: "orx ingest", ingested_at: $timestamp, source_file: $ref, ingest_script_hash: "sha256:$(sha256sum "$0" | cut -d" " -f1)" }, conclusions: [] }' > "${ARTIFACTS_DIR}/${ARTIFACT_ID}.json" ;; *) echo "Unknown source type: $SOURCE_TYPE" >&2 exit 1 ;; esac echo "Ingested: ${ARTIFACTS_DIR}/${ARTIFACT_ID}.json" git add "${ARTIFACTS_DIR}/${ARTIFACT_ID}.json" git commit -m "orx ingest: ${ARTIFACT_ID}"这个脚本的关键设计点：
- 强制 Git 提交：每次
ingest都伴随git add && git commit，确保所有 artifact 的引入都有时间戳和作者信息，这是审计的基础； - 脚本自哈希：
ingest_script_hash字段记录的是orx脚本自身的 SHA-256，这意味着如果你修改了抓取逻辑，provenance会立刻体现变化，避免“同一份脚本不同版本产出相同 artifact ID”的混淆； - ID 生成策略：
$(printf "%03d" ...)确保同一天同一类型 artifact 的 ID 递增（api-20240615-001,api-20240615-002），比 UUID 更易读，且避免了并发冲突（因为git commit是原子操作）； - 错误即退出：
set -e保证任何命令失败都终止脚本，防止半成品 artifact 污染仓库。
我们没用 Node.js 或 Python，是因为 Bash 的依赖最轻、兼容性最强、审计最简单——你可以用cat orx一眼看清它做了什么，而不用去翻node_modules里几十层嵌套的依赖。
3.4 渲染与交付：如何生成一份真正“可验证”的报告
orx render的目标不是做出炫酷的 PPT，而是生成一份“即使十年后打开，也能独立验证其结论”的静态文档。我们用一个极简的 Jinja2 模板实现：
<!-- report-template.html --> <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>{{ report.title }}</title> <style>body{font-family:sans-serif;line-height:1.6}</style> </head> <body> <h1>{{ report.title }}</h1> <p><strong>生成时间：</strong>{{ now }}</p> <p><strong>证据链完整性：</strong>{% if report.verified %}✅ 通过{% else %}❌ 失败{% endif %}</p> <h2>核心结论</h2> {% for conclusion in report.conclusions %} <div class="conclusion"> <h3>{{ conclusion.title }}</h3> <p>{{ conclusion.content }}</p> <h4>支持证据</h4> <ul> {% for source in conclusion.sources %} <li><a href="{{ source.url }}">{{ source.title }}</a> ({{ source.id }})</li> {% endfor %} </ul> </div> {% endfor %} <h2>附录：原始证据摘要</h2> {% for artifact in report.artifacts %} <details> <summary>{{ artifact.title }} ({{ artifact.id }})</summary> <pre>{{ artifact.preview | truncate(200) }}</pre> </details> {% endfor %} </body> </html>关键点在于report.verified字段：它不是前端 JS 计算的，而是在orx render命令执行前，先调用orx verify --report，把验证结果（JSON 格式）注入模板上下文。这意味着报告里的“✅ 通过”字样，本身就是被验证过的证据的一部分——如果有人篡改了报告 HTML，这个验证标记就会失效。
我们还强制所有<img>标签必须使用assets/目录下的相对路径，且在orx render时校验每个路径是否存在。曾经有同事想插入一张从网上找的示意图，orx render直接报错：“assets/images/funnel-chart.pngnot found”，逼着他用orx ingest screenshot重新抓取并存档。这看似麻烦，却确保了报告的每一次分发，都是一个自包含、可离线、可验证的证据包。
4. 常见问题与实战避坑指南
4.1 “orx command not found” 的 90% 场景，其实与 CLI 无关
搜索“unable to locate the orx binary”会出来一堆教程教你npm install -g orx或brew install orx，但问题在于：根本不存在官方 orx CLI 包。所有这些报错，根源都是用户误以为 OpenResearch 是一个开箱即用的软件，于是盲目执行网上搜到的安装命令，结果当然找不到二进制。
真实排错路径应该是：
- 确认你是否真的需要 CLI：如果你只是想开始记录研究笔记，直接用 VS Code 打开
research/evidence/目录写 Markdown 即可，orx命令此时纯属干扰项； - 检查
$PATH中是否真有 orx：运行which orx，如果返回空，说明你没安装任何东西，报错是预期行为； - 自查本地脚本：如果你自己写了
orx脚本，确认它在$PATH下（如/usr/local/bin/orx），且有执行权限（chmod +x /usr/local/bin/orx）； - 警惕“伪 orx”：某些第三方工具（如某个叫
open-research-cli的 npm 包）只是借用了名字，其 schema 与社区共识不兼容。我们的建议是：删掉它，用 Bash 重写一个符合你团队 schema 的版本——控制权比便利性重要得多。
我们团队的黄金法则：任何 CLI 工具，如果它的文档里没有明确写出provenance字段的 JSON Schema，就不要用。因为 schema 是 OpenResearch 的宪法，偏离它，整个证据链就失去互操作性。
4.2 Windows 终端里orx --version能运行，但其他命令失败？检查换行符和权限
Windows 用户常遇到这种情况：orx --version显示orx v0.1.0，但orx ingest api https://example.com就报错。原因往往不是脚本问题，而是 Windows 的 CRLF 换行符和 Bash 权限模型冲突。
Bash 脚本第一行#!/bin/bash在 Windows 的 Git Bash 或 WSL 中会被正确识别，但如果脚本是用 Notepad++ 或 VS Code（默认 CRLF）保存的，某些 shell 会把\r\n解释为命令分隔符，导致curl命令末尾多出一个\r，进而使 URL 变成https://example.com\r，HTTP 请求自然失败。
解决方案极其简单：
- 用 VS Code 打开脚本，右下角状态栏点击
CRLF，选择LF； - 或者在终端里运行
dos2unix orx（需先apt install dos2unix）； - 最彻底的方法：在 Git 配置中全局设置
core.autocrlf=input，让 Git 自动把 CRLF 转 LF 提交。
另一个隐形杀手是 Windows 的文件权限。Bash 脚本在 Windows 上默认没有执行权限，即使chmod +x orx也无效。正确做法是：把orx放在 WSL 的 Linux 文件系统里（如/home/username/bin/orx），而不是 Windows 的C:\Users\...路径下。WSL 对 Unix 权限的支持是完整的。
4.3 “local-first” 导致协作困难？用 Git 分支策略破局
最大的质疑是：“所有东西都存本地，团队怎么协作？”答案是：local-first 不排斥协作，它只是把协作的原子单位从‘文件’升级为‘commit’。
我们采用三叉分支模型：
main：只接受 CI 验证通过的 PR，代表已审计、可发布的研究成果；review/xxx：每个研究议题一个分支（如review/payment-fail-analysis），作者在此分支上提交evidence/和links/，CI 自动运行orx verify；draft/xxx：作者本地工作分支，用于草稿、实验、临时数据，不推送，不参与 CI。
关键创新在于orx sync命令：它不只是git push，而是先执行orx verify --strict（检查所有链接有效性），再git push origin review/xxx，最后自动创建 GitHub PR 并 @ 相关 reviewer。Reviewer 收到的不是模糊的“请看这个文档”，而是“review/payment-fail-analysis分支已通过全部证据链验证，请审核evidence/hypothesis-payment-fail-root-cause.md的结论是否被artifacts/user-survey-20240610.json充分支持”。
我们曾用这个流程发现一个经典谬误：一位高级工程师在evidence/里写道“90% 用户反馈加载慢”，但orx verify报错指出：他引用的artifacts/survey-raw.csv里，对应问题的实际回答比例是 62%，且样本量仅 47 人。PR 被自动拒绝，工程师不得不回去重跑统计——这比在会议里口头争论“我觉得是90%”高效得多。
4.4 如何说服团队接受这套流程？从“最小痛苦点”切入
推广 OpenResearch 最大的阻力不是技术，而是习惯。没人愿意为“未来可能有用”的东西，改变现在顺手的工作流。我们的破局点是：找到团队当前最痛、最浪费时间、最易出错的环节，用 OpenResearch 方案直接替换，且第一天就见效。
对我们来说，那个点是“周会材料准备”。以前每周五下午，每个人要花 2 小时整理 PPT，从不同系统导数据、截图、写结论，经常出现“张三说 A 数据是 12%，李四的 PPT 里写的是 15%”的混乱。我们只做了三件事：
- 创建
research/weekly-review/目录； - 写一个 5 行的
orx weekly-ingest脚本，自动拉取 BI 系统本周核心指标 CSV，存为artifacts/weekly-metrics-20240614.csv； - 要求所有人周五上午 10 点前，把本周结论写进
evidence/weekly-conclusion-20240614.md，并声明sources: ["weekly-metrics-20240614.csv"]。
结果第一周就见效：周五上午 11 点，orx render weekly-report自动生成 HTML 报告，所有数据来源清晰标注，结论与数据一一对应。大家发现，准备周会的时间从 2 小时降到 20 分钟，而且再没人质疑数据真实性——因为报告底部写着：“数据来源：artifacts/weekly-metrics-20240614.csv，SHA-256:a1b2c3...，可随时git show查看原始文件”。
从此，OpenResearch 不再是“又要学新东西”，而是“终于不用再手动对数据了”。
5. 生态延展：orx 如何与现有工具链共生，而非取代
5.1 与 VS Code 深度集成：让研究写作变成“所见即证据”
VS Code 是我们 OpenResearch 工作流的主战场。我们没开发专用插件，而是用原生功能组合出强大体验：
- Settings Sync：所有团队成员同步相同的
settings.json，启用"editor.quickSuggestions": {"other": true}和"editor.suggest.snippetsPreventQuickSuggestions": false，让 YAML front matter 的sources:字段能智能提示artifacts/目录下的文件名； - Code Snippets：定义
orx-evidence片段，输入>orx即展开标准 front matter 模板； - Task Runner：配置
tasks.json，把orx ingest、orx verify、orx render都注册为可一键运行的任务，快捷键Ctrl+Shift+P→ “Tasks: Run Task” 即可触发； - Live Server：
orx render生成的 HTML 报告，用 Live Server 插件直接预览，修改evidence/后保存，浏览器自动刷新。
最巧妙的是Outline View的利用：VS Code 的大纲视图会解析 Markdown 的#标题，但我们把它扩展为“证据导航器”。在evidence/文件里，我们约定二级标题## 支持证据下，必须用- [ ]任务列表罗列所有引用的 artifact，如：
## 支持证据 - [x] `artifacts/user-survey-20240610.json` （已验证） - [ ] `artifacts/a-b-test-v2-results.csv` （待验证）VS Code 会自动把[x]渲染为完成状态，[ ]为待办。这让我们一眼看出：这篇分析还有哪些证据没到位。orx verify会检查所有[ ]条目是否真实存在，不存在就报错。这种“视觉化证据状态”的设计，比任何 CLI 命令都直观。
5.2 与飞书/钉钉的“非接入”式协作：用 webhook 做轻量通知
网上有很多“orx 接入飞书”的搜索，但我们的实践是：不接入，只通知。OpenResearch 的核心是本地证据链，强行把orx命令塞进飞书机器人，反而破坏 local-first 原则。
我们用最朴素的方式：在orx sync的最后一步，加一行curl -X POST "https://open.feishu.cn/open-apis/bot/v2/hook/xxx" -H "Content-Type: application/json" -d '{"msg_type":"text","content":{"text":"✅orx sync完成：review/payment-fail-analysis已推送，等待审核"}}'。
注意，这里发送的不是报告内容，而是动作通知。飞书群里看到消息，点击链接直达 GitHub PR 页面，Reviewer 在那里做真正的协作——查git diff、看orx verify日志、评论具体行。飞书只是传声筒，不是证据库。
同样，我们禁止在飞书文档里写研究结论。所有结论必须首发于evidence/目录，飞书里只放一句“详见evidence/hypothesis-payment-fail-root-cause.md”，并附上git show HEAD:evidence/hypothesis-payment-fail-root-cause.md的 raw 链接。这样，飞书就成了证据链的索引卡片，而不是替代品。
5.3 与 Claude / Codex 等 LLM 工具的关系：助手，而非作者
最后必须厘清：Claude、Codex、Gemini 这些工具，在 OpenResearch 里扮演什么角色？答案是：高级计算器，不是研究员。
我们允许在evidence/文件里引用 LLM 的输出，但必须严格遵循三个规则：
- 必须声明来源：在 YAML front matter 中，
sources:字段要写明["llm-claude-3-sonnet-20240615.json"]，且这个 JSON 文件必须由orx ingest llm命令生成，包含完整的 prompt、response、token count、调用时间戳； - 必须人工验证：LLM 输出的任何数据、结论、代码，都必须用本地脚本或手动方式验证。
orx verify会检查：如果sources包含 LLM artifact，则evidence/文件里必须有verified_by: "manual"或verified_by: "script: validate-llm-output.py"字段； - 禁止模糊引用：不能写“根据 AI 分析”，必须写“根据
artifacts/llm-claude-3-sonnet-20240615.json第 3 段输出，经validate-llm-output.py验证，确认其 JSON Schema 符合预期”。
我们曾因此退回一份 PR：一位同事用 Codex 生成了 SQL 查询，直接放进报告，orx verify因缺少verified_by字段而失败。他花 15 分钟写了验证脚本，跑通后 PR 合并——这 15 分钟，避免了未来可能
