Concord

Concord

一个用于共同设计数据标准的原型平台，为 ODI 标准中心打造。每项标准都是严格的 OWL 2 本体，始终保持逻辑一致并符合 FAIR 原则；从初次讨论到正式发布的整个生命周期均以异步方式运行，并在每个步骤提供 AI 协助。

• 通过三种方式收集需求。 AI 访谈助手会按照结构化用例开展访谈，并询问能力问题及示例答案。你可以上传 Google Meet 转录文本，也可以邀请协作主持机器人加入实时通话，像邀请其他来宾一样通过电子邮件发送邀请；如果需要，它还可以在 Meet 聊天中提出澄清问题。Claude Code 和 Codex 等编码 Agent 可通过 MCP 连接、读取本体，并报告缺失或不合适的概念。
• 将需求转化为变更。 系统会根据用例综合生成变更请求，其中包含结构化编辑，以及针对每个能力问题的 SPARQL 测试。模型不会直接编写 RDF：它只提出术语，再由服务编译为经过验证的编辑操作。
• 在阅读术语的地方编辑。 Browse 中的每个术语旁边都有“编辑”按钮，可修改标签、定义、注释、替代标签、示例和编辑备注，旁边还有“报告问题”按钮。编辑会成为一项编辑性变更请求（一个 updateAnnotations 编辑），因此会像其他变更一样进行分类、验证和审批；在合并之前，不会有任何内容进入工作草稿。编辑会记录修改前的值，因此如果另一项针对同一字段的变更先行合并，它会退回给原作者，而不会覆盖已有内容；修改定义措辞时，系统还会询问含义是否保持不变（含义发生变化的修改会作为重大变更审查）。
• 无需开会即可治理。 每项变更都会根据明确规则分类为补丁、次要或重大变更（依据 OWL 版本管理实践和 gist 的语义化版本控制方法），然后进行验证（严格 lint、使用 sparq 进行 OWL 2 DL 推理、FAIR 检查、能力问题），再按照本体治理政策进行审查。政策可从五种模板的下拉菜单中选择（负责人主导、懒共识、W3C 工作组、成员投票、ODI 托管），并可调整：签字批准人数和角色、审查期限、带法定人数和门槛的投票、否决权、ODI 权限、所有权与转让，以及自动化内容。
• 规范地发布。 发布版本会采用其变更的最高级别、递增语义版本号、设置 owl:versionIRI、owl:priorVersion 和 owl:backwardCompatibleWith 或 owl:incompatibleWith，并包含所有格式，以及适用于重大版本的 SPARQL 迁移脚本。每个本体都是一个 git 仓库（每个发布版本都有一个标签），配置完成后会在发布时推送到 GitHub。
• 使用提议的变更测试真实应用。 基于本体构建应用的人员可以连接自己的应用；GitHub Action 会针对每个待处理变更请求将产生的本体版本测试应用，并反馈结果，让每项变更都会显示可能造成的影响。开启自动驾驶后，只要应用测试通过，Concord 就会代表应用所有者批准变更或投赞成票，因此变更不会因等待他们而搁置。
• 本体地址本身即可阅读。 本体 IRI 和每个版本 IRI 都会解析为公开页面，页面样式参考 W3C 和 Widoco 词汇文档：包含元数据、每个术语的参考条目（以其 IRI 片段作为锚点）、该版本背后的用例和需求、发布说明，以及所有序列化格式。RDF 客户端可通过内容协商从同一地址获取 Turtle、JSON-LD、RDF/XML 或 N-Triples，也可使用扩展名（/def/<slug>/<version>.ttl）获取。每次发布时，页面还会作为 index.html 写入发布内容，并生成 w3id.org 重定向规则以支持持久化 IRI。
• 根据本体验证数据。 在本体的 验证数据 页面粘贴或上传 RDF，也可以向本体或版本地址发送 POST 请求（curl -X POST https://<site>/def/<slug>/<version> -H 'Content-Type: text/turtle' --data-binary @data.ttl）。系统会根据该版本派生的 SHACL 形状和其定义的术语检查数据，并返回 JSON 报告；如果设置 Accept: text/turtle，则返回 SHACL sh:ValidationReport（列出前 1,000 条结果；汇总计数涵盖所有结果）。支持 Turtle、JSON-LD、N-Triples、N-Quads、TriG 和 RDF/XML，数据大小最多为 5 MB（JSON-LD 为 2 MB），不同三元组最多 25,000 个（IRI 和字面量总计最多 800 万个字符，其中 IRI 最长 4,096 个字符）；每个客户端最多同时处理两个请求，每分钟最多 30 个请求。使用 SHACL 配置文件时，形状本身也可从同一地址获取（Accept-Profile: <http://www.w3.org/ns/shacl#> 或 ?_profile=shacl）。Agent 也可通过 MCP validate_data 工具执行相同的检查。
• 在浏览器中查询。 Query 选项卡会将本体加载到 sparq 中；它是一个编译为 WebAssembly 的 SPARQL 引擎，可运行 SPARQL，并检查实例数据是否符合本体的 SHACL 形状，无需往返服务器。
• 不止于阅读，还能直观查看。 Browse 选项卡提供无障碍类树、schema.org 风格的属性表、UML 风格的类图（包括属性、带基数的关系和子类）以及网络图。请参阅本体可视化。
• 按你的方式查看。 支持 Turtle、LinkML、JSON-LD、RDF/XML、N-Triples、Manchester 语法和 SHACL 形状，也支持可读性更强的 SHACL 紧凑语法（SHACLC）。
• 立即在代码中使用。 每个 SHACL 形状也会生成为 JavaScript 类，并通过 ODI SHACL converter 和 @rdfjs/wrapper 生成。应用可从本体自身地址导入这些类（import { VolunteeringDataset } from "https://…/def/volunteering/1.0.0.js"，或使用 Accept: text/javascript），从 .d.ts 获取类型，或运行 npm install https://…/def/volunteering/1.0.0.tgz 安装。所有版本和分支使用相同的包名，因此将应用从分支迁移到发布版本时，只需更改该 URL。
• 身份和私有数据。 使用 Google 或 GitHub 登录。系统会自动创建 WebID 和 Solid pod；访谈转录文本等私有材料存储在 pod 中，只有结构化的公开内容会被共享。
• 内置 Alpha 测试。 /alpha 会引导测试者以所选角色体验平台，并在模拟工作组的陪伴下进行；/feedback 则是支持语音的反馈聊天，提供引导式和开放式两种路径。

运行

需要 Node 22.13+ 和 pnpm 10。Git 必须位于 PATH 中。

pnpm install
pnpm dev            # API on :8787, web app on :5173

打开 http://localhost:5173/alpha。未进行任何配置时，应用完全离线运行：AI 步骤使用确定性回退方案，私有数据存储在本地磁盘上，并通过演示账户登录。

OWL 2 DL 推理（一致性、不可满足类、推断出的层级）由编译为 WebAssembly 的 sparq 执行，服务器（在工作线程中）和浏览器（在 Web Worker 中）使用的是同一份代码，因此无需额外安装任何内容。sparq 可以判定大多数 OWL 2 DL 问题。如果它无法判定某个本体，或超出步骤预算，就会明确说明；在能够判定之前，验证不会通过。./toolkit/setup.sh 只会安装 LinkML，核心测试中有一项会用到它。

要使用 Claude，请设置 ANTHROPIC_API_KEY（所有设置请参阅 .env.example）。默认模型为 claude-opus-5-5。

Docker

cp .env.example .env
docker compose up --build   # Concord on :8787, Community Solid Server on :3000

部署（Vercel 和 Azure）

Web 应用由 Vercel 提供服务。所有需要长期运行的服务（API、登录、MCP 端点、实时会议流、治理时钟、Solid 服务）都运行在一台小型 Azure VM 上，该 VM 由 deploy/azure/deploy.sh 启动，符合 Azure for Students 的免费层级要求（另保留了 AWS 模板作为替代方案）。Vercel 会将 /api、/auth、/mcp、/people 以及 MCP 客户端的 OAuth 端点转发到该 VM，因此用户始终只会看到 Vercel 链接。GitHub Actions 会测试每次推送并构建后端镜像；服务器会在五分钟内获取新镜像。分步说明：docs/deploy.md。

连接编码 Agent

在任意 Concord 站点打开 /connect，即可查看安装按钮。简而言之，只需 URL：

claude mcp add --transport http concord https://standards-concord.vercel.app/mcp   # Claude Code, then /mcp → Authenticate
codex mcp add concord --url https://standards-concord.vercel.app/mcp && codex mcp login concord

在 Claude（网页、桌面、移动端，以及使用 Claude 账户登录时的 Claude Code）中，Add to Claude 按钮会打开预先填好的自定义连接器对话框。ChatGPT 的连接方式相同，使用 OAuth 将其配置为自定义 MCP 服务（页面上提供了操作步骤）。首次连接时会打开浏览器，用户登录 Concord 并点击 Allow：MCP 端点实现了 MCP authorization spec（带 PKCE 的 OAuth 2.1、受保护资源元数据、动态客户端注册和客户端 ID 元数据文档），因此无需复制令牌。个人令牌（位于同一 Connect an agent 页面中已连接 Agent 列表下方）仍可供 CI 等无头 Agent 使用。

此仓库也是 Claude Code（/plugin marketplace add standards-concord/standards-concord）和 Codex（codex plugin marketplace add standards-concord/standards-concord）的插件市场，server.json 则是其 MCP Registry 条目。Concord 更换域名时，运行 node scripts/public-url.mjs https://<new-origin> 并合并：这会更新所有列表并重新发布注册表条目。网站本身无需更改：它显示的所有 URL 和 OAuth 端点都根据其访问地址生成（在 Vercel 和后端设置 CONCORD_PROXY_SECRET，让后端信任转发的地址；请参阅 docs/deploy.md）。已安装的插件会在更新后跟随变更，Agent 则会在新地址重新登录，因此旧地址需继续运行一段时间。列表详情及各项内容的提交位置：docs/mcp-listings.md。

开发分支

如果标准中还没有你需要的术语？创建一个分支，添加术语，并在审核变更期间继续开发。分支是本体的预发布版本：

• 它可通过 https://<host>/def/<ontology>/forks/<fork> 访问（内容协商，除非客户端请求 HTML，否则返回 Turtle；也可通过扩展名指定：.ttl、.jsonld、.owl、.nt、.omn、.linkml.yaml、.shacl.ttl），因此应用可以直接导入。它始终提供分支的最新修订版，并开放 CORS。
• 新术语沿用标准的命名空间（vol:VolunteeringActivity，而非分支专属 IRI），因此基于分支编写的数据在术语合并后仍然有效。要切回主本体，只需更改导入 URL。
• 它会标记为预发布版本：owl:versionIRI 是分支的 URL，owl:versionInfo 类似 1.0.0-fork.volunteer-hours.2，owl:priorVersion 则是它所基于的版本。
• 提交分支提案时，会将其中所有编辑一并纳入一个变更请求，并按照本体的常规治理流程处理。后续编辑后再次提交，将更新该请求。
• 每个分支都是本体仓库中的一个 git 分支 forks/<fork>；它不会触碰 main。对分支的每次变更（包括关闭）都会通过比较并交换来移动分支，并根据分支记录的版本进行原子条件写入保存；如果保存失败，则会撤销提交。
• 变更是否已合并，完全依据内容判断，具体有三种情况：对于分支涉及的每个术语，Concord 都会比较分支基准、分支、工作草稿和最新发布版本中的内容（忽略 dcterms:created 等来源信息）。只有上游内容与分支完全一致时，术语才算已合并或已发布；因此，审核期间重命名或改写的术语绝不会触发迁移。
• 同步会将分支更新到最新草稿，并仅重放尚未合并的编辑。如果上游更改了分支也更改过的术语（直接更改，或因某项变更影响到上游新增术语，例如删除操作），或者结果会导致不一致，则不会进行任何更改，并会列出冲突；如要采用上游版本，请放弃分支对此术语的更改，然后同步，并在需要时重新进行更改。
• 分支编辑会使用 HermiT 进行一致性检查。启用 CONCORD_REQUIRE_REASONER 时（NODE_ENV=production 时默认启用），如果推理器无法运行，则会拒绝分支变更，而不会仅进行结构检查。
• 迁移计划会指向 /def/<ontology>/<version>（或 /def/<ontology>/draft），并支持相同的扩展名。对于未请求 RDF 的客户端，版本 IRI 会返回 HTML 页面，因此未设置 Accept 标头的代码应改用 .ttl URL；计划中也会说明这一点。

在 hub 中，分支位于 Changes → Forks。通过 MCP 可使用：create_fork、edit_fork、propose_fork、check_forks、sync_fork、discard_fork_changes、list_forks、get_fork 和 close_fork。系统会指示 Agent 在每次开发会话开始时调用 check_forks：它会说明应继续使用分支、同步分支、解决冲突，还是切换到草稿或发布版本，并提供需要替换的导入 URL。

针对提议的变更测试应用

在任一本体的 Changes → App checks 中连接应用，然后将 Concord app check action 添加到应用的 CI 中。结果会显示在每个变更请求上；当你的应用通过检查时，autopilot 可以代你批准或投票。

可选服务

功能	配置
使用 Google / GitHub 登录	GOOGLE_CLIENT_ID/SECRET、GITHUB_CLIENT_ID/SECRET
用于私有数据的 Solid pods	SOLID_SERVER_URL（Community Solid Server v7+）
Google Meet 实时机器人	RECALL_API_KEY（Recall.ai）。Google Meet Media API 仍处于封闭预览阶段。添加 MEET_BOT_EMAIL 和 MEET_BOT_ICS_URL，这样邀请机器人的地址加入通话（或定期系列通话）时，机器人就会加入：docs/meet-bot.md。
将版本发布到 GitHub	GITHUB_PUBLISH_TOKEN，并在本体上设置仓库
选择公开反馈摘要为 GitHub issues	FEEDBACK_GITHUB_TOKEN（Issues：读取和写入）。请参阅 docs/feedback-issues.md
在 Firefox 上使用语音输入	STT_PROVIDER=openai、OPENAI_API_KEY

目录结构

packages/core     OWL engine: parsing, edit operations, diff, change classification, versioning,
                  lint, FAIR checks, reasoners, competency-question tests, LinkML/Manchester/SHACL
packages/shared   Domain types and the HTTP API contract
apps/server       Express API, MCP endpoint, governance engine, AI prompts, Solid, meeting bot
apps/web          React app
toolkit           Python virtualenv with LinkML, used by tests
docs              Research, the alpha walkthrough script and questions for ODI colleagues

测试

pnpm test            # unit and API tests
pnpm test:e2e        # browser tests (Playwright): the alpha walkthrough and every page
pnpm test:e2e:live   # read-only smoke tests against the deployed site (LIVE_URL)

浏览器测试会启动自己的 API 服务（端口 8797，使用临时数据目录）和 Web 应用（端口 5183），因此不会影响正在运行的 pnpm dev。设置 E2E_MODE=preview，即可测试生产构建，而不是开发服务器；请先运行 pnpm --filter @concord/web build。CI 会在每次推送时运行这两种模式，并在每次 Vercel 生产部署后运行实时测试。新增测试用例时，请使用 e2e/fixtures.ts 中的 test，并将文件命名为 e2e/<feature>.spec.ts：如果页面记录了控制台错误或发生崩溃，它会使测试失败。

每项功能都配有 Playwright 测试，而且每个错误修复都配有能重现该错误的 Playwright 测试，以防问题再次出现。docs/e2e-coverage.md 列出了每个页面、角色和流程对应的测试用例。更多信息请参阅 CLAUDE.md。

文档

• Alpha 版使用指南
• 带讲解的演示视频：运行 pnpm walkthrough，即可根据可编辑脚本录制视频
• 向 ODI 同事提出的问题
• 研究：本体实践、需求、版本管理和治理、本体的可视化视图、技术选项、ODI 操作手册