外部 AI Agent 與 MCP Server

13. 外部 AI Agent 与 MCP Server

目前的工作接续以 owner_key 识别业务工作。首次 select_workspace（Single／All 都适用）带 idempotency_key，成功后保存回传 key；后续工作工具每次带 key 与 expected_workspace_id，compact invoker 放最外层。换客户端 session 或切工作区沿用 key；harness 列工具、列 prompts 不取得工作权。Lantide backend 重启后需重新绑定取 key，已保存的 Plan 版本核准仍保留。

交给另一个 Agent 接续： owner_key 是私有的工作接续凭证，不是使用者身分或 Plan 核准。你可以请原 Agent 透过私有交接提供 key、目前工作区与简短进度；接手 Agent 必须使用同一个连线设定（profile），先用 key 读取目前 context，再依该 profile 的模式与工作区范围操作。交出 key 不会自动停用原 Agent，请原 Agent 停手，避免同时切区或写入；不要把 key 存进 Report 或专案笔记。若明确接管并踢除旧工作，旧 key 及共用它的所有 Agent 都会失去该工作的接续能力；执行中或待恢复操作须先完成。

Plan 核准与连线分开： Execute 由 GUI 核准；Admin 可在你于对话明确同意后呼叫 claim_plan_approved，记录版本与确认摘要。系统不再核发 session／runtime execution grant。切区或重连不撤销核准；Plan 正文版本改变、明确停止或撤回时，不能再沿用旧核准。Report 的内容、证据与版本检查仍保留。

Lantide Data 也可以作为本机 MCP Server，让你惯用的外部 AI Agent（例如 Cursor、Codex、Claude 或其他支援 Streamable HTTP MCP 的客户端）直接使用 Lantide 的数据环境与分析工作面。

外部 Agent 不是取代 Lantide 的 GUI：它在自己的对话中和你协作；Lantide 则保存可检视的 Plan、Report、SQL / evidence、审批、Save History、audit，以及 Agent 实际呼叫 MCP 的活动纪录。这能让「Agent 说它做了什么」与「Lantide 实际留下什么」彼此对照。

不要和 §4.6 的 MCP Sources 混淆。 MCP Sources 是 Lantide 作为 MCP client 接入外部数据或 API；本节的 MCP Server 则是 Lantide 作为 MCP server 供外部 AI Agent 连入。

13.1 何时适合使用

选择外部 Agent 整合，通常是因为你已在某个外部 Agent 中工作，但希望分析不只停留在聊天纪录：

• 想让 Agent 对本机数据进行分析，同时把 Plan、Report 和正式证据留在 Lantide。
• 想在 Claude / Codex 中维持原本的工作方式，但能在 Lantide 审阅执行、成果与活动轨迹。
• 想让高信任 Agent 协助整理工作区、专案、文件别名或知识，仍保留 GUI、audit 与可追溯 artifact。

若你只需要在 Lantide 内完成分析，直接使用内建 AI 助手即可；不必建立 MCP connection。

13.2 开启 Agent Integration

1. 在主画面右上角点击 Server Cog 图示，开启 Agent Integration。预设会开启 Persistent connections 分页。
2. 开启顶端的 Enable MCP server。这是全域开关，同时控制 Quick 与 Persistent connections。
3. 在 Persistent connections 建立常用连线，或切到 Quick connection 建立仅绑定目前工作区的一次性连线。

Codex 一键配对： 若你从支援的 Codex 本机流程开启 Agent Integration，Lantide 可先带入「配对 Codex」请求。请在 GUI 检查 scope、access mode、expiry、exposure 与设定档目的地后，按 Approve & Connect；只有核准后才建立 credential 并合并 Codex 的本机 MCP 设定。此流程不会把 bearer credential 显示在聊天、deep link、命令列或剪贴簿。若设定写入失败，才改用一次性的 connection kit。

关闭全域开关会立刻停止所有可连入的 MCP endpoint，并 unexpose Quick 与 Persistent connections；已保存的 Persistent profile 设定不会被删除。日后重新开启全域开关时，仍有效且设定为 exposed 的 Persistent connections 会恢复可用。

安全提示： Lantide 的 MCP host 只绑定在本机 127.0.0.1。连线设定包含 bearer credential，请只贴到你信任的本机 MCP client 设定中；不要贴到公开聊天室、issue 或远端主机。外部 Agent 不能自行向 Lantide 要求或重建你的 credential。

13.3 Quick connection：针对目前工作区的一次性连线

Quick connection 适合一次分析、临时使用外部 Agent，或你只想将目前工作区交给它。

1. 切换到要使用的工作区。
2. 在 Quick connection 分页选择 Access mode。
3. 点击 Expose host。Lantide 会在同一步建立新的 connection credential。
4. 点击连线设定旁的 Copy 图示。复制内容是完整的 mcpServers["lantide-quick-<workspace>"] JSON entry；请将这个 named server 合并到外部 Agent 既有的 MCP 设定，不要用整份复制内容覆盖原设定档。
5. 回到外部 Agent，重新载入 MCP 或开始新对话，让它 initialize。

Quick connection 的 credential 只透过 Copy 内容交付；离开这个画面后不会再次显示。若遗失设定，请 Unexpose 后再 Expose，取得新的设定。同一 workspace 重新 Expose 时会沿用同一个 lantide-quick-<workspace> server key，并以新 credential 更新该 entry。Quick connection 是 workspace-scoped，切换工作区不会让同一份 config 自动改指向新的工作区。

13.4 Persistent connection：可跨重启使用的连线

Persistent connection 适合经常使用同一外部 Agent，或希望关闭 Lantide 视窗后仍能保留已授权的本机 host。

1. 切到 Persistent connections，点击 Create connection。目前建立画面的预设值为 All workspaces + Admin；这是表单预设，不代表所有情境都应选 Admin。第一次评估或低信任的唯读探索可先选 Observe；需要 Plan 审阅与正式证据、且一次只专注一个工作区的分析可选 Execute（All workspaces 或 Single workspace 皆可）。
2. 输入可辨识的 Alias，例如「我的 Codex 分析连线」。Lantide 会将 alias 正规化为 copied config 的 lantide-<alias> server key；正规化后的名称不可与未封存的 Persistent connection 重复。若 alias 不含可用的英数字元，server key 会自动带上 profile 短 id 以保持唯一。
3. 选择 Access mode 与 Connection scope：

• Single workspace：选择一个必填工作区；连上后自动绑定该工作区。Access mode 可选 Observe / Execute / Admin。
• All workspaces：可搭配 Observe / Execute / Admin。每次连线从未绑定状态开始，由 Agent 先探索再明确选择要工作的工作区。Execute 为单线双开（同一连线任何时刻只有一个 selected writer）；若要多工作区同时写入，请另开 Admin 单开（Single workspace）连线。

4. 选择 expiry（1 / 3 / 7 / 30 / 180 / 365 天或 Permanent），并决定是否立即 Expose。
5. 建立后复制显示一次的 JSON config。请将其中的 named server 合并到 MCP client 既有的 mcpServers，不要覆盖整份设定档。

Persistent config 使用安装层级稳定的本机 URL；在正常重启 Lantide 后，已 exposed 且未到期、未 revoked 的 profile 可用同一份 config 重新 initialize。token 只在建立或 Rotate 后显示一次，profile 清单不会回显 token。

如果 stable port 被其他程式占用，Persistent connections 会显示 warning，可能包含可辨识的 PID / process name。释放 port 后可按 Retry，不必重启 Lantide；Retry 不会改变 URL。只有你主动使用 Change local MCP port 才会变更 URL。

13.5 Access mode：这是 connection 的能力上限，不是分析阶段

Access mode 在建立 connection 或 Quick connection 时由你选择。它是外部 Agent 能做到什么的能力上限，不会因 Plan 从 planning 变成 executing 而自动切换。

新建 Quick / Persistent connection 只提供以上三种模式。Draft 已停用，不再提供为新连线选项，外部 Agent 也不应推荐 Draft。

Plan 的 Approve & Execute 只会核准该 Plan 的执行范围与证据脉络，不会把 connection 从 Observe / Execute / Admin 自动升降级。相反地，外部 Agent 也不能自行透过 MCP 提高 access mode 或开启全域 MCP server。

13.6 三种推荐工作法：不是新的 mode

Access mode 是硬性能力边界；以下是 Lantide 建议外部 Agent 依任务与你的偏好采用的工作法。外部 Agent 连上后会读取 playbook，应向你说明目前连线的 scope、能力与推荐做法。

这三者不是设定页中的第三个 mode，也不会限制你改变工作方式。Admin 连线时外部 Agent 通常先推荐双开；若你只说「少打扰」或不确定，它应先问你要即时看 Lantide还是之后回看——仅低打扰偏好不足以改推单开。单开是进阶工作法：不代表可以省略 Lantide 的分析记录方式；当下审阅在外部对话，回看时在 Lantide 看到的产物与 Activity／audit 应与双开同等完整。若你不确定，直接告诉外部 Agent 你的目标与偏好，或问：「这个连线现在能做什么？我应该怎么用 Lantide？」

外部 Agent 可在首次使用或团队工作流需求出现时，一次性介绍开源的 Lantide Team Workflow Skill。这是可选的 client Skill，协助串接连线、团队审阅、证据与交付规范；未安装也能继续分析。使用者提出或接受安装后，Agent 才依安装指南拉取完整的 skills/lantide-team-workflow-default/ 子目录，固定同一个 commit，不需下载整个 repo。已安装或拒绝后不应反复提示；这个 Skill 不提高 MCP 权限，也不取代 live playbook 与 Lantide runtime skills。

13.6.1 Playbook 资源与 Plan／chat 面分工

外部 Agent initialize 后可读取 MCP playbook 资源（例如 external_agent_playbook、recommended_next_steps），作为产品导览与下一步建议的权威来源，而非仅依赖 client 内建提示。

Copy onboarding prompt（Agent Integration 顶部）会引导外部 Agent：先 tools/list；首次列表是本次 session 的精简固定工具目录，核心能力可直接呼叫，长尾能力则用 search_capabilities 搜寻。若是 All workspaces，必要时先 select_workspace（或 Admin 的 create_workspace_and_select）；成功 response 已包含 analysis_context，应先使用内嵌内容，只有 refresh trigger、选择失败或需要最新状态时才呼叫 get_analysis_context。选择后不需重新载入工具。尚未选定工作区时，workspace-bound 工具会回 WORKSPACE_SELECTION_REQUIRED，这不是权限失败。未绑定可呼叫 search_capabilities，搜寻不解锁工具；load_skill 仍须先选工作区。例外：新工作区导入（import_new，含 compact write invoker）可在未绑定时完成，不要先建立空工作区。你无须手动维护 client 内的长篇 system prompt。

长尾能力的固定用法： Agent 先把使用者意图改写成简洁英文的「动作 + 对象」，一次只搜寻一个动作，例如 edit CSS styles of an existing HTML report，不要只搜 test、report、add 或 analysis。搜寻本身永远不执行能力；side_effect 筛选的是「目标能力」而非搜寻动作，因此一般探索维持 any，只有明确要排除某类能力时才缩小。domain 是 optional single enum filter，不是启用工具组；确定分类时可填一个，不确定就省略，filtered search 无结果时移除 domain、改写英文后重试一次。多步工作应拆成多次搜寻，不传多个 domain。接著检查回传的 capability_id、descriptor_digest、input_schema、side_effect 与 invocation。invocation=direct 时优先直接呼叫核心工具；read 用 invoke_read_capability；write 用 invoke_write_capability。若 host 已把 direct capability 送入种类相符的 read／write invoker，server 也会接受这条相容路径，无需刷新或重新配对；它仍使用相同的原工具 schema 与 canonical executor。invoker 必须原样带回 id／digest，并只把原工具参数放进 arguments。若收到 CAPABILITY_DESCRIPTOR_STALE，重新搜寻后再呼叫，不能猜 digest。read／write invoker 不会提高 Access mode，也不会跳过原工具的 confirmation、Activity、evidence、lifecycle 或 audit。

External compact core 的公开 input schema 使用跨 host 可携子集；复杂的互斥与 lifecycle 规则仍由 Lantide server 验证。Capability descriptor 会明示 availability、data access 与 workspace read scope。analysis-context.v2 只列出适用 Knowledge 的 metadata，不会自动传送正文；Agent 需用 read_applicable_knowledge 按需读取已核准的 User／focused Project Knowledge，Queued Knowledge 不包含。add_plan 对新 external session 只公开 inline verification，不再公开 legacy verification_ref 或 oneOf／not 组合；已快取旧 schema 的 direct client 在相容期仍可完成原呼叫，但新工作应依当前 schema 使用 inline verification。

External MCP 不使用、也看不到内建 Agent 的 activate_analysis、activate_html_editing 或其他 activate_*。Execute／Admin 要做统计分析时，直接以 domain=statistics 搜寻 t-test、比例检定、相关性、回归、时间序列、预测、趋势、分群、异常侦测或描述统计能力，再依 descriptor 走 write invoker；执行前仍须确认精确方法、栏位、filter 与方法参数。HTML 建立、CSS 与 custom JavaScript 也直接以 domain=html 分别搜寻，不需 activation。

13.6.2 外部 Agent 何时建立工作区、专案或切换 Focus

外部 Agent 应先读取既有 project、artifacts 和目前 focus，再向你说明组织决策。它不应因为新聊天、暂时没有 activity，或只是偏好整齐就大量建立 workspace / project。

13.7 在 GUI 审阅外部 Agent 的工作

Header 显示的是后端确认的 active session，不是「已 Expose」的设定状态：

• Observe session： 顶端显示蓝色 External session observing。Observe 是唯读连线，不取得 writer ownership，内建 Lantide Agent 仍可使用。
• Execute / Admin writer session： 顶端显示绿色 External agent mode enabled。这表示目前工作区由外部 writer session 操作，内建 Lantide Agent 会暂停，避免两个 Agent 同时修改同一分析脉络。
• Exposed waiting： endpoint/profile 已可接受连线，但尚无 active session；Header 不会把它显示成 connected。请到 Agent Integration 查看 exposed、recovery 或 conflict 等设定状态。

侧边栏工作区列只在该工作区有 active external session 时显示 MCP 状态图示：Observe 使用蓝点，Execute / Admin 使用绿点。它是目前工作的快速提示；完整连线设定、等待与错误处理仍以 Agent Integration 为准。

• 点击 Header 胶囊或 AI 面板中的 Manage 可开启 Agent Integration。
• 胶囊右侧的 link-off 图示是「中断目前 session」。它会结束当前外部 MCP 对话并要求 client 重新 initialize，但不会 unexpose Quick connection、也不会 revoke Persistent profile 或 token。
• 若要真正停止 Quick connection，请在 Quick 分页按 End external agent mode / Unexpose；若要停止 Persistent connection，请关闭该 profile 的 Expose 开关。

右侧面板的 External MCP Activity 是观测与核对面板，让你确认 Agent 实际呼叫了什么、改了哪些内容，以及在安全条件成立时回退单笔内容变更：

• 每个外部连线建立 logical session；标题显示 profile alias（或 Quick connection）、工作区与 Active / Ended 状态。Activity history 可保留已结束的工作，但不代表 session 仍 active。
• 卡片依时间由上往下新增，记录 initialize、resource read、tool call、policy / review 结果与 connection end。点卡片可展开经过遮蔽的安全摘要。
• 每个成功的 content mutation 各自形成一张 Activity 卡；系统不依时间猜测外部对话回合，也不把多个 tool call 冒充成一个 operation。卡片会标示事件当下的工作区名称；下方常驻显示受影响的 SQL、Plan、Report、Reference（含外部文件汇入建立／替换）或 HTML artifact，以及绿色 +N／红色 -N 行数。点档名可开启 artifact；若它属于另一个工作区，系统会先要求切换（适用 SQL／Markdown／HTML 等资源），而不会建立错误的空白分页。
• 支援安全回退的变更右侧显示 Undo 图示。确认 Revert 后，系统只回退该笔 content mutation；回退前会验证目前内容仍等于当时记录的 after hash。若后续已有人工或其他 Agent 修改，会以 content conflict 阻挡，不提供 force revert。
• 新建文件的 Revert 会清空内容但保留文件。Plan lifecycle、execution completion、lineage、export、workspace / connection mutation、knowledge governance 等具副作用的操作不支援由 Activity 回退。成功回退后，原 Activity 仍保留并显示已 reverted，系统另追加回退活动与 audit；不会删掉原历史。
• History（标题右侧时钟图示）可切换过往 session；蓝点只代表该 session 有你尚未看过的非 session-end活动（断线／重启结束本身不计），不代表连线仍 active。蓝点紧贴 profile 名称尾端。列表顶部可选 Mark all as read 一次清除所有蓝点。Ended session 可 Archive（从列表隐藏，但保留纪录直到保留期限到期）。
• 右侧图示列的 External MCP activity icon 在面板收起时，若有尚未看过的 attention 活动会显示红点；打开 Activity 面板后红点隐藏（未读改由 History 蓝点提示）。
• 活动内容会遮蔽 bearer credential、token 与不应显示在观测面板的敏感内容。Activity 不是外部 Agent 的聊天纪录，也不保存变更正文；Undo 所需的受限 before/after snapshot 另行保存在本机。
• 标题列 History 左侧的齿轮图示开启 Activity retention and privacy：
  • 从下拉选单设定 Max events per session 与 Ended session retention；储存后立即清除过旧 session 并压缩事件数量。
  • Clear archived history (N) 只删除已 Archive 的历史；Clear ended history (N) 删除全部 ended history（含已 Archive 者）。括号显示各自会删除的 session 数量，两者都会同步删除相关 Undo snapshots，且不会清除 active session。
  • 上述清理不影响 business audit、artifacts 或 knowledge。设定变更与 Clear 会写入本机 host-level admin audit，不会把敏感正文写进 Activity 事件。

外部 Agent 可开启、focus 或刷新相关 Plan / Report / SQL tab。你仍应以 Lantide 中实际出现的 artifact、Plan steps、Report、Save History、Activity 与 audit 作为成果依据，而不是只依赖 Agent 在外部聊天中的口述。

跨对话接续分析脉络： 外部 Agent 首次接手工作区时，可用 read_workspace_manifest 分页读取目前文件、知识、关系与近期变更，再依导航读取正文及事件细节。之后使用 read_workspace_changes 与相同范围的 cursor 增量接续，必要时以 read_workspace_change 查明变更理由。快照后的 cursor 不代表已读完更早历史；不完整、未知或未确认的资讯不能当成已核准事实。这些能力依目前 Access Mode 与工作区范围提供。

13.8 Plan、审批、证据与 Admin 操作

正式 Report 的共同门槛： 内建与外部 Agent 新建正式 Report，都必须对应本次已核准、正在执行且符合结案条件的 Plan；品质检查不能代替执行授权。Draft mode 不提供新建 Report，先把报告大纲写在 Plan。快速问答与探索可直接进行；既有 Report 的文字维护仍可使用原入口。人类在 GUI 手动建立 Report 不受这项 Agent 门槛限制，但不会因此取得正式执行证据。

Execute connection 的分析流程通常是：Agent 建立或修订 Plan → 请求 GUI review → 你在既有 Plan 工具列按 Approve & Execute → Agent 取得该 Plan 的执行范围 → 在范围内连续执行正式查询与产出 Report。你不需要为 Plan 中每一笔正式 SQL 重复确认。

Admin 单开（进阶）的 Plan 核准例外： 若你主要在外部 Agent 对话中审阅 Plan，且已明确表示同意执行，外部 Agent（仅 Admin connection）可呼叫 claim_plan_approved，将该版本 Plan 记为已核准并推进为 Executing——效果等同 GUI Approve & Execute，但当下不必打开 Lantide Plan 工具列。此路径须带最新 Plan digest 与你的确认摘要；Execute connection 不可用。Claim 之后的正式 SQL 仍须带 execution_plan_ref 才会写入 Plan Steps；若你正在看 Lantide GUI，仍应优先使用 Approve & Execute。

三层区分（避免混淆）：

正式 evidence 会被留在 Plan 的 execution progress。未关联 Plan 的探索查询可以存在，但不应被当成 Report 的关键数字。若 Report 产出后需要补充数据，Agent 可以将 post-execution action 连到 Report，使 Lantide 显示这是正式步骤之外的补充证据；修改 Report 时也能连回对应 evidence。

Admin 操作依 connection mode 具有不同确认方式：

• 在 Execute connection，Admin 级操作会出现在顶端的 Pending Admin approvals 通知（例如新增／重绑 Additional folder、Cloud folder，或建立／重绑 SQL Server 连线）。卡片由旧到新排列，逾时未处理会自清单移除（约 5 分钟）；已过期的请求无法再核准。
• 你可逐笔 Approve／Reject，或 Approve all。多数操作核准后后端才会套用变更；若该操作需要帐密等密文（例如新建 SQL Server／Cloud folder），Approve 会开启 Connections 并预填非密文字段，你须在表单补齐凭证后才算完成——此期间操作仍属未完成。Approve all 遇到第一笔需补凭证的请求时会暂停批次，其余卡片维持 pending。
• 在 Admin connection，Lantide 不会为每笔 Admin 操作要求 GUI confirmation。外部 Agent 仍会收到安全 warning，并应先在自己的对话中取得你的同意；所有操作仍留下 audit 与 Activity。

对于 result export，Agent 会先 stage 完整结果并确认 staging 已完成，才送出 review 或 direct-save。Execute 通常由你在 GUI 核准或按 Save；Admin direct-save 会以已确认、不可被 Agent 任意换掉的 destination 写入，并留下 warning / audit。你可在右侧 Save History 查看 Preparing、Ready to save、Saved、失败或过期等状态；手动 Results 汇出仍是原本的本机文件选择流程。

13.9 All workspaces 的选择与切换

All workspaces profile（Observe / Execute / Admin）在每次外部 Agent initialize 后都从 unbound 开始，不会暗中沿用上次的工作区。它可以先用安全的摘要读取来比较所有工作区与专案。一般深层工作或任何写入仍需明确选择一个工作区；若只需读另一工作区的 snapshot-safe artifact，可在不切换 writer 的情况下使用跨工作区 snapshot read。

建议顺序（Agent 与你验收时可对照）：

1. Initialize 后呼叫一次 tools/list → 这就是本次 session 的精简固定工具目录；完整 mode-allowed 能力仍可经 search_capabilities + read/write invoker 触达，选择或切换工作区后不会改变。
2. 用 discovery 工具比较工作区后，呼叫 select_workspace（仅 Admin 亦可 create_workspace_and_select）绑定一个工作区。
3. 尚未绑定时，其他 workspace-bound 工具会回 WORKSPACE_SELECTION_REQUIRED。未绑定可呼叫 search_capabilities，搜寻不解锁工具；load_skill 仍须先选工作区。例外：新工作区导入（import_new，含 compact write invoker）可在未绑定时完成，不要先建立空工作区。绑定成功后不需再 call tools/list；先使用 response 内嵌的 analysis_context，只有 refresh trigger、选择失败或需要最新状态时才呼叫 get_analysis_context，再按需读 playbook／current_state／recommended_next_steps，然后进行专案、Plan、Report 或查询工作。
4. 已绑定 A 时，如只需读 B 的 snapshot-safe Plan、Report、Reference、HTML metadata／content、External Delivery 清单或 evidence lineage，可对 invoke_read_capability 传 target_workspace_id=B。这是 per-call snapshot read：不切 GUI、不改 writer ownership，并保留 A 的 Plan 核准／review；回传会带来源 identity 与 freshness。live query、schema／source、GUI handoff、draft／write 与 pending operation 都不允许，且多次呼叫不保证形成同一 transactional snapshot。

Observe（All workspaces）

• 选择工作区后可做唯读探索；不会取得 writer ownership，也不会切换 Lantide GUI 的目前工作区。
• 可与既有 Execute / Admin writer session 并存；不会因为目标工作区已被占用而要求 eviction。
• 不可建立新工作区（create_workspace_and_select 仅 Admin 可用）。

Execute（All workspaces）— 单线双开

• 同一连线任何时刻只有一个 selected writer workspace；成功选择后预设会切换 Lantide GUI 的目前工作区（activate_gui 预设为 true）。仅在你明确要求不要打断画面时，Agent 才应传 activate_gui=false（仍会绑定 session／ownership；后续 tool 仍可能切换 process connector）。
• 切换工作区沿用 owner_key，保留原工作区的 Plan 版本核准与待审纪录。实际执行中或待恢复操作须先完成；回到原区后重新取得 writer、确认版本仍有效即可续做，不必因切区再核准一次。
• 不可建立新工作区；正式核准请用 GUI Approve／Continue（claim_plan_approved 仅 Admin）。
• 若要多工作区同时写入，请另开其他 Admin Single workspace 连线，不要把同一条 Execute All workspaces 连线当成并行多写入。

Admin（All workspaces）

• 成功选择或建立工作区后，同一 MCP session 绑定该工作区；预设会同步切换目前 active workspace 并刷新侧边栏（activate_gui 预设 true）。仅在你明确要求不打断画面时才应传 activate_gui=false。
• 同一份 owner 工作一次只持有一个 writer workspace；切换保留 key、Plan 核准与 pending reviews。其他 owner 不会因此失去其独立工作。
• 若目标工作区已被另一条 writer connection 使用，Agent 会看到占用资讯。它必须先在外部对话取得你的同意，并以指定 session 重新送出切换；系统不会静默抢占。被你同意 eviction 的 session 会结束，但该 profile 的 expose / token 设定仍保留。

若你目前使用的是 Single workspace 连线，却需要改去另一个既有工作区，请到 Agent Integration 建立或改用 All workspaces profile，不要请 Agent 用建立新工作区来冒充切换。

13.10 关闭视窗、重新开启与明确退出

如果存在已 exposed 的 Persistent connection，或已 exposed 的 Quick connection，关闭 Lantide 的视窗不一定等于停止 host：Lantide 可保留 backend 与 MCP listener 在背景，让已授权的外部 Agent 不被意外中断，同时销毁 renderer 以减少前端资源使用。

• macOS： 可从 Dock 重新开启视窗。
• Windows： 若有需要保留的 connection，视窗可收合至系统匣；首次在没有保留条件时关闭，会询问你要直接退出或保留在系统匣，并可记住选择。
• 若有未储存内容，会先显示确认：Close window and discard 或 Cancel。
• Quit Lantide、app update、crash 或系统终止会停止 backend / listener；外部 client 的后续请求会 fail closed。下次启动后，仅有效且设定为 exposed 的 Persistent profile 会恢复，client 必须重新 initialize。

13.11 常见问题与安全检查

为什么外部 Agent 连不上？

先确认全域 Enable MCP server 已开启、对应 Quick / Persistent connection 是 exposed、token 未过期／未 revoked。Persistent listener 显示 port collision 时，先释放占用程式后按 Retry；不要自行把 config 改成另一个 port。若你主动 Change local MCP port，必须更新外部 client 里保存的 URL。

为什么外部 Agent 需要重新 initialize？

这是预期的安全语意：app restart、Rotate、Revoke、Unexpose、global disable、明确 Disconnect session 或 workspace eviction 都会让旧 session 失效。重新 initialize 会建立新的 MCP session；这不等于你需要重新建立 profile 或取得新 token（Rotate / Revoke 除外）。

为什么内建 AI 面板不能输入？

只有目前工作区存在 active Execute / Admin writer session 时，内建 Agent 才会暂停以避免互相冲突。Active Observe session 不会阻挡内建 Agent。若 Header 显示绿色 external writer 状态，请让外部 Agent 完成、使用 link-off 中断 session，或结束 / unexpose 外部 connection，再使用内建 Agent。

All-workspaces 连上后，Agent 说工具很少／做不了分析？

工具较少是精简 catalog 的预期行为，不代表能力被删除。若仍是 unbound，可先用 search_capabilities 找长尾能力，搜寻不解锁工具。除新工作区导入（import_new）外，请先 select_workspace（或 Admin 建立并绑定），再使用 response 内嵌的 analysis_context；需要刷新时才呼叫 get_analysis_context，不需再 tools/list。再依回传的 invocation 使用 read/write invoker。这不是 Observe／Admin 权限被降级。见 §13.9。

我的旧 Activity 卡片还在，代表 Agent 还连著吗？

不代表。Activity history 是可追溯纪录；请看 session 的 Active / Ended 灯号。你可 archive 已结束 session，隐藏它的日常列表项目，不会删除 underlying audit。

为什么 connection 已 Expose，Header 却没有 external session？

Expose 只表示 endpoint/profile 已可接受外部 client，可能仍处于 exposed waiting。等 client 重新载入 MCP 并成功 initialize 后，Header 才会显示 active Observe 或 writer session。若长时间没有建立 session，请到 Agent Integration 检查全域开关、profile expiry/revocation、port 状态与 client config。

遇到 recovery 或 writer conflict 时该做什么？

持续性问题会留在 Agent Integration、Header 或相关状态面，不只靠短暂 Toast。依画面提供的主要 action 使用 Retry、Disconnect session、Unexpose、Rotate credential、Select workspace 或 Resolve conflict。Workspace conflict 会先显示阻挡的 writer session；只有你在外部对话明确同意后，Agent 才能指定该 session 重新尝试，系统不会静默驱逐或停用对方的 profile。诊断细节可保留 error code 供回报，但不需要手动修改 sidecar 或猜测 raw MCP 状态。

可以把 Persistent config 给同事或远端服务吗？

不建议。它是本机 loopback endpoint 与本机 bearer credential；它的设计目标是你自己电脑上的可信 MCP client，而不是远端共享 API。若要让别人使用，请在对方的 Lantide 安装上建立自己的 connection。

Beta 提示： MCP Server 功能目前仍处于产品 Beta 收束阶段。若遇到连线、recovery 或 client compatibility 问题，请保留不含 credential 的错误码、Activity 截图与重现步骤，再依 §21 回报。