让外部 AI Agent 安全连入 Lantide

读时间： 约 8 分钟 · 系列： 平台启用（数据工程）进阶 · 上一步： .lantide 汇出汇入 · 下一步： MCP Sources 入门

先分清楚两个方向

团队说「要用 MCP」时，可能在谈两件完全不同的事：

方向	Lantide 的角色	你会在什么地方设定	用途
Agent Integration	MCP server	右上角 Agent Integration	让 Cursor、Codex、Claude 等外部 Agent 读取或操作 Lantide 工作环境
MCP Sources	MCP client	侧边栏 MCP Sources	把外部 API 或数据服务物化成 Lantide 可查询的表

本篇谈第一种：让外部 Agent 连入 Lantide。如果你要接数据源，请读 MCP Sources 入门。两者都叫 MCP，但连线方向、权限与故障排除方式不同。

Execute 模式 的外部 Agent 也可透过 Lantide 代为呼叫 MCP Sources（mcp_explore、mcp_pull_table、mcp_test_source、mcp_connect_source 等），与内建 Agent 共用同一组来源设定；Admin 才可新增／换凭证／Remove。Observe 仅能读已物化表与 schema，不能对远端 call_tool。

什么时候值得开 Agent Integration

适合：

分析师已在 Cursor、Codex 或 Claude 中工作，希望沿用原本的对话介面。
团队仍要求 Plan、SQL evidence、Report 与 Activity 留在 Lantide。
你需要一个可查看、可限制、可撤销的本机 Agent 入口，而不是把数据与凭证交给远端 API。

可以不开：

团队只使用 Lantide 内建 Agent。
只是要让 Lantide 读取外部 API；那是 MCP Sources。
外部 Agent 跑在另一台机器或云端服务。Agent Integration 绑定本机 loopback，不是远端共享 API。

第一次连线（First-run）

首次启动须先选 Setup Mode Choice：Built-in Agent (BYOK) 或 External Agent (MCP)（见 USER_GUIDE §2.1）。

External 路径： 选 External 后 Lantide 会开启 Agent Integration，建议建立 All workspaces 的 Persistent profile。一般 client 复制 connection kit（完整的 mcpServers 具名 entry，例如 lantide-<alias>）并合并进既有 MCP client 设定；不要整档覆写。从支援的 Codex 本机流程启动时，可改用 GUI 的 Approve & Connect：先检查 scope、mode、expiry、exposure 与设定档目的地，再建立 credential 并合并设定；credential 不会显示在聊天或 deep link。再 Copy onboarding prompt 贴到外部 Agent。该 prompt 已含 All-workspaces 的 精简固定 tools/list → 选工作区并使用 response 内嵌 analysis_context 指引；只有 refresh trigger、选择失败或需要最新状态时才再呼叫 get_analysis_context。长尾能力透过 capability search/invoker 使用，选定后不需重新载入工具。Agent 依 playbook version、required skills 与 next action 恢复工作，而非只靠 client 内建提示。详见 Agent Integration 对话框顶部说明与 USER_GUIDE §13.6.1。

Built-in 路径： 不经 Agent Integration first-run；完成 Agent Preferences（可 Skip）与 Open AI Settings 后即可在 Lantide 内聊天。若团队日后要接外部 Agent，再从 Header Agent Integration 手动设定。

第一步：选 Quick 还是 Persistent

选择	适合情境	你要记得的事
Quick connection	一次性测试、只给目前工作区	切换工作区不会让同一份 config 自动改指向新工作区；重新 Expose 沿用同一 `lantide-quick-<workspace>` key，并以新 credential 更新该 entry
Persistent connection	经常使用同一外部 Agent、希望跨 App 重启保留设定	token 只在 Create 或 Rotate 后显示一次；正常重启后 client 仍须重新 initialize；server key 为 `lantide-<alias>`

第一次只想确认 client 能连上，可以从 Quick 开始。要建立日常工作方式，使用有清楚 alias、expiry 与 scope 的 Persistent connection，比反复贴一次性设定容易治理。复制的内容一律是具名 entry，贴入 client 时合并既有 mcpServers，不要整档覆写。

第二步：先选信任程度，再选 mode

Access mode 是这条 connection 的能力上限，不是 Plan 的分析阶段。

Mode	能力	适合谁先用
Observe	唯读工作区与 artifacts；不写入、不暂停内建 Agent	第一次评估、陪同 review、低信任探索
Execute	可建立分析 artifacts，正式查询仍受 Plan review、evidence 与 Report 契约约束	分析师用外部 Agent 完成一个明确工作区的正式分析
Admin	Execute 加上高信任的工作区、专案、知识、alias 与本机交付操作	已信任 Agent，并需要它协助整理环境或完成管理操作

目前 Create connection 表单预设为 All workspaces + Admin。 这是表单预设，不表示第一次试用就该给最高权限。建议依目的分流：

低信任或第一次评估：Observe——先确认它看得到正确工作区与 artifacts。
正式分析：优先 Single workspace + Execute——把数据边界锁在一个工作区，让 Plan、Approve & Execute、evidence 与 Report 留下完整记录。若需跨区比较再绑定，可用 All workspaces + Execute（见下一步），切换沿用 owner_key，保留 Plan 版本核准与待审纪录。
高信任环境管理：Admin——确认 Agent、操作范围与回看方式后才使用。

Admin 不代表比较专业，也不代表可以跳过 Plan 或成果审阅。Admin mutation 直通（整理 workspace、patch knowledge 等）≠ 可跳过 Plan lifecycle；但在 Admin 单开工作法下，Plan 的当下审阅可在外部对话完成，Agent 可在你的明确确认后呼叫 claim_plan_approved 推进 Plan → Executing。Execute 双开仍须在 GUI 按 Approve & Execute。

Plan 核准：三层不要混为一谈

层次	你能期待什么
Admin mutation 直通	高信任的本机设定与 artifact 整理可在 Admin connection 直接执行；仍会留下 Activity 与 audit
Admin 单开 + Plan lifecycle	你在外部对话确认执行后，Agent 可 `claim_plan_approved` → 该版本 Plan 记为已核准并变 Executing；之后正式 SQL 仍须带 `execution_plan_ref` 才进 Steps
Execute 双开	在 Lantide 审 Plan、按 Approve & Execute；Execute connection 不能 claim

Claim 不是「跳过一切治理」：没有确认摘要、Plan 非 planning、或 digest 过期都会失败。事后仍应在 Lantide 核对 Plan Steps、Report、Activity 与 audit。

在 Execute connection，部分 Admin 级操作（如新增数据源）会出现在顶端待审批通知。若该操作需要密文，Approve 会开启 Connections 并预填非密文字段，你补齐凭证后才算完成；Approve all 遇到这类请求会暂停批次。细节见 USER_GUIDE §13.8。

第三步：选 Single workspace 还是 All workspaces

Scope	现在可用的 mode	适合情境
Single workspace	Observe / Execute / Admin	工作边界已确定；正式分析优先使用这种 scope
All workspaces	Observe / Execute / Admin	Agent 需要先比较工作区，之后再明确选一个；一次只有一个选定的 writer 工作区，不是同时写多区

Single／All workspace 都先呼叫 select_workspace 并带 idempotency_key，保存回传 owner_key；之后工作工具每次带 key 与 expected_workspace_id。换 session 与切区沿用 key，只有 Lantide backend 重启需重新绑定。Plan 版本核准是持久分析纪录，不跟著 session 失效；Admin 的对话确认摘要供稽核，Lantide 不会宣称独立验证对话内容。

Initialize／tools/list／prompts/list 只做 unbound 探索，不新增 owner、不取得 writer；实际工作由每次工具呼叫带 key 接续：

首次 tools/list 就是依 Access Mode 固定的精简 session catalog。核心工具直接呼叫；长尾能力用 search_capabilities 找到 descriptor，再依 invocation 使用 read/write invoker。descriptor 会揭露 availability、data access 与 workspace read scope。未绑定时，未带工作 key 时回 OWNER_KEY_REQUIRED（受限的 bootstrap 指引例外）。未绑定可呼叫 search_capabilities，搜寻不解锁工具；load_skill 仍须先选工作区。例外：新工作区导入（import_new，含 compact write invoker）可在未绑定时完成，不要先建立空工作区。绑定后先使用 selection response 内嵌的 analysis_context，只有需要刷新时再呼叫 get_analysis_context。见 USER_GUIDE §13.9。
analysis-context.v2 只揭露适用 Knowledge 的 metadata；正文由 Agent 按需呼叫 read_applicable_knowledge 读取已核准的 User／focused Project Knowledge，Queued Knowledge 不会被带入。
已绑定工作区后，Agent 可用 invoke_read_capability(target_workspace_id=…) 读取另一工作区的 snapshot-safe Plan、Report、Reference、HTML 与 lineage，不切换 GUI、不改 writer ownership，也不影响目前 Plan 核准／review；live query、schema／source、GUI handoff 与任何 write 仍不允许。
搜寻长尾能力时，Agent 应使用简洁英文「动作 + 对象」，一次搜寻一个动作。搜寻本身不执行能力，因此一般探索维持 side_effect=any；此栏位筛的是目标能力类型。domain 是 optional single enum；确定分类时填一个，不确定则省略，零结果时移除 domain 并改写一次。外部 Agent 不使用或看见任何 activate_*；HTML 与 Execute／Admin 统计能力直接搜寻，统计执行走 write invoker 并保留参数确认、Activity、audit 与 evidence。
Observe 选定工作区后只做背景唯读探索，不切换 Lantide GUI，也不排挤既有 writer。
Execute／Admin 选定工作区后取得该工作区的 writer ownership，预设会切换 Lantide GUI 到该工作区（方便你立刻审阅）。若你明确要求不要打断画面，外部 Agent 可关闭 GUI 切换，但仍会绑定业务工作。切换沿用 key、保留原区 Plan 核准与待审纪录；执行中操作须先完成，仍是一次一区 writer。

内建 Ask ≠ MCP Observe： 内建聊天的 Ask 只让内建 Agent 不改产物；Observe 只约束外部连线。两者不要混用名称或设定。见 USER_GUIDE §12.1.1。

若另一条 Execute / Admin session 已在写入，系统不会静默抢占。外部 Agent 必须先说明阻挡者与风险，取得你的同意后才能指定该 session 重试。

需要去另一个既有工作区时，请改用 All-workspaces profile；不要让 Agent 建一个新工作区假装完成切换。并行写多个工作区时，请改开多条 Single workspace 连线。

从侧边栏把 Project、文件、数据列或工作区拖进外部 Agent 输入框，会交出一笔物件参照；Agent 用既有 MCP 工具解析，请不要手改那段文字。拖出工作区只是指出目标，不代表立刻 select_workspace；真正切换 Execute／Admin 写入工作区仍会动到 GUI 焦点与授权。

Expose、active 与 selected 不是同一件事

画面状态	意思
Profile 已 Exposed	endpoint 已可接受 client；不代表 session 已建立
External session observing（蓝色）	Observe session active；内建 Agent 仍可使用
External agent mode enabled（绿色）	Execute / Admin writer active；内建 Agent 在该工作区暂停
All-workspaces unbound	client 已连线，但尚未选工作区
Activity 显示 Ended	历史仍在；不代表 Agent 还连著

遇到「已 Expose 但 Header 没状态」时，先确认 client 是否重新载入 MCP 并成功 initialize，不要把 waiting 当断线或把旧 Activity 当 active。

换对话或换 Agent 接续

首次接手先让 Agent 读工作区分析脉络索引，再依导航查 Plan、Report、Knowledge 与变更细节；之后用相同范围的 cursor 增量读取。近期摘要不是完整历史，未读的旧决策与未知原因不能被当成已确认事实。

Sidebar 的物件或来源父列可拖到外部 Agent，明确指定要读的文件或数据集合。父列参照不会自动刷新 Cloud 索引或重新连线；改绑来源后应重新拖移。Activity 的文件变更可开启唯读差异视窗，便于审阅实际修改。

你如何验收外部 Agent 的工作

外部聊天里的「我已完成」不是成果依据。建议依序检查：

Artifacts——预期的 Plan、SQL、Report 是否真的存在。
Plan lifecycle——正式分析是否经过 Approve & Execute（Execute 双开），或 Admin 单开下经 claim_plan_approved 且 Activity 有对应纪录；而不是把探索结果当正式数字。
Evidence——关键数字能否回到正式查询步骤。
Report——是否回答问题、包含具体数字与 limitations。区分 Markdown Report（NN_report.md，常由 add_report 写入）与 HTML Report（同名 NN_report.html sibling，须经 HTML 工具产生）；外部 Agent 不应只用聊天摘要代替 HTML 交付。若成果已发布到 P4、KM、URL 或其他位置，可建立 External Delivery metadata-only 回绑；它不会自动抓取或验证外部内容，只有 HTTP／HTTPS location 可由使用者主动点击开启，unlink 不会删除外部成果。
External MCP Activity——实际呼叫、受影响文件与 +N/-N 是否符合预期。
Audit / Save History——高信任操作与本机交付是否留下对应记录。

Activity 中支援安全回退的内容变更会显示 Undo。系统只在文件尚未被后续修改时允许 Revert；若内容已变更便阻挡，不会强制覆写。新建档回退时会清空内容但保留文件；Plan lifecycle、export、连线与知识治理等具副作用的操作不能从 Activity 回退。

Activity 隐私与保存

Activity 保存经遮蔽的 host facts、artifact identity 与行数统计，不是外部聊天纪录，也不把 token 或变更正文放进活动事件。

Archive：只把 ended session 从日常列表隐藏。
Clear archived/ended history：实际删除符合条件的 Activity 与相关 Undo snapshot。
清理 Activity 不会删除 active session、business audit、Plan、Report 或 knowledge。

设定细节与完整按钮步骤见 USER_GUIDE §13.7。

常见误区

误区	实际
All-workspaces unbound 时 Agent 说「只有管理权限／做不了分析」或「工具很少」	unbound 是尚未选工作区，而工具较少也是精简 catalog 的预期结果。未绑定可 `search_capabilities`，搜寻不解锁。除 `import_new` 外先 `select_workspace`，使用 response 内嵌的 `analysis_context`；只有需要刷新时再呼叫 `get_analysis_context`，不需重新 list
Approve／`claim_plan_approved` 后 Progress → Steps 仍是空的	正式 SQL／Source Run 必须带 `execution_plan_ref`（通常先 `read_artifact(type=plan)` 或长尾 `read_plan` 取最新 digest）才会写入 Steps；无 ref 的查询可当 exploration，Steps 不会更新
Header 显示 Continue，以为 Plan 没进入 Executing	在 external lease 下 Continue 多半是预期 UI；请看 Plan 状态、Progress Steps 与 Activity，不要只靠按钮文案判断
Admin 连线就等于可以跳过 Plan 核准	Execute 双开仍须在 Lantide 按 Approve & Execute；Admin 单开才可在你明确确认后由 Agent 呼叫 `claim_plan_approved`，且之后正式 SQL 仍须带 ref

安全底线

MCP host 只绑定本机 127.0.0.1；不要将 config 当远端 API 分享。
bearer credential 只放进你信任的本机 MCP client，不贴进 issue、公开聊天室或团队 wiki。
更新 MCP 设定时合并具名 entry，不要用单一 connection kit 整档覆写 client 的其他伺服器。
Unexpose 暂停 endpoint；Rotate 让旧 token 立即失效并要求更新 client config；Revoke 永久撤销 profile。
Persistent token 只显示一次；建立时就放入合适的本机 secret/config 管理位置。
Admin 单开是进阶工作法。若不即时看 Lantide，仍要在完成后回看 artifacts、Activity 与 audit。

完整设定、关闭视窗与 recovery 操作见 USER_GUIDE §13。

第一次试用检查清单

确认使用的是 Agent Integration，不是 MCP Sources
用测试工作区建立一条有 expiry 的 connection
低信任评估先选 Observe，确认内建 Agent 仍可使用
正式分析优先 Single workspace + Execute；若用 All workspaces + Execute，确认切区返回沿用原 key 与有效 Plan 核准
在 Lantide 核对 Plan、evidence、Report 与 External MCP Activity
演练中断 session，确认 profile 仍可 Expose 并重新 initialize
确认团队知道谁可以 Rotate / Revoke，以及谁负责 Approve & Execute