Atlas CLI

首次使用：读取可见客户

准备：下载的 CLI 或源码构建、测试环境账户、包含 crm:read 的委托令牌，以及一个你有权访问的客户 ID。下载位置和旧版限制见 安装。

1. 按照下方 快速开始 安装并核对版本，然后设置测试环境 URL 和令牌。
2. 运行 atlas profile read <customer-id>；若直接运行解压目录中的文件，使用 ./atlas。将占位符替换为有权访问的客户 ID。
3. 查看 JSON 中的 status、request_id 和 data，再与网页中的客户档案核对。

预期结果：读取成功返回 status: completed 和客户档案数据；本次读取不会创建或修改客户。

如果失败，先运行 atlas auth status 和 atlas config get base-url，再按 故障排查 检查权限及错误。接下来查看 命令参考 或学习 提案确认。

快速开始

shasum -a 256 -c SHA256SUMS
tar -xzf atlas-cli-<tag>-darwin-arm64.tar.gz
./atlas version
./atlas config set base-url https://atlas.staging.forth.ai
./atlas auth login
./atlas profile read <customer-id>
./atlas library search "warranty terms" --limit 5

atlas version 会打印发布标签与源码 SHA。两者都必须与同一发布版本的 manifest.json 一致。

发布状态

• MCP 服务器：已在 staging 就绪。它发布了八十四个受治理的工具；参见 MCP 服务器指南。
• MCP 服务器：已在 staging 就绪。它发布了一百零八个受治理的工具；参见 MCP 服务器指南。
• CLI 源码：已在当前 staging 源码中就绪。下方参考文档中的每条命令都存在于当前源码中。
• 可下载的 CLI：atlas-cli-v0.1.0-staging.3。此归档包早于客户搜索与客户创建功能。如需使用 atlas customer search 与 atlas customer create …，请从源码构建，或等待下一个归档包发布。
• 生产环境：本次更新未涉及。请将 CLI 指向 https://atlas.staging.forth.ai。

Auth 发布操作员：仓库内命令 bun scripts/auth-authority-release.ts deploy|status|resume|recover --env staging|production --operation UUID 登记尚未用于准入的 Auth 配置代次。写操作要求 --expected-generation N --candidate-sha SHA；恢复还要求 --replace-operation UUID --expected-deployment-id UUID --expected-version-id UUID。必须具备已有 Cloudflare 权限、准确发布分支及 staging 预留。迁移前置条件和保持关闭的恢复规则见仓库 agent lifecycle。此命令不授予租户 CLI 权限，也不表示制度准入已启用或已发布到生产。

预发布运维：bun --env-file=/dev/null scripts/staging-migration-readiness.ts SERVICE 仅通过只读 SELECT 查询，检查所选服务配置中归该服务所有的预发布迁移记录。它不会初始化缺失的记录表，也不会执行迁移。读取失败或结果无法验证时会阻止发布，且不能通过待迁移例外放行。已确认的待迁移项仍须遵循既有审核流程。此检查不会授予权限，也不代表部署成功。

安装

私有 GitHub Release 中包含 atlas-cli-<tag>-darwin-arm64.tar.gz、atlas-cli-<tag>-darwin-x64.tar.gz、manifest.json 以及 SHA256SUMS。

1. 将适用于你 Mac 机型的归档包与 SHA256SUMS 下载到同一目录。
2. 运行 shasum -a 256 -c SHA256SUMS。如果有任何一行不是 OK，立即停止；删除文件后重新下载。
3. 解压归档包，将 atlas 移动到 PATH 中一个仅你自己可写的目录下。
4. 运行 atlas version，将标签与源码 SHA 与 manifest.json 对比。

归档包不支持 Linux 与 Windows。在这些平台上，请从源码运行，并通过 ATLAS_ACCESS_TOKEN 传入令牌。

配置

atlas config set base-url https://atlas.staging.forth.ai
atlas config get base-url
atlas auth login      # 提示输入令牌（不回显），并存入 macOS Keychain
atlas auth status     # 显示当前生效的令牌来源，但绝不显示令牌本身
atlas auth logout

在 Atlas 门户中生成令牌；MCP 指南展示了具体请求方式。远程 base URL 必须使用 HTTPS，仅本机回环地址允许使用 HTTP。

命令参考

尖括号中的参数为必填项。下方每条命令都会向已配置的 base URL 发送一次 REST 请求，并以 JSON 形式打印响应信封（response envelope）。

atlas team inspect 与 atlas external call 并非使用已分类外部工具的唯一途径：雇员自己的运行——无论是通过 atlas team propose 在此触发，还是事后通过 atlas team inspect 查看——都会按 REST 手册「雇员运行期间使用外部工具」所述的同一套权限级别规则，调用其角色已启用的已分类 read 工具，并受共用的 maxExternalReadCalls 上限约束；已分类的 effect 工具在任何权限级别下（包括 auto_pilot）都不会被运行直接调用。

例如：atlas releases list --kind policy --limit 20、atlas releases search "报价" --cursor "…" 和 atlas releases read mrel_1。--pretty 只会缩进同一个 atlas.action.v1 信封。缺少 scope 或令牌被吊销时，返回服务端的 forbidden 信封和退出码 3；上游不可用时返回失败信封，不会伪装成空结果。

# 成功：逐字保留所有 citation、release 字段和 next_cursor
atlas releases list --kind policy --pretty

# 已授权组织没有当前发布版本
{"schema_version":"atlas.action.v1","action":"ekb.releases.list","status":"completed","data":{"items":[],"next_cursor":null}}

# 缺少 scope 或令牌已吊销：退出码 3，绝不伪装成空的 completed 结果
{"schema_version":"atlas.action.v1","action":"ekb.releases.list","status":"forbidden","error":{"code":"insufficient_scope"}}

# 上游不可用：保留失败信封及重试惯例
{"schema_version":"atlas.action.v1","action":"ekb.releases.list","status":"retryable_failure","error":{"code":"storage_unavailable"}}

不发起 REST 调用的本地命令：atlas version、atlas config set|get base-url、atlas auth login|status|logout。

atlas team 系列命令除 scope 之外，还受 AI 团队的发布开关约束。平台超级管理员在「平台 → 功能可见性」中通过 ai-team 开关控制，该功能在超级管理员放开之前处于隐藏状态。隐藏期间，任何 atlas team 命令——无论走 CLI、其背后的 REST 动作还是 MCP——都会被拒绝并返回 agent_team_restricted，同时排定的 Account Manager、Sales Assistant 与 Pre-sale Assistant 工作不再启动新任务。其他命令不受影响。

新的 Account Manager 账户复核使用固定的 complete-json-bytes.v1 来源包：分析与已批准证据草稿分别接收 24,000 字节 JSON 信封内的完整授权记录。草稿只接收已批准的证据。分析资料无法全部容纳时，Atlas 直接依据保留的摘录生成结构化限定的部分复核，不暴露模型自由文本，也不生成草稿；若仅已批准的草稿证据有省略，同样不生成草稿。结果会明确标注证据不完整，且绝不会声称已完成完整复核。若没有任何分析记录能容纳，则不产出复核结果。运行与追踪诊断只报告数量，不复制来源正文。旧的固定配置运行与 Sales Assistant 客户组合工作继续使用原有来源选择器。

仓库评测运维

指定用例的诊断评测复用现有平台运维会话与真实 Agent 试验路径。诊断结果始终不具备基线资格，即使全部通过或选中全部 60 个用例也一样。完整标准评测仍是默认的 60 × 3 基线路径。密封方法试验使用同一个私有队列：Governance 保留固定描述符、序号、计费运行和尝试身份，且不会创建 Agent TeamStore 运行记录。这不新增公共启动器或准入路径。

bun scripts/eval-campaign.ts start --key diagnostic-a --purpose diagnostic --cases entry-01,entry-03
bun scripts/eval-campaign.ts drain CAMPAIGN_ID
bun scripts/eval-campaign.ts report CAMPAIGN_ID
bun scripts/eval-campaign.ts summary REPORT_ID
bun scripts/eval-campaign.ts compare FROM_REPORT_ID TO_REPORT_ID
bun scripts/eval-campaign.ts start --key full-golden-a

要试验某一条模型路由，在 start 上加 --model-route glm_only 或 --model-route deepseek_only，例如 bun scripts/eval-campaign.ts start --key route-deepseek-a --purpose diagnostic --cases entry-01,entry-03,entry-05 --model-route deepseek_only。每个评测世界自己的评测组织会在第一次助手运行前被设为该 Atlas 托管预设；你所在组织的模型策略不会改变。其他取值在发送请求前即被拒绝。摘要会在实际观察到的模型旁写明请求的路由，并列出不一致的试验；路由不可用的试验会直接失败，绝不换用其他模型。换一条路由需要新的 --key：用同一个键换路由会被作为冲突拒绝。

如只想在评测中试用某个功能开关，在 start 上加 --feature-preview KEY，例如 bun scripts/eval-campaign.ts start --key plan-prefix-on --feature-preview assistant-plan-prefix。该开关会在第一次助手运行前，只为每个评测世界自己的评测组织开启，并在清理评测世界时移除；你所在组织的开关不会改变。未登记的功能键在发送请求前即被拒绝。要衡量一个开关，在同一组已部署的 Worker 上各跑一次不带该选项和带该选项的评测并分别生成报告，然后运行 compare：该选项不会改变对比兼容键。换一个功能键需要新的 --key。

要对比两条路由，在同一组已部署的 Worker 上为每条路由各跑一次完整标准评测并分别生成报告，然后运行 bun scripts/eval-campaign.ts compare-route GLM_REPORT_ID DEEPSEEK_REPORT_ID。它按路由显示 pass@1 与 pass^3 的通过用例数、发生变化的用例（退步的安全用例单独列出）、每次试验耗时的 p50/p90、每次模型调用计费耗时的 p50/p90，以及每次试验的模型调用次数。若两份报告除路由外还有其他差异，它会写明不同的字段，不给出任何数字。它只负责报告；决策规则由你执行，并由你在“设置 → 模型密钥”中切换路由。

对比要求两份报告的用例选择语义、语料、评分细则、评分器、目标环境与模型策略标识完全一致，且各自的证据内部稳定。对比按用例给出 pass@1 与 pass^3 的修复、回归与未变化结果；任何不兼容都会隐去全部差异。第 1 版报告的存储字节与摘要保持不变。恢复与失败证据见 docs/evaluation-operations.md。

这些 Bun 命令需要已批准的 Atlas 平台运维会话（平台名册中的超级管理员），由私有的 ATLAS_SESSION_COOKIE_FILE 提供。租户管理员会话一律返回 403，且看不到任何占用者信息。它们是仓库运维命令，不是委派令牌 CLI 或 MCP 能力。

bun scripts/eval-reservation.ts status
bun scripts/eval-reservation.ts reconcile OWNER_TOKEN
scripts/deploy-staging.sh governance web
scripts/deploy-web-staging.sh

启动评测必须在 JSON 请求体中给出稳定的 idempotencyKey。用同一个键与同一份载荷重试可恢复缺失的调度；载荷改变则返回冲突。评测状态包含冻结的准入清单。排空请求需指明 campaignId。

目标占用不会因超时自动释放。评测对账要求评测已终结、执行已结算、各服务清理已核实。未持有目标的运维人员会看到占用者、获取时间与当前未结算的阻塞原因，而不是笼统的“已占用”；持有令牌始终不予披露。运维人员可以替已离线的持有者做结算声明，但沿用完全相同的证据要求，并记录声明人。本地进程被强制终止后，中断的发布对账需要子进程与远端发布的结算证据，并出示该占用自身的持有令牌；系统无法自行观测。占用状态缺失即拒绝发布。暂存发布携带新鲜度保证（#2597）：有预构建产物的 Worker（atlas-web 的 SPA 包）在共享预留内、以盖章检出完成构建，构建失败即拒绝发布；由源码打包的 Worker 以干净盖章检出为保证；/health 盖章证明的是检出，而不是实际提供的包。新的迁移与 API 必须先建立才能首次使用；不提供任何绕过方式。

CLI 拒绝信息保留评测 ID 和恢复原因。恢复通过执行结算凭据保留原始结果、追踪与清理证据，不重复调用模型；仅凭经过的时间不能认定已准入的执行完成。

虚构回归用例包

由管理员在本地编写：bun scripts/eval-pack.ts scaffold SOURCE PACK_ID en|zh-CN OWNER OUTPUT，随后依次执行 digest DRAFT、validate DRAFT [VERSIONS_ROOT] 与 publish DRAFT VERSIONS_ROOT。工具不会抓取任何来源对话。产品与销售必须针对确切的语义摘要与版本记录真实审阅。校验只检查格式与绑定；授权由人工在仓库审阅确认。当前已部署的注册表为空，金丝雀草稿尚未审阅。

审阅并部署之后，用 bun scripts/eval-campaign.ts start --key KEY --purpose diagnostic --cases ID,ID,ID --pack-id PACK --pack-version VERSION --pack-digest SHA256 选择用例包。任何身份不匹配都会在创建世界或调用模型之前拒绝。补充报告保留来源与审阅出处，并始终不具备基线资格。不支持运行时上传或远程 MCP 编写工具。

Propose、confirm、reject

生成一条未保存的方法修改建议

atlas team propose '{"operation":"teaching.suggest","hireId":"amhire_example","revision":1,"teachingSuggestion":{"runId":"amrun_example","excerpt":"No clear question.","expected":"Ask for a decision date."}}' --idempotency-key suggest-example-1
atlas team confirm <proposal-id> --idempotency-key confirm-suggest-1

确认返回一条未保存的 data.suggestion，含有长度限制的 proposedInstructions、rationale、inputDigest，以及顶层 runId/hireId。范围默认为账户；审阅后才另行提交 teaching.create。尝试需要当前来源权限和积分。重放不会再次生成；中断后无法恢复时返回 result_unavailable。明确新建提案会独立计费。输入限制、组织权限和保留规则详见 REST 参考。

1. 使用你自选的 key 发起提案：atlas customer create propose "Acme" --idempotency-key acme-1。响应状态为 awaiting_confirmation，并携带 confirmation.id。
2. 检视：atlas customer create inspect <id>。检查 intended_*、evidence 与 expires_at。
3. 使用另一个 key 做出决定：atlas customer create confirm <id> --idempotency-key acme-1-confirm，或使用 reject。
4. 使用同一个 key 重复执行 confirm，会返回原始结果并带有 meta.repeated: true，不会产生第二次实际效果。

提案在创建 15 分钟后过期。对已过期或已拒绝的提案执行 confirm 会返回 conflict。任务提案遵循同样的步骤，改用 atlas task …。

REST

查看独立 REST 参考：请求头、请求示例和响应结构。

输出与退出码

stdout 即 JSON 信封，每条命令输出一份文档。--pretty 会对其缩进。诊断信息输出到 stderr。没有通用的 --yes 参数；确认永远是独立的一条命令。

令牌管理

• 切勿将令牌作为命令参数传递。使用 atlas auth login 或 ATLAS_ACCESS_TOKEN。CLI 绝不会打印或记录它。
• 在 CI 与脚本中，从 runner 的密钥存储中设置 ATLAS_ACCESS_TOKEN，其优先级高于 Keychain。
• 只生成任务所需 scope 的令牌。令牌最长存活 30 天，可由管理员随时吊销。
• 过期与吊销均由服务端决定。CLI 只会返回信封并以 3 退出。

本文档不包含任何分析脚本、远程字体、外部脚本或携带密钥的资源。

故障排查

客户资料、导入与销售阶段

客户档案读取包含网站、背景备注，以及可选的主营市场（main_markets）、品牌（brands）和产品（products）。读取仍按组织和客户负责人权限过滤；使用 REST 导入或客户编辑页面维护这些信息。

任务隐私

本人创建并分配给自己的任务默认标记为 private，即使关联客户也不例外。仅负责人本人可访问，经理和管理员无权绕过。team 任务对负责人、创建人和组织管理人员可见，其他销售人员不可访问。筛选、来源重试、提醒和代理调用均遵守同一权限边界，定时共享上下文不包含私密任务。

受治理的人类团队操作

所有接口复用 Auth 团队函数。新增委托权限 auth:teams:read 与 auth:teams:write 相互独立：写权限只允许提出和确认已审核变更，不包含读取工具。既有令牌不会自动获得权限，须通过 POST /auth/tokens 显式申请。签发以及每次读取、提案、确认、恢复均检查当前有效的所有者/管理员成员身份，以及对应实时 members:read/members:write 能力。撤销、过期、角色降级及不支持的平台/计划任务/同步身份均不能执行。

MCP 工具：auth_teams_read、auth_teams_change_propose、auth_teams_change_confirm、auth_teams_change_reject。提案参数包含变更字段和 idempotency_key；确认/拒绝使用 proposal_id 与 idempotency_key。CLI：atlas organisation teams read '<json>'；atlas organisation teams propose '<json>' --idempotency-key KEY；atlas organisation teams confirm PROPOSAL_ID --idempotency-key KEY；atlas organisation teams reject PROPOSAL_ID --idempotency-key KEY。

REST 动作入口：POST /assistant/v1/actions/auth.teams.read、POST /assistant/v1/actions/auth.teams.change，及现有 POST /assistant/v1/proposals/:id/confirm 或 /reject。提案和决定须提供 Idempotency-Key。结果使用现有 atlas.action.v1 信封，数据与 Auth 团队/分配结果一致。团队变更属于管理类提案，执行前仍受政策暂停、到期、拒绝及实时权限检查约束。提案绑定原始主体、组织、规范化输入、版本依据和幂等键。委托令牌不能绕过政策；所有者决定沿用现有治理流程。

{"operation":"list","status":"active","limit":50}
{"operation":"team","team_id":"TEAM_ID","limit":50}
{"operation":"assignment","email":"rep@example.com"}
{"operation":"create","name":"销售团队"}
{"operation":"rename","team_id":"TEAM_ID","name":"客户成功","expected_revision":1}
{"operation":"archive","team_id":"TEAM_ID","expected_revision":2}
{"operation":"assign","email":"rep@example.com","team_id":"TEAM_ID","expected_assignment_revision":0,"expected_team_revision":1}
{"operation":"assign","email":"rep@example.com","team_id":null,"expected_assignment_revision":1}

列表状态支持 active（默认）、archived、all，按 ID/邮箱稳定排序，使用不透明 cursor，默认 50 条、最多 100 条；原样传回 next_cursor。名称去除首尾空白后不能为空，最多 80 个 Unicode 字符。拒绝未知/多余字段。重命名和归档须提供当前 expected_revision；分配须提供 expected_assignment_revision，非空目标另须 expected_team_revision；移除分配必须省略目标版本。仅能归档无成员的有效团队，不提供角色或全局成员变更。

Auth 将变更、审计和操作回执原子提交。超时或响应丢失后，以相同提案和决定键重试：恢复经过实时准入，仅返回匹配的原始结果，不会再次执行；已执行提案随后过期仍可恢复。缺少回执不能绕过有效期。重复键对应不同输入或版本过期返回冲突；权限撤销返回拒绝；服务/存储不可用返回可重试失败，不能伪装为空成功。所有响应均为 no-store。先部署 Auth 回执迁移 0023_organisation_team_operation_receipts.sql、权限和生产接口，再部署 Agent 适配器；公开会话团队 REST 保持兼容。仅服务绑定可访问 /internal/teams/actions/read 和 /change/prepare、/change/execute、/change/recover，要求精确绑定请求及正文的断言，没有公开别名。

若确认请求超时，操作可能仍在提交。方案保持待定；在结果未确定时，拒绝与过期处理返回冲突。再次确认只查询原操作回执，不重复执行；若始终没有回执，方案保持待定，不能据此假定操作失败。

通过 MCP 与 CLI 读取工作台客户分析

只读操作 crm.workbench.customer_summary.read 与 crm.workbench.customer_contributors.read 沿用 crm:read 权限。普通租户会话与持有该授权的委托令牌，会在 CRM 查询前及返回前由 Auth 重新确定公司、已分配团队、本人或空范围。未分配有效团队的经理获得明确的空范围；无需团队管理权限，也无需确认操作。

MCP 提供只读工具 crm_workbench_customer_summary_read 与 crm_workbench_customer_contributors_read。概览输入严格为 {}；明细输入为 {"metric":"customers","scope_revision":"<scope_revision>","limit":50}，可选不透明的 cursor。指标包括 customers、active、at_risk、open_pipeline；每页默认50条，允许1–100条。额外字段及调用者提供的组织、负责人或范围提示均被拒绝。

atlas workbench customers summary
atlas workbench customers contributors '{"metric":"open_pipeline","scope_revision":"<revision>","limit":50}'

CLI 调用 POST /assistant/v1/actions/crm.workbench.customer_summary.read 与 POST /assistant/v1/actions/crm.workbench.customer_contributors.read，保留现有操作信封。游标字节须原样传递，并使用匹配的范围版本。每页明细与四项总数来自同一次当前 CRM 快照；分页不保证历史快照不变。

结果保留 customer-current-book-v1、公开范围元数据及 evaluated_at。商机 amount_by_currency 使用完整货币单位并按币种分组；unknown_amount_count 统计缺失金额。商机明细同时提供 customer_id/customer_name 与跟进项目名称及ID，不返回内部负责人名单。

响应均为 Cache-Control: no-store。输入或游标无效返回400；凭证与权限拒绝保留401/403；范围变化返回409 scope_changed，需重新读取概览；Auth/CRM 不可用返回503，不伪造零值。平台、定时及同步调用者不受支持。公开 CRM 路由仍仅接受会话，令牌通过受治理操作读取。先部署 Auth 精确允许列表与 CRM 断言入口，再部署 Agent 适配器；不增加迁移或权限范围。

Knowledge 页面与来源权限

此接口已实现但默认未启用。只有在完整的目标数据普查和产品影响审核通过后才可开放。本文不代表已在 staging 或生产环境上线。

离线 CLI 帮助保留这些命令语法。服务端发现和提案准入每次都必须重新检查 Knowledge 所有者的就绪状态；帮助输出不代表接口已开放。

atlas pages list '{"limit":50}'
atlas pages read '{"pageId":"PAGE_ID"}'
atlas pages revisions list '{"pageId":"PAGE_ID"}'
atlas pages revisions read '{"pageId":"PAGE_ID","revision":1}'
atlas pages create '<PageCreate JSON>' --idempotency-key PROPOSAL_KEY
atlas pages update '<PageUpdate JSON plus pageId>' --idempotency-key PROPOSAL_KEY
atlas pages decide '<PageDecision JSON plus pageId>' --idempotency-key PROPOSAL_KEY
atlas pages proposal PROPOSAL_ID
atlas pages confirm PROPOSAL_ID --idempotency-key CONFIRMATION_KEY
atlas pages reject PROPOSAL_ID --idempotency-key REJECTION_KEY

先读取可见页面，再提交完整 JSON 提案并审核。确认成功后查看返回的 page 和可读 revision；修改已批准公司页面时，贡献者可能仅收到旧批准版本和 revision:null。未启用时页面接口返回 404。

ekb.page.list, ekb.page.read, ekb.page.create, ekb.page.update, ekb.page.decide, ekb.page.revisions.list, ekb.page.revisions.read.

个人页面仅限所有者；公司页面的贡献者需要当前 knowledgeFiles 写权限，审核需要 knowledge 写权限。普通公司读者只能看到已批准版本；view=current 仅供作者或审核者。每次读取及重试都重新检查全部来源。来源被撤回、修正或无权访问时，整份衍生内容不可用，包括摘要、引用、相关标题和数量。没有完整来源记录的历史内容以及 Sales 依赖内容保持不可用。core 回退仅从当前原始片段进行关键词检索；纯语义检索返回 source_unavailable，未验证的向量排序不会进入模型上下文。原始文件标题、正文片段、下载和原有权限不变。

读取需要 ekb:read；返回页面内容的 delegated 写操作同时需要明确授予 ekb:read 和 ekb:write。idempotencyKey 是 EKB 操作标识，不能与提案或确认请求的 idempotency_key 混用。保持相同正文和标识重试；409 conflict 表示需要重新读取并审核当前版本。404 source_unavailable 不披露不可读来源；503 read_unavailable 表示无法确认读取结果。内部适配器可使用签名 URL 的 receiptOnly=true 仅恢复既有回执；无回执时返回 404，绝不产生新操作。

合并客户

需要当前客户访问权限。读取与审阅使用 crm:read；提交、继续及取消使用 crm:write，仍须通过 CRM 的当前角色和客户权限检查。组织和操作人来自已验证的凭据，输入不能包含 org_id。此说明对应本地候选功能，不代表已在生产环境开放；完整流程验收前不得启用。

1. 选取 2–10 个客户，先提交 customer_ids 和可选的 survivor_id 进行只读审阅。
2. 按返回的 selection 修改选择，再次审阅完整选择。查看每个值的来源、时间、冲突、关联记录及负责人影响。latest 不会代替必须明确作出的决定；时间相同、主联系人、计划及缺失决定等阻碍须先解决。choices 和 custom_field_sources 的值是来源客户 ID。
3. 向操作人展示最终名称、保留的原始资料数量、负责人及访问变化，取得明确确认。发送前持久保存唯一的 request_id、完整选择、preview_digest 和 expires_at。提交时加上 confirmed:true；不能用通用 --yes 跳过审阅。
4. 持续查看同一操作；只有 state:complete 表示已发布。pending 仍在处理，blocked 需要按阻碍处理。响应丢失时用同一 request_id 查询，不能另建请求；继续操作只用已有 operation_id，不传替代选择。

审阅过期或数据变化后须重新审阅，不能绕过 preview_digest。只有进入 apply 前才可请求取消；以 state:cancelled 为准，取消不是撤销。已开始应用的操作应继续恢复。完成后从合并历史查看保留的关联原始资料；原始资料只读，内容仍按当前访问权限过滤，无自动 Undo。

atlas customer merge preview '{"customer_ids":["CUSTOMER_A","CUSTOMER_B"]}'
atlas customer merge preview 'FULL_SELECTION_JSON'
atlas customer merge commit 'CONFIRMED_COMMIT_JSON'
atlas customer merge request REQUEST_ID
atlas customer merge status OPERATION_ID
atlas customer merge resume OPERATION_ID
atlas customer merge cancel OPERATION_ID
atlas customer merge history SURVIVOR_ID
atlas customer merge original OPERATION_ID SOURCE_ID

将占位符替换为审阅得到的完整 JSON。commit 的 JSON 包含所有选择字段，外加 request_id、preview_digest、expires_at 和 confirmed:true。此流程的幂等标识是 JSON 内的 request_id，不接受 --idempotency-key。stdout 保留 REST 的原始协议对象，不使用 atlas.action.v1；pending 或响应未知返回退出码 6，blocked 返回 5，complete 或 cancelled 返回 0。不要把退出码 6 当作重新提交的指令。

完整字段与 REST 路径

遇到 409 merge_blocked、preview_stale、preview_expired 或请求查询返回 404 时，仍须保留同一 request_id；并发提交可能已经获准执行。重新审阅并明确确认后，继续使用同一编号重试。遇到 idempotency_conflict 时，查询同一编号并恢复已有操作，不能替换已保存的计划。只有确认 state:complete 或 state:cancelled 后才可结束使用该编号。

搜索 Atlas

使用 atlas.search 查找当前身份可访问的记录和内容。此接口只读取；它不会发送邮件、保存更改或调用 AI。以下说明对应待部署的候选实现，不代表线上验收已经通过。

atlas search "电机" --kind customer,task --limit 10

输入 query 为 1–100 个 UTF-16 单元，不允许控制字符；可选 kinds 为不重复的类别数组，limit 为每类别 1–20 条（默认 10）。类别：customer, contact, opportunity, task, work, mail, document, knowledge, chat, assistant.

返回 atlas.action.v1，其结果包含 data.query、items 和 sections。每个请求类别均有状态：complete 表示读取完成，unavailable 表示该来源或凭据不受支持，error 表示读取失败。hasMore 只统计可访问的匹配项。一个类别失败不影响其他类别；可使用原查询重试。

聊天搜索使用 GET /crm/communications/authority/readable?strict=1。已确认的拒绝或空授权集返回 200 {items:[]}；权限服务不可用、响应格式错误或存储失败返回 503。搜索将这些失败标为 error，不返回聊天条目或计数。返回结果前会再次检查邮箱授权；授权变化也会撤回该类别的结果。不带此选项的原有权限查询仍保留返回空集的行为。

入口沿用 crm:read。普通成员会话始终携带此传输 scope，不受 CRM 设置权限影响；各所属服务仍单独执行访问检查。任务另需 tasks:read，文件与知识另需 ekb:read。仅持有 EKB 或 Tasks scope 的令牌应使用原有领域接口。委托令牌不能通过此接口读取私人 chat 或 work；它们沿用普通会话权限。assistant 在独立身份后端可用前返回 unavailable。邮件索引未就绪或失效时，mail 返回 unavailable；不会把摘要搜索伪装成完整正文搜索。

每条结果仅含 kind,id,title 及需要时的 subtitle,snippet,customerId,connectionId,threadKey,fileId,sourceId。标题和副标题最多 200 个单元，摘要最多 300；结果不携带任意网址或执行回调。查询在所属服务的结果上限之前匹配，仍受组织、负责人、任务隐私、邮箱授权、聊天来源及知识可见性限制。

另行授权应用 0167_comm_mail_search_text.sql 并发布 CRM 后，现有 CRM 定时处理器会在已配置的 cron 周期中，自动为已启用 Inbox 的组织调用 runScheduledMailContentBackfill。每次最多处理 10 条、耗时预算 5 秒；持久游标支持续跑和重试，不让失败来源阻塞后续来源。缺少迁移时维护保持停用。检查仅含计数的 [crm.cron] mail content backfill 日志；遍历结束不等于所有正文都已成功索引。未完成、解析失败或已失效的可读来源仍使邮件类别不可用。新导入邮件自动建立索引；源更改、丢弃或删除会使旧索引失效。搜索不会触发索引。使用实时搜索前，请分别核验部署版本和可读内容的索引就绪状态。

邮件导入和旧邮件回填使用带 SHA-256 摘要的独立不可变存储键。发布时须一并包含导入器、附件及回复读取器兼容支持，以及第二版索引和回填逻辑。第一版索引须重建后才可用。回填会固定当前保留的快照，无法恢复历史可变存储键竞争中已被覆盖的原始字节；旧对象会保留。回滚时必须保留新存储键的读取兼容支持，优先向前修复。

助手自动能力配置

新建命名助手会自动沿用 Atlas 现有的任务能力解析：组织启用的技能、可调用的已连接插件工具、内置功能和有权读取的知识。已发布的组织指导和当前用户的生效个人记忆仍由原有模块提供。无需手动分配能力；不会安装服务、增加权限或发布记忆。

目录通过 setupSchema: atlas.assistant-setup.v1 声明支持。明确的中英文工作名称会推断工作重点；名称不明确或包含冲突职责时，在创建提案前返回 400 assistant_purpose_required。请通过可选字段 identity.purpose 提供一条去除首尾空格、1–400 字且不含控制字符的描述。核对工作重点后明确确认。已保存的命名身份可包含 setup: {mode: automatic, focus, source: name|clarified}；旧身份不含该字段。只改头像保留工作重点；改名会重新推断或要求澄清，明确填写的用途优先。工作重点仅作为不受信任的用户数据引导任务技能选择，不授予权限。

共享治理追踪保留运行身份、用量及策略等元数据，不包含私人对话正文、计划或工具输入输出。本人对话历史保持可用。