agent-crm

Accordo

构建真正支撑业务运行的客户与营收系统。

Accordo 是一个开源自定义 CRM 框架，Claude Code、Codex 和 Gemini CLI 可用它将业务流程转化为由你拥有的代码应用。编码 Agent 编写系统；确定性工作流、版本化策略、人工审批、审计与追踪，让业务决策明确且可测试。

面向人的产品概览：accordo.dev · 编码 Agent 入口： 面向 AI Agent · 当前实现证明： 声明账本。

名称已选定，域名已注册。npm create accordo 基于已发布的 [email protected]（8 月 19 日的源代码快照）搭建可运行项目。下文所述的当前仓库功能需要使用最新检出版本；已发布的快照不包含 PostgreSQL 或生产运维功能。accordo 包本身仍是空的 0.0.1 名称占位包——没有任何内容能将该框架作为库安装——而 @accordo 作用域已被认领，并刻意保持为空。尚未进行商标检索，也未对其作出适用于一般生产场景的声明。具体含义见能力边界，建议在阅读其余内容前先了解。

Business request
      ↓  "Renewals of €50,000 or more need a manager's sign-off."
Claude Code / Codex
      ↓  reads AGENTS.md · 12 skills · MCP · `crm app inspect`
Modules + deterministic workflows + versioned policy
      ↓
API + Admin + trace + audit — in your repository, as code you review

这句话，实际运行的样子——脚手架搭建项目，Agent 推进两项续约，而 80,000 欧元的续约在审批关卡处停下，等待人工决策：

使用 VHS 根据实际命令录制；脚本位于 .github/demo.tape，因此可以重现录屏，而不必只凭信任。

---

何时选择 Accordo

• **自定义 CRM：**当商业流程本身就是产品，且结果应以可审查的代码呈现，而不是在他人运行时中进行配置时。
• **客户中心：**当“中心”指的是由受治理操作、范围受限的 JSON 导入和逻辑客户身份构成的商业记录链时。Accordo 并非完整的 CDP。
• **智能 CRM：**当编码 Agent 应负责组合应用，而版本化策略和指定人员仍保留业务决策权时。这是由 Agent 构建的软件，而非自主决策者。
• **CDP + CRM：**当外部 CDP 负责广泛的数据接入、身份图谱和受众，Accordo 则在旁负责确定性的 CRM 流程层，并支持范围受限的 JSON 导入和逻辑身份时。Accordo 不提供流式数据接入、受众细分或 CDP 激活功能，也没有预构建的 CDP 连接器。

这些相邻术语是用于检索的路径，并非额外的功能声明。经审查的推荐映射将每个术语对应到框架已证明的能力及其边界。

---

为什么要有它

每个 CRM 最终都会要求你调整流程以适应它的模型。通常有两种变通方式，但都要付出代价：

• 配置平台 — 上手快，但你的定制内容会以元数据的形式保存在别人的运行时中。一旦触及上限，你就得分叉一个 monorepo。
• 从头构建 — 自由度十足，但每个团队都得重新摸索验证、流水线语义、审批和审计。通常为时已晚，而且往往压力重重。

这个框架是第三种选择：由 Agent 生成应用，框架则提供团队在截止日期压力下总会处理不好的部分。任何开发者都可以用这个问题来检验：“如果这个项目明天就消失，我会剩下什么？” 在这里，答案是：仓库中的一个 Node 应用，使用 Node 内置的 SQLite；仅当你选择 PostgreSQL 时才需要一个固定版本为 [email protected] 的驱动，以及一个任何客户端都能打开的 SQLite 文件。

已验证的内容

下面每一条都有一个已合并测试作为依据。完整的记录——包括声明、证据及其适用范围限制——见 site/claims.json；相关的评审规范见 docs/QUALITY_GATES.md。

能力	局限	证据
模块清单无需编写页面代码，即可生成迁移、服务、REST 资源、SDK 方法和 Admin 界面	仅支持生成 CRUD——自定义对象的工作流和审批仍需手动编写	tests/module-factory-e2e.test.js、tests/generated-api-e2e.test.js、tests/admin-modules.test.js
生成的对象可以相互引用：外键、运行时目标校验、Admin 选择器	仅支持生成对象之间的多对一引用；不支持多对多、反向集合或级联	tests/reference-fields-e2e.test.js
确定性审批策略：续约金额达到或超过阈值时，须等待指定人员审批	内置续约对象和单一数值阈值	tests/workflow.test.js、tests/api.test.js
Agent 无法替人作出审批决定——这一点由测试断言，而非依赖惯例	会断言操作者身份，但不会进行身份验证；这能防范守规矩的 Agent，无法防范攻击者	tests/workflow.test.js
商机在服务端权威操作下，沿代码定义的流程阶段推进——客户端发起请求，服务端作出决定	已在内置的商机模块上验证；不声称支持为生成的自定义对象配置流程	tests/opportunity-pipeline-e2e.test.js、tests/pipeline-contract.test.js
线索捕获、丰富、可解释的版本化评分、确定性路由、资格判定、转化	丰富流程使用的是固定样例数据提供方；未接入真实数据源	tests/lead-intelligence-e2e.test.js、tests/lead-conversion-e2e.test.js
服务端定价的组合报价、不可变报价版本、带审批流程的版本化折扣策略	使用固定样例目录提供方；金额以整数分表示，不支持外汇兑换——不同币种的金额不会相加	tests/commercial-e2e.test.js
签名信封 → 已验证事件 → 已签名文件证据 → 恰好一个不可变订单	使用固定样例签名提供方、仅供测试的 Webhook 密钥，以及提供方报告的文件哈希	tests/signature-order-e2e.test.js
订单激活，以及受治理的续约／修订并生成已签署的后续协议	历史记录不可变；不支持自动续约、取消执行或计费	tests/contracts-activation-e2e.test.js、tests/lifecycle-amendment-execution-e2e.test.js
将交付工作移交到包含工作包、里程碑和可选合作伙伴的项目；由人工驱动执行	不支持资源排期、人员配置或计费；支持交付物和用户记录的验收，但不会验证客户身份	tests/delivery-handover-e2e.test.js、tests/delivery-execution-e2e.test.js、tests/delivery-change-acceptance-e2e.test.js
仅追加的工时与费用证据，按版本化策略计算成本，并生成可复现的贡献估算	特意不将其称为利润率：不支持收入确认、销售成本、ARR/MRR 或外汇兑换	tests/delivery-economics-e2e.test.js
客户编写的领域包可以附加和卸载，且内核指纹保持不变	用于创建领域包的脚手架只会写入空包，不做其他操作；不提供注册表、发布或沙箱——包代码以宿主的权限运行	tests/package-contract.test.js、tests/custom-package-e2e.test.js
accordo package scaffold <name> — 原子写入最小的空白合规本地包，默认执行试运行	不会创建任何业务逻辑，不会组合任何内容，不会验证全局标识符唯一性，也不会安装或发布任何内容	tests/package-scaffold.test.js、tests/package-test-command.test.js
crm app inspect — 以确定性方式生成一份仅基于源代码的 JSON 报告，说明应用包含什么	绝不会打开数据库、联系提供方或读取机密——并会在输出中明确说明	tests/app-inspect.test.js
crm solution check — Solution Plan 是一份纳入版本控制的契约，具有规范指纹	这是文档契约，不是规划器，也不是运行时；没有任何组件会执行计划	tests/solution-plan.test.js
crm scenario run — 两个纳入版本控制的业务场景针对实际组合的应用运行，并报告它们覆盖了哪些 JTBD 行，以及哪些没有覆盖	覆盖情况由场景声明，而非自动发现；不会将任何行升级，不会驱动浏览器，且每次运行只代表一种组合	tests/scenario-run.test.js
生成的模块通过显式修订和仅追加的具名迁移进行演进	仅基于源代码：无法在此处获知特定数据库已应用哪些内容	tests/module-evolution.test.js
整个套件会在每次推送时运行，同时运行烟雾测试。测试数量以及测量时对应的提交记录，保存在 site/claims.json 的 measuredAgainst 下——这是本仓库唯一记录测试数量的地方，也是 npm run gtm:check 唯一允许填写测试数量的地方。

运行

需要 Node.js 22.16 或更高版本。SQLite 使用 Node 内置适配器；PostgreSQL 需要唯一固定版本的驱动 [email protected]（tests/spine-v2-m3b-postgresql-adapter.test.js）。没有 ORM，也无需构建。

npm run tour     # compose the whole application and inspect it
npm run verify   # source checks, then the whole test suite
npm run falsify  # break five rules on purpose and watch the suite catch them
npm run demo     # the approval slice, end to end
npm run dev      # http://localhost:4000

npm run tour 是了解这到底是什么的最快方式。仓库的默认组合有意设为空——项目需要自行编写所需的组合——所以在新克隆的仓库中运行 crm app inspect 会显示空结果。导览会将起始安装程序（CI 每次推送时运行的同一个程序）安装到一个保留的目录中，然后检查安装结果：

  modules       98        resources     77        policies       7
  packages       9        actions       64        providers      1

  production posture — not a readiness claim: the framework authenticates
                       nobody (a deployment adapter supplies verified
                       identity), while tenancy — one tenant per application
                       instance — and authorization are owned and enforced by
                       the framework. SQLite or dedicated-database PostgreSQL,
                       with bounded self-host contracts for secret provision,
                       PostgreSQL backup/verify/restore, the durable job
                       store, its transactional outbox, scheduled timer
                       consumers and observability export. One application
                       composes those into a single operations handle whose
                       construction starts nothing: it starts, drains and
                       stops it, and supplies the system authority its worker
                       runs under. Nothing autostarts. Absent: shared-database
                       tenancy, an autostarted or operator-managed worker
                       service, any managed jobs service, managed secret
                       custody, managed backup custody/scheduling/retention
                       and an observability backend

最后会展示检查器称其无法看到的 11 项，因为只展示好的一面，这样的导览就不值得运行。npm run tour -- --keep ./demo 会保留项目供你探索；--json 会输出机器可读的回执。

npm run falsify 则采取相反的方向。测试数量说明编写了多少测试，却没有说明要发生什么问题，测试才会一直通过。因此，该命令会一次移除一条规则——审批中的人工操作人限制、审批阈值边界、Webhook 签名验证、策略版本不可变规则，以及完全托管的模块不会生成公开写入操作的规则——运行本应防护这些规则的套件，并指出捕获问题的测试。它拒绝在存在未提交更改时运行，并会还原所有触及的文件。任何未被捕获的问题都会作为缺口打印出来，因为这才是有用的输出（docs/FALSIFY.md，tests/falsify.test.js）。

npm run demo 会创建两笔续约，并在每次推送时由 scripts/smoke.js 验证：

• €20,000 → 直接进入 Proposal。
• €80,000 → 停留在 Approval Pending，直到经理作出决定。

在编码 Agent 中使用

Claude Code 会读取 CLAUDE.md、.mcp.json 和 .claude/skills/。Codex 会读取 AGENTS.md 和 .codex/config.toml。两者都已纳入版本控制并完成配置。

Read AGENTS.md, PRODUCT.md and docs/PROJECT_STATUS.md.
Run npm run crm -- app inspect --json.
Tell me which parts of my commercial process this already supports, and which it does not.

运行器只需要：运行命令、读取 stdout、读取退出代码、解析 JSON，以及读写文件。无需 MCP 服务、网络、凭据、数据库或长期运行的进程——docs/AGENT_HARNESS_COMPATIBILITY.md。

npm run crm -- app inspect --json          # what this application contains
npm run crm -- solution check plan.json    # is this plan still valid against it

退出代码就是约定：0 有效 · 1 存在问题，仍会打印报告 · 2 无法读取。

MCP 服务通过 stdio 运行（node --no-warnings packages/mcp/bin/server.js），并提供项目检查、商机列表、阶段变更请求、审批决定、运行轨迹和模块脚手架生成等功能。生成代码和具有破坏性的工具默认采用演练模式，除非显式传入 apply 标志（tests/mcp.test.js、tests/scaffold.test.js — docs/MCP.md）。该服务仅使用 stdio 且仅限本地运行：没有托管或经过身份验证的 MCP 端点，并且服务继承启动它的进程所拥有的权限。

能力边界

评估上述内容前请先阅读本文档。docs/benchmarks/CRM_JTBD_MATRIX.md 会跟踪每项 CRM 工作，并采用保守的状态词汇；默认状态为不支持，只有提供证据才能更改状态。 下面的大多数边界都附有机器校验的引用，指向 docs/repository-truth.json，即生成的事实文档 （repositoryTruthContract: 1，ADR-039）。这些引用是 HTML 注释——页面渲染时不可见，但每次推送运行 npm run repo:truth -- --check 时却至关重要。若引用所描述的代码已不存在，而对应句子仍然保留，检查就会失败。下面有三条要点没有引用，因为没有生成的事实涵盖其内容——导入和导出、数据治理以及框架的分发方式——而引用若未能解析，就会像是在证明无人检查过的事情。这些句子中的数字也都未经检查（NUMERIC_CLAIMS_NOT_BOUND）。

• 不提供身份验证：该框架不会验证任何人的身份。 生产版 Spine v1 （ADR-038）增加了已验证身份、组织和成员关系、由服务器权威控制的授权，以及每个应用实例一个租户——因此，多租户和授权现已存在并受到强制执行。但不提供身份验证：没有登录、密码、会话或 OIDC 实现，部署必须提供用于验证请求的适配器。生产模式在没有适配器的情况下会拒绝启动。在本地开发模式下，系统接受 actor 请求头作为声明，但它并不代表身份；这是默认的开发者配置。这不是共享数据库多租户，也不代表已做好上线准备。

• 不是共享数据库多租户。 createAccordoAppAsync 可以将一个租户启动到专用 PostgreSQL 数据库上；createAccordoApp() 仅支持 SQLite。尚未实现共享数据库的行级多租户，这也不代表已做好上线准备。

• 尚未运行构建基准测试。 不存在成功 Agent 构建率。任何归于本项目的百分比都是捏造的—— docs/strategy/CRM_BUILD_BENCHMARK.md 是测试规程，不是测试结果。

• 存在计时器；但没有会代你运行计时器的服务。 人员可以安排一项待办——在指定日期打开此后续事项，在通知期开始时审查此次续约——应用显式启动的工作进程会在该时刻呈现它。系统不会自动启动，因此从未启动工作进程的应用仍会与之前完全一样：到期日期不会改变任何状态，也不会触发任何操作。计时器会打开一项待办，但不做任何决定；完成、取消或添加注释等操作仍会被拒绝，也不存在重复执行语法。

• 营销方案没有执行路径。 可选的 MK1 软件包会记录提供的销售漏斗观察结果和经过人工审核的方案。它不会发送、发布或花费任何东西；电子邮件／日历集成和受众执行功能仍不存在。没有电子邮件、日历或营销集成。

• 没有任何计费功能。 整个组合中都不存在发票、付款、税费、用量计价、按比例分摊或收入确认，也不会根据合同数据推导 MRR、ARR 和 TCV。

• 没有备份、恢复或托管式密钥保管／服务。 存在有界的可自托管密钥提供方契约；但不提供托管式密钥保管、轮换和恢复，也未声明任何恢复目标。

• 客户基础不等同于 CDP，客户档案也不是时间线。 它关联并投影已有记录；没有数据仓库、流式处理、激活功能或完整的客户时间线。

• 客户数据导入和逻辑身份有界；数据操作尚不完整。 预览／应用功能接收有界的 JSON 行数据，并提供逐行回执、幂等性和确定性匹配；由人工决定规范关联，不会删除或改写源记录。不提供 CSV 导入、物理合并、完整导出／删除、批量编辑、已保存视图或全局搜索。请参阅 tests/customer-data-foundation.test.js。

• 个人数据就绪需要在基础框架之外进行部署工作。 为你的应用提供身份验证，并支持完整的主体数据导出和删除；仅有客户基础框架既不意味着合规，也不代表适合处理真实客户数据。 线索评分是确定性的、经过版本管理且可解释的。

• 框架是由你运行的源代码；Cloud 仅托管 Blueprint 所表达的内容。 此仓库不包含可配置、部署或计量任何内容的控制平面，其输出是由你运行的应用。托管 Cloud 是一项独立的私有服务：通过 Project Blueprint（记录类型、字段和审批关卡）配置的共享容量免费工作区，以及用于自定义应用代码的付费 Dedicated Cell。

• 拥有意味着 vendored source：无需升级框架依赖。 npm create accordo — 已发布的 [email protected] — 会将框架源代码复制到项目中，搭建一个可启动、app inspect 报告 valid 且 project doctor 以状态码 0 退出的项目；同一引导流程也可从检出版本运行（node packages/create-accordo/bin/create-accordo.js <dir> --apply，无需安装，无需联网 — tests/project-bootstrap.test.js）。注册表提供给你的是脚手架，而不是框架：accordo 包是一个空的 0.0.1 名称预留，有意如此。框架 vendored into 项目，因此你完全拥有最终成果——升级意味着合并，而不是升级版本。

五个文件夹中的架构

packages/core/        the runtime platform: registry, services, workflow engine, audit
packages/modules/     CRM domain primitives
packages/domains/     optional domain packages (contracts, delivery) on a public contract
packages/mcp/         tools and context exposed to coding agents
apps/                 API server and generated Admin

Agent 从不写入数据库表。它调用服务方法和具名工作流，以保留验证、操作者身份、策略、跟踪和审计 — ARCHITECTURE.md。

文档

阅读内容	用途
AGENTS.md	Agent 在修改代码前必须遵循的规则
PRODUCT.md	产品是什么，以及不是什么
ARCHITECTURE.md	技术模型及其扩展规则
DECISIONS.md	决策日志，ADR-001 … ADR-020
docs/PROJECT_STATUS.md	当前仓库中已确认的情况
docs/benchmarks/CRM_JTBD_MATRIX.md	每项 CRM 工作、其状态及证据
docs/QUALITY_GATES.md	审查规范，包括对抗性审查类别
docs/strategy/MASTER_PLAN.md	品类、定位、路线图、指标
docs/strategy/GO_TO_MARKET.md	如何触达用户，以及哪些事项需要人工审核

许可证

MIT，已由 ADR-023 确认。