emollick/concord

# Concord **对定性文本的仪器级测量。几分钟内开始探索，以可靠的统计数据发布。** Concord 能够将开放式文本——调查问卷回复、访谈记录、客服工单、实地笔记——转化为经得起检验的数据。它有两个档位。第一档是快速的：导入文件，几分钟内你就能获得语料库的“即时阅读”、一份由 Director 编写并锚定真实引文的简报，以及关键主题的探索性计数。第二档是刻意放缓的：将概念转化为正式的 codebook 条目，codebook 被编译为评判工具（词典、LLM 评判器、多模型评审组），工具根据人工标注的金标样本进行校准，并且每个发布的估算值都通过基于设计的统计方法（DSL/PPI）对机器误差进行了修正——因此，即使一个模型在 10% 的情况下出错，依然能产生带有可靠置信区间的无偏数值。 连接这两个档位的核心是**证据阶梯**。Concord 中的每一个数值都带有一个标记，准确地告诉你它获得了多少认可度：◌ 探索性（可编译并运行），◑ 已稳定（在多次运行中保持一致，且通过了初级校准），● 已校准（在专门设计的金标样本上与人类判断一致，并冻结带有证书），◉ 已修正（估算值本身已根据金标样本进行偏差校正，并存储了包含概率）。这些级别从不会阻挡你——它们只是如实地给你打上标签。探索是廉价的，并且诚实地表明它只是探索；发布是昂贵的，并且明确表明这份花费买到了什么。 而且**每一个数值都是一扇门**。点击任何计数、条形、单元格或系数，证据检查器就会打开：背后的逐字单元、触发的词典词条、每个模型的推理过程、存在时的人类金标标签，以及所有这些的来源。在底层，每个操作都会追加到哈希链账本中，研究方法部分会自动生成并附带指向该账本的引用，只需点击一下即可导出复制归档，其包含的 R 和 Python 脚本能在 Concord 外部重现每个修正后的估算值。 ## 快速开始（无需 API 密钥） 前置条件：你的 PATH 中需要安装 **Node.js 20.10 或更高版本**（`node --version`）。 1. **Windows：双击 `start.bat`**（首次运行会安装依赖项——纯 JavaScript，无需编译）。你的浏览器会打开 `http://localhost:7341`。**Mac/Linux：** 运行 `npm install` 然后 `npm start`，并自行打开 `http://localhost:7341`。 2. **创建一个项目**（名称任意；隐私模式 "no-training" 是不错的默认选项），然后将 `demo/techcorp-exit-survey.csv` **拖拽**到任意位置——包含 2,500 条合成的离职调查回复。 3. 确认建议的映射（`response` 列会被自动检测为文本）。垃圾队列会标记出预设的无效回复、重复项以及一次包含 7 条记录的机器人刷屏。 4. 观察**即时阅读**（全本地运行：长度直方图、语言混合、高频词汇——"pay" 就在其中、情感草图、元数据边缘分布）。 5. **选择一个 Director**：通过侧边栏的 *Project → Settings*（或 Brief 按钮下方的链接）→ Director 的槽位 → 无需密钥的演示：提供商选择 **mock** → 保存。 6. 请求**语料库简报**并观察其流式生成：候选主题，每一个都锚定到真实的引文。点击引文——那就是检查器。 7. 从那里开始，整个阶梯都敞开了：接受概念、编译工具、初级调优、运行语料库、抽取金标样本、在 Calibration Studio 中进行标注、冻结证书，并观察“修正揭晓”将修正后的估算值展示在原始估算值旁边。 **“Mock”的含义：** 无需密钥，Concord 运行在 **MockModel** 上——这是一个确定性的、零成本（$0）的本地假模型，它了解演示语料库中预设的主题，并能模拟一个准确率约为 90% 的评判器，生成看似合理的推理过程。它的存在是为了让整个产品（包括需要易错评判器的校准和修正功能）在你输入任何密钥之前就能端到端地运行。它始终被标记为 "Mock"——无论是在 UI 中、运行记录中，还是在自动生成的研究方法文本中。它从不假装自己是科学研究；它展示的是让科学研究成为可能的底层机制。 ## 添加真实模型 打开**设置**（通过路径 `#/settings`，或侧边栏的 *Project → Settings*），并为以下任意一项粘贴密钥： - **Anthropic** —— Claude 模型，通过 tool-use 实现模式控制。 - **OpenAI** —— GPT 模型，原生 JSON-schema 输出。 - **OpenRouter** —— 一个密钥即可访问长尾模型（Gemini, Mistral, Llama 等）；每次调用都会记录提供服务的提供商。 - **Ollama** —— 本地模型，在 `localhost:11434` 处自动发现；零成本（$0），且数据绝不开源本机。 密钥保存在 `config/keys.json` 中——已被 gitignore 忽略，位于每个项目打包文件之外，绝不包含在导出文件中。然后在“设置”中选择一个** Director **模型（你拥有的最强大的模型；它负责撰写简报、起草 codebook、编译评判器提示词，并对上报的单元提供二次意见）。 **隐私模式**（在适配器层强制执行，而非 UI 层）： - **Open** —— 任何已配置的后端都可以查看单元文本。适用于没有保密性限制的数据。 - **No-training** —— 仅限具有合同规定不进行训练承诺的后端（Anthropic, OpenAI）以及本地模型；其他任何情况都需要说明理由，并记录在账本中。 - **Strict** —— 网络适配器在整个应用范围内被禁用；所有内容（包括 Director）必须在本地模型上运行，并且产品会明确告知其简化后的工作流程。 ## 演示语料库 `demo/techcorp-exit-survey.csv` 是**合成的且完全由种子生成**（使用 mulberry32，种子为 7341 —— 运行 `node demo/generate.js` 可逐字节重现）。包含 2,500 条带有元数据（部门、任期、职位、地区、离职日期、满意度 1–5）的离职调查开放式回复，以及六个预设主题并带有内置相关性，以便交叉表能顺利生成： | theme | base rate | planted correlation | |---|---|---| | pay | 0.28 | ↑ Sales (≈0.39), ↓ satisfaction | | management | 0.22 | ↑ Operations | | workload / burnout | 0.25 | ↑ tenure < 2 years | | growth | 0.18 | ↑ IC role | | remote policy | 0.12 | ↑ NA/EMEA | | quit regret | 0.06 | flat, rare | 当满意度 ≤ 2 时，通常会触发离职意图的语言。此外还有逼真的“垃圾”数据：约 2% 的无效回复（"n/a", "asdf", "."），约 1% 的完全重复项，一次 7 条记录的机器人刷屏，约 3% 的西班牙语回复。`demo/oracle.json` 记录了每行的确切真实情况——这就是 MockModel 的 oracle 读取的内容，也是 E2E 测试套件用来检查修正后估算值的基准。 ## 仓库结构 | path | what lives there | |---|---| | `start.bat` | 双击启动器（首次运行时安装依赖项，并打开浏览器） | | `server/` | Node 22 ESM 服务器 —— 无框架，无构建步骤 | | `server/core/` | 项目打包、哈希链账本、对象模型、缓存、ids | | `server/ingest/` | CSV/XLSX/DOCX/PDF/VTT 解析器、列映射、单元化、无效数据及 PII 扫描 | | `server/providers/` | Anthropic / OpenAI / OpenRouter / Ollama / Mock 适配器、隐私控制门、成本计量 | | `server/instruments/` | 词典引擎、LLM 评判器、模型评审组、稳定性检查 | | `server/director/` | Director：简报、概念起草、提示词编译器、初级调优、问题栏 | | `server/runs/` | 运行引擎（检查点/恢复、预算上限、上报）+ 实时监控器 | | `server/stats/` | 一致性（κ, α, AC1）、bootstrap、DSL/PPI 修正、OLS/logit —— 纯 JS 实现，经过黄金数值验证 | | `server/reporting/` | 研究方法生成器（引用账本）、复制归档、报告 HTML | | `server/lexicons/` | 内置词典（VADER MIT；原创 CC0 起始词典） | | `app/` | 浏览器 UI —— 原生 ES 模块、手工编写的 SVG 图表 | | `demo/` | 设定种子的语料库生成器 + 提交的 CSV + 预设真实的 oracle | | `tests/` | 单元、集成、模拟和 e2e 测试套件（`node --test`） | | `docs/plans/` | 设计文档和实施计划 | ## 运行测试 ``` npm test # everything node --test tests/e2e/pipeline.test.js # the release gate: full pipeline, keyless, ~30s node --test tests/e2e/perf.test.js # performance budgets (10k import, instant read, engine run) node --test tests/sim/dsl.sim.test.js # Monte-Carlo validation of the DSL correction ``` e2e 流水线完全像 UI 那样通过 HTTP 驱动真实的服务器：导入 → 即时阅读 → 简报 → 构建概念 → 编译 → 初级调优 → 完整运行 → 抽取金标样本 → 盲法双重标注 → 优先确认人类一致性 → 裁决 → 冻结 → DSL 修正后的交叉表 → 研究方法及复制归档导出 → 账本验证。 ## v1 版本中不包含的内容 坦诚的清单，并附带了每项偏差的文档记录位置（设计文档 §2，`docs/plans/2026-06-05-concord-v1-design.md`）： - **无本地 Whisper。** 记录文件以 VTT/SRT/JSON 格式导入；音频转录可以在日后通过任何兼容 OpenAI 的本地端点进行附加。 - **无端到端加密中继。** 项目打包文件是普通的便携文件夹——通过共享驱动器分享；盲法标注员会话是从 Calibration Studio 启动的受限监听器，绝不是第二个服务器。 - ~~PII 伪匿名化功能已构建，但尚未接入导入流程。~~ 自 2026-06-06 起已接入：导入确认环节接收 `pii: "off" | "scan" | "pseudonymize"` 参数（默认为 scan）。扫描和掩码覆盖了单元文本以及字符串元数据值（相同的可逆保险库，相同的 `[EMAIL_1]` 格式 token）；保险库存放在 `projects//vault/.json` 中，并且被排除在所有复制归档之外。重新单元化时，会在派生语料库上重新运行源语料库的 PII 模式。 - **无 OS 密钥链。** 密钥存放在 `config/keys.json` 中（被 gitignore 忽略，位于打包文件和归档之外）。 - **无 SQLite/DuckDB。** 使用 NDJSON/JSON 打包文件，支持原子写入和只追加的账本 —— 可流畅处理至约 10 万个单元，而非 100 万个。 - **无内嵌 Python。** 统计分析采用纯 JS 实现，通过与手工推导的黄金数值和种子模拟进行对比验证；复制归档会生成 R + Python 脚本，可在 Concord 外部重现每个修正过的数值。 - **预测因子侧的测量误差修正**目前以文档形式提供，而非计算功能：v1 版本修正结果侧；预测因子侧的呈现会附带建议。 ## License MIT License

标签：AI代码标注, AI风险缓解, MITM代理, Petitpotam, 学术研究工具, 数据溯源, 数据科学, 文本分析, 统计分析, 自定义脚本, 资源验证