Workspace 指令助手（Command Palette Agent）
2026-2026 · Side Project · next-blog
安全可控的Workspace指令助手，实现自然语言到业务操作的精准映射
背景
为私人Workspace打造⌘K自然语言指令助手，让用户用口语完成待办、面试记录、密钥库等写操作，无需记菜单路径或API字段
我的职责
独立设计并实现整个系统架构，包括UI层、BFF层、Python agent-service层以及数据流设计
技术深挖
⌘K 自然语言指令助手
问题：用户需要通过自然语言完成 Workspace 中的写操作，但传统菜单路径和 API 字段记忆成本高，且需要确保安全性和可审计性。
方案与实现：设计一个 ⌘K 触发的自然语言指令助手，将用户口语转换为具体操作；采用双脑架构分离 UI 与执行逻辑，确保浏览器端不接触内部 Agent Key；整个执行链路可审计，关键步骤需要人工确认，保证操作安全可控。
我的贡献：独立设计并实现了整个指令助手架构，定义了安全边界和人工确认流程，确保用户操作既自然又安全。
双脑架构设计
问题：需要在保证安全性的同时实现自然语言处理能力，且需要分离前端与后端逻辑以降低安全风险。
方案与实现：采用双脑架构，UI 层仅负责用户交互和请求转发，Python agent-service 负责复杂的 LangGraph 编排逻辑；Next.js BFF 作为中间层处理鉴权和请求转发，形成清晰的职责分离；所有业务写操作都在 Next internal API 中执行，确保数据安全。
我的贡献：设计了完整的双脑架构方案，明确了各层职责和安全边界，确保系统安全性和可维护性。
UI 层与 BFF 交互
问题：前端需要安全地与后端 agent-service 交互，同时支持预览和确认执行两种模式。
方案与实现：UI 层的 CommandPalette 组件仅通过 POST /api/workspaces/agent 与 Next.js BFF 通信；BFF 负责转发请求并处理响应，支持 run 预览和 confirm 执行两种模式；所有请求都经过鉴权处理，确保只有合法请求能到达 agent-service。
我的贡献：实现了前端与 BFF 的安全交互机制，设计了预览和确认两阶段执行流程，提升用户体验。
LangGraph 编排流程
问题：需要设计一个能够处理复杂多步骤任务的工作流，并在关键节点引入人工确认。
方案与实现：使用 Python LangGraph 构建 agent-service，实现 plan → interrupt 等人确认 → execute 的编排流程；在 execute 前设置 interrupt 节点暂停执行，等待用户确认；通过精心设计的节点转换逻辑确保任务按预期执行。
我的贡献：实现了基于 LangGraph 的任务编排逻辑，设计了人工确认节点，确保关键操作得到用户授权。
安全边界设计
问题：需要确保浏览器端无法直接访问敏感资源，同时保持功能完整性。
方案与实现：建立「脑在手外、手在 Next 内」的安全边界，Python agent-service 负责决策但不直接操作数据；Next internal API 在鉴权后执行具体的业务写操作（todo/interview/vault 等）；所有敏感操作都经过鉴权和人工确认双重保障。
我的贡献：设计了完整的安全边界方案，确保敏感数据不会被前端直接访问，同时保持系统功能完整性。
Capability RAG 能力检索
问题：需要让系统能够动态理解和响应用户的自然语言指令，并准确匹配到对应的功能能力。
方案与实现：启动时扫描 agent-actions.manifest.yaml 文件生成能力目录；使用 Chroma 向量数据库和智谱 Embedding 对能力描述进行向量化存储；当用户输入指令时，通过语义检索匹配最相关的功能能力，确保准确理解用户意图。
我的贡献：实现了基于 RAG 的能力检索系统，使系统能够动态扩展功能并准确理解用户自然语言指令。
能力候选排名与收窄
问题：当检索到多个可能匹配的能力时，需要有效筛选出最相关的几个选项，避免 LLM 上下文过载。
方案与实现：实现 rank_action_ids 算法将检索到的能力 chunk 聚合为 top-5 action 候选；通过相关性评分和业务规则对候选进行排序；将收窄后的候选列表提供给 LLM，减少 prompt 上下文长度，提高决策准确性。
我的贡献：设计了能力候选排名算法，平衡了检索准确性和上下文效率，确保 LLM 能在有限上下文中做出最佳选择。
LLM Tool Calling 与参数校验
问题：需要让 LLM 从候选能力中选择最合适的工具并正确填充参数，同时防止参数错误或安全漏洞。
方案与实现：使用智谱 function calling 让 LLM 从 top-5 候选中选择工具并填充参数；实现 Registry 校验机制，确保 manifest 中定义的 action 与参数类型匹配；严格禁止 LLM 编造未定义的 action，保证系统安全性和一致性。
我的贡献：实现了完整的工具调用与参数校验流程，确保 LLM 的选择和参数填充符合系统规范和安全要求。
智谱 function calling 与参数校验
问题：如何确保 LLM 从候选 action 中正确选择工具并填充参数，同时防止编造未定义的 action
方案与实现：通过智谱 function calling 实现 tool 选择与参数填充，结合 manifest 文件定义的 action 注册表进行严格校验。系统首先扫描 agent-actions.manifest.yaml 生成能力目录，然后使用 Chroma 和智谱 Embedding 进行语义检索，rank_action_ids 将候选 chunk 聚合为 top-5 action。Registry 组件会校验 manifest 中定义的参数类型，确保 LLM 只能使用已注册的 action 并正确填充参数，禁止编造未定义的 action。
我的贡献：设计了 manifest 注册表与参数校验机制，确保 LLM 调用安全可控，防止越权操作。
Human-in-the-loop 交互设计
问题：如何在自动化执行前确保用户对操作意图的确认，提升安全性与用户体验
方案与实现：通过 LangGraph interrupt 机制在执行前暂停流程，UI 展示 action 摘要与参数预览，等待用户确认后才恢复图执行。这种设计确保用户始终对关键操作有最终控制权，同时提供清晰的预览信息帮助用户理解即将执行的操作内容。
我的贡献：实现了 interrupt 机制与 UI 预览组件的联动设计，确保用户在关键节点有确认机会。
LangGraph interrupt 执行流程控制
问题：如何在长链路执行中实现人工确认点，同时保持流程的连贯性
方案与实现：在 LangGraph 工作流中设置 interrupt 节点，在 execute 阶段前暂停执行。UI 通过 WebSocket 或轮询机制获取中断状态，展示操作摘要与参数预览。用户确认后，通过 API 信号恢复图执行，否则取消操作。这种设计实现了「脑在手外、手在 Next 内」的安全边界，确保关键操作需人工确认。
我的贡献：设计了 interrupt 节点与恢复机制，实现了安全与效率的平衡。
Planner system prompt 场景区分
问题：如何让 LLM 区分易混场景（如改标题 vs 新建、recent 定位 vs oldLabel），提高意图识别准确性
方案与实现：为 planner 设计精细化的 system prompt，明确区分不同场景的语义差异。针对 todo、interview、vault 等易混场景，定义清晰的指令模板，包括操作类型判断（修改/创建）、对象定位策略（recent/oldLabel）等关键维度。通过示例和约束条件引导 LLM 正确理解用户意图，减少场景混淆。
我的贡献：设计了场景区分的 prompt 策略，提高了 LLM 对复杂语义的理解准确性。
异步任务管理与导航保护
问题：如何处理长链路任务的取消与页面跳转，确保用户体验连续性
方案与实现：实现异步任务 Dock 组件显示任务进度，配合 WorkspaceLeaveGuard 监听页面离开事件。任务执行期间，用户可随时取消；若尝试离开页面，系统会提示任务状态并允许跳回来源页。通过任务状态持久化与 WebSocket 通知，确保跨页面操作的一致性。
我的贡献：设计了任务状态管理与页面跳转保护机制，提升了长链路操作的用户体验。
高频 Workspace 写操作自然化入口
问题：如何为 Todo、面试记录、密钥库等高频操作提供自然语言入口，降低使用门槛
方案与实现：通过 Command Palette 实现统一的自然语言入口，结合双脑架构（Next.js BFF + Python agent-service）处理用户指令。系统能理解口语化表达，自动映射到对应的业务操作，无需用户记忆菜单路径或 API 字段。与职业档案、知识库等模块共用权限与任务规范，确保操作一致性。
我的贡献：设计了自然语言到业务操作的映射机制，覆盖了多个高频 Workspace 写操作场景。
能力清单可扫描扩展机制
问题：如何实现新 action 的即插即用，无需修改核心代码即可扩展系统能力
方案与实现：通过 agent-actions.manifest.yaml 文件定义能力清单，系统启动时扫描并生成能力目录。新 action 只需在 manifest 中注册即可被 RAG 检索到，实现动态扩展。结合 Chroma 和智谱 Embedding 进行语义检索，确保新能力能被正确匹配和调用。
我的贡献：设计了 manifest 驱动的扩展机制，使系统能灵活支持新 action 的添加。
双脑架构安全边界设计
问题：如何在保持功能灵活性的同时确保系统安全，避免内部 Agent Key 泄露
方案与实现：采用双脑架构设计，UI 层仅调用 Next.js BFF，Python agent-service 负责 LangGraph 编排。Next.js internal API 在鉴权后执行业务写库，形成「脑在手外、手在 Next 内」的安全边界。执行链路可审计、可人工确认，确保浏览器侧永不接触内部 Agent Key。
我的贡献：设计了双脑架构的安全边界，实现了功能与安全的平衡。
Workspace 权限与任务规范共享
问题：如何让指令助手与多个现有模块（职业档案、知识库、模拟面试等）共享统一的权限管理和任务规范，确保操作一致性和安全性。
方案与实现：设计了一套统一的 Workspace 权限模型，将指令助手的权限验证逻辑与现有模块对齐，通过 Next.js BFF 统一鉴权中间件处理所有写操作请求；任务规范方面，定义了标准化的任务数据结构，包括任务类型、状态、元数据等字段，确保不同模块间任务数据格式一致；实现了一套通用的任务处理流程，包括任务创建、更新、状态变更等操作，通过模块化设计使指令助手复用这些通用功能。
我的贡献：我主导设计了统一的权限与任务规范接口，并实现了与现有模块的集成方案，确保了指令助手能够无缝融入现有 Workspace 生态。
能力亮点
系统架构设计
设计'脑在手外、手在Next内'的双脑架构，确保安全边界与执行链路可审计
AI Agent工程实践
实现基于LangGraph的编排流程，结合RAG检索与function calling实现精准能力匹配
用户体验设计
通过Human-in-the-loop机制与异步任务管理，确保长链路操作的可控性与可取消性
架构 / 流程
双脑架构实现安全可控的Workspace指令助手，UI层与Python agent-service分离，通过Next.js BFF协调，结合RAG检索与LangGraph编排实现自然语言到业务操作的精准映射
技术栈
难点与方案
难点：安全边界与权限控制
方案：设计双脑架构，UI层仅调用Next.js BFF，Python agent-service负责编排，Next internal API执行业务写库
效果：浏览器侧永不接触内部Agent Key，执行链路可审计、可人工确认
难点：自然语言到业务操作的精准映射
方案：实现Capability RAG系统，通过Chroma+智谱Embedding做语义检索，rank_action_ids收窄候选，function calling选择工具
效果：避免编造action，确保操作符合业务规范
难点：长链路操作的用户体验
方案：LangGraph interrupt在execute前暂停，UI展示action摘要与参数预览，用户confirm后才恢复执行
效果：用户可随时取消或确认操作，提高系统可控性
成果
- 覆盖Todo、面试记录、密钥库等高频Workspace写操作的自然语言入口
- 能力清单可扫描扩展，新action注册manifest即可被RAG检索
- 与职业档案、知识库、模拟面试等模块共用同一Workspace权限与任务规范