【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载本篇文章以 SuperPlane 开源仓库中 inline-config-assistant.md 产品需求文档PRD为骨架结合仓库内已有的 scoped JWT、表达式自动补全示例构建与 Agents API 路由注册等源码证据系统讲解这一「内联配置助手」的设计目标、信任边界、公共 API、Python Agent 服务、前端集成与验收标准。读完你将掌握如何在 SuperPlane 工作流节点配置侧栏中实现「自然语言描述意图 → 得到单个字段建议值 → 一键应用」的完整闭环并理解它与 AI Builder 会话式助手的本质区别。Overview什么是内联配置助手该 PRD 描述的是一套in-config配置内的辅助能力在工作流节点的配置侧栏sidebar中针对单个配置字段提供一种无状态stateless、逐字段的流程——用户用自然语言描述想得到什么系统返回一个建议值suggested value用户确认或丢弃。建议由一条**专用dedicated**的 LLM 路径产生PydanticAI Anthropic运行在 SuperPlane 公共 API 之后。它不是AI Builder 聊天、不是会话历史、也不是会改动画布的工具。它不持久化对话状态也不取代表达式自动补全autocomplete与本地预览。从实现约束看助手本质上是一次不带任何工具no tools的 LLM 调用上下文全部来自system prompt、instruction用户指令和field_context_json字段元数据、当前值、表达式负载形状等。canvas_id/node_id只用于鉴权auth与路由routingAgent 侧不会据此去抓取数据。问题陈述为什么需要窄幅的辅助面重度用户在编辑节点配置——尤其是表达式expressions和长文本时必须熟悉 expr-lang 的约定、负载payload形状以及组件语义。即使有自动补全和预览反复试错仍然很慢。因此目标是一个狭窄的辅助面不打开完整 Builder、不进入独立的聊天产品直接在字段上完成「描述意图 → 看到建议字符串 → 应用到当前字段」。Goals核心目标在流程Settings / 配置 UI上对符合条件的字段提供一次性的 suggest 能力并受产品开关与权限控制。保持信任边界清晰浏览器 → 已认证的 SuperPlane API → 携带scoped JWTpurpose: config-assistant与 AI Builder 的 token 相互独立的 Agent HTTP 调用。运行一个小型 Python Agentagent/src/config_assistant/采用结构化输出value可选explanation不导入 Builder 的agent.py不共享 Agent 工具循环无工具——上下文只通过field_context_json外加 instruction 与 system prompt传入。在前端把客户端封装集中在lib/configAssistantSuggest.ts与useConfigAssistantSuggest避免请求形状与错误处理散落在 UI 各处。Non-Goals明确不做的事在助手面板内流式输出 tokenv1 采用 unary JSON。与 AI Builder共享聊天记录或复用 Builder 的流式路由。面板内的多轮对话每次点击Generate相互独立。近期内基于目录catalog在共享Fieldschema 上增加逐字段开关——见 Decisions目前只做前端类型 allowlist。服务端对field_context_json中每个 secret 做脱敏超出大小限制以外的加固可能后续跟进。API 中以结构化/非字符串作为核心value例如 JSON 对象作为主契约v1 响应保持字符串需要时 UI 侧自行做类型转换。Decisions关键决策组织级「AI 关闭」对齐 AI Builder当组织禁用了 AI 能力时字段建议必须以403或等效状态失败而不是静默调用模型。字段资格eligibility维持前端 allowlistisConfigAssistantSupportedField位于web_src/src/lib/configAssistantFields.ts在产品稳定之前暂缓目录级Fieldschema 的 opt-in 机制。多轮 / 流式面板不做多轮v1不流式——单条指令进、单条结构化响应出。响应形状value在公共 API 与 Agent 契约中全程保持字符串v1 不需要并行的结构化值字段。范围与语义可支持的字段前端 allowlist只有在功能已启用且字段通过isConfigAssistantSupportedField时才会展示助手。允许的类型与约束归纳如下规则内容允许类型expression、string、text、url、cronintegration-resource仅**单值非 multi**字段助手只在Expression 标签页模式出现不在 Fixed 选择器模式出现永不支持sensitive: true的字段不支持select、multi-select、number、boolean固定目录或自然语言体验不佳关于 allowlist 的设计意图被排除的类型要么有固定目录select/multi-select要么数值/布尔值用自然语言描述没有收益number/boolean要么涉及敏感数据sensitive: true。PRD 明确将「目录级 schema 开关」推迟到产品稳定之后因此短期内web_src/src/lib/configAssistantFields.ts就是字段资格的唯一事实来源。UX 契约InlineFieldAssistant在适用的字段标签行旁显示触发器sparkle 图标。面板流程指令文本域instruction textarea→Generate→ 只读的建议值 可选说明explanation→Use this value/ 取消。应用建议值走正常的字段onChange保存时的校验仍然作为最后防线。请求负载概念层公共 API 接收canvas_id、node_id、instruction和field_context_jsonJSON 字符串。field_context_json必须携带模型在无工具条件下提出一个好的字符串建议所需的全部信息至少包括结构化的字段元数据由buildConfigAssistantFieldContext构建name、label、type、description、placeholder、required存在时含typeOptions。正在编辑字段的currentValue或等价物。对于expression及同类字段提供autocompleteExample或等价物——即 Monaco 自动补全使用的同一形状命名的上游节点负载、__root、__previousByDepth、__nodeNames等这些由前端从工作流图中客户端推导Agent 在运行时不抓取。Go 侧会强制大小上限instruction 长度按 runes 计与field_context_json最大字节数。这里可以印证仓库中已经存在的自动补全示例构建实现buildAutocompleteExampleObj.ts 中正是以相同思路在客户端组装示例对象——例如第 340 行exampleObj.__root exampleObj[rootNodeId]、第 344 行exampleObj.__previousByDepth previousByDepth、第 399 行namedExampleObj.__nodeNames nodeMetadata并注入__app、__run、__order、__workspace等全局示例第 380-383 行。PRD 要求的autocompleteExample正是复用这套客户端推导机制只是把它序列化进field_context_json交给模型而不是喂给 Monaco。响应valuestring建议的字段值成功时必须非空。explanation可选简短的人类可读说明。公共 APIGoHTTPPOST /api/v1/agents/suggest-fieldgRPC-Gateway 转发给ConfigAssistant.SuggestConfigurationField或在 agents URL 前缀下等效注册——实现细节。Auth与应用其余部分相同的会话鉴权。AuthZ用户必须被允许更新目标画布与编辑工作流的门槛一致同时组织 AI 已启用对齐 AI Builder组织禁用 AI 时返回403。Agent 调用铸造短时 JWT携带purpose: config-assistant与 Builder 的agent-builder区分开把 JSON 转发给 Agent HTTP 服务内部路径可保持如{AGENT_HTTP_URL}/config-assistant/suggest——这是 SuperPlane 内部路径不是公共 API 路径。Scopes包含canvases:read:canvas_id以及按实现加入的 org/integration 读检查使 Agent 能校验 JWT 且不引入 Builder 专属语义。Proto 与生成代码可放在protos/config_assistant.proto与pkg/protos/config_assistant/下对外文档化的公共 URL 是/api/v1/agents/suggest-field。仓库证据pkg/jwt/scoped.go已经实现了携带Purpose字段的 scoped token 机制——ScopedTokenClaims包含Purpose第 23 行、GenerateScopedToken强制 purpose 非空第 44-46 行、ValidateScopedToken校验 token type、audience 与 purpose第 71-123 行。同时 protos/agents.proto 展示了 agents 服务下 gRPC-Gateway 的注册范式例如GET /api/v1/agents/canvases/{canvas_id}/chat、POST /api/v1/agents/canvases/{canvas_id}/chat/reset说明suggest-field在 agents URL 前缀下注册是现有惯例的自然延续。Agent 服务Python挂载与 Builder 共用同一个 FastAPI 应用路由从ai.web挂载到内部路径如POST /config-assistant/suggest。校验JWT 使用共享校验器agent/src/ai/jwt.py带 purpose 白名单agent-builder、config-assistant。运行PydanticAI Agent 位于agent/src/config_assistant/模型取自CONFIG_ASSISTANT_AI_MODEL或AI_MODELAnthropic 需要ANTHROPIC_API_KEY。无Builder 工具、该路径无工具调用对 instruction 解析后的field_context_json system prompt做单次 LLM 推理。v1 中该路径不依赖agent.py。授权与配置SuperPlane 侧目标画布的 canvasupdate权限与 AI Builder 一致的 org 级 AI 策略AGENT_HTTP_URL必须解析到 Agent HTTP 服务——在 Docker Compose 中要使用 Agent 服务主机名不能在应用容器内用localhost。Agent 侧JWT_SECRET必须与应用一致可选独立模型字符串用于相对 Builder 做成本/延迟调优。仓库证据pkg/public/middleware/auth.go中authenticateUserByScopedToken第 383 行起调用jwtSigner.ValidateScopedToken并把校验通过的 claims 写入 contextScopedTokenClaimsContextKey第 240-241 行这正是「Agent 侧用同一把JWT_SECRET校验 scoped token」所依赖的共享机制。而 purpose 隔离的必要性也能在测试中找到印证scoped_test.go 使用Purpose: agent-builder断言 claims 往返一致runner_planning_session_test.go 中携带purpose: other的 token 访问 runner 路由直接返回401——说明「错误的 purpose 不能复用」这一约束在仓库里已有先例。前端集成GateVITE_ENABLE_INLINE_CONFIG_ASSISTANT以及只读侧栏控制可见性服务端 AuthZ 才是权威。HookuseConfigAssistantSuggest为SettingsTab→ConfigurationFieldRenderer提供isFieldAssistantEnabled与getSuggestFieldValue(field, getCurrentValue)。Mock 路径当 canvas/node/org 上下文缺失时客户端使用一个短延迟 mock让 Storybook / 部分上下文仍能演练 UI。示例流程用户在启用助手的流程画布上打开一个节点。用户聚焦一个expression字段点开 sparkle输入「filter to open PRs only」过滤出仅未关闭的 PR。UI 调用POST /api/v1/agents/suggest-field携带field_context_json含 autocomplete 风格的上游负载与 instruction。Go 侧鉴权canvas update org AI 允许后铸造config-assistantJWTPOST 给 Agent。Agent 执行一次模型调用——无工具——基于 instruction context JSON system prompt返回{ value, explanation }用户确认后值写入配置autosave/save 规则照常生效。验收标准符合条件的字段展示助手sensitive与不允许的类型不展示。成功的 suggest 返回非空字符串value错误在面板内呈现不影响侧栏其余部分。Builder JWT 不能用于 config-assistant 的 Agent 路由反之亦然purpose隔离。没有 canvasupdate权限的用户无法对该 canvas 获得成功的 suggest。组织 AI 被禁用时与 AI Builder 同一策略suggest 返回403或文档化的等效状态。Agent 与应用共享 JWT 签名密钥错误配置会表现为可从日志排查的明确 503/4xx 行为。风险与缓解风险Context JSON 向模型泄露 secrets 或 PII。缓解排除敏感字段限制负载大小文档化信任边界后续在 Go 侧增加脱敏。风险模型给出非法表达式或错误类型。缓解用户必须确认保存时已有校验兜底在agent/src/config_assistant/system_prompt.txt中编写提示词约束。风险成本 / 滥用。缓解instruction 与 context 大小限制限流与 Builder 对齐的 org AI 禁用开关。风险运维方错误配置AGENT_HTTP_URL。缓解文档化 Compose 默认值Go 侧记录转发失败日志。相关实现线索该 PRD 追踪的实现工作见仓库 issue #3714 的关联记录。结合本文梳理落地时你可以沿着以下仓库路径快速定位现有设施pkg/jwt/scoped.goPurpose字段与 scoped token 的生成/校验是config-assistantpurpose 隔离的底层机制pkg/public/middleware/auth.goscoped token 的请求级校验与 claims 注入pkg/jwt/scoped_test.go 与 pkg/public/runner_planning_session_test.gopurpose 校验行为的测试佐证protos/agents.proto/api/v1/agents/*路由的 gRPC-Gateway 注册范式buildAutocompleteExampleObj.ts__root、__previousByDepth、__nodeNames等表达式自动补全示例对象的客户端构建实现是autocompleteExample的直接来源。需要注意的是截至本仓库当前快照PRD 中列出的web_src/src/lib/configAssistantFields.ts、agent/src/config_assistant/、protos/config_assistant.proto等路径尚未出现在源码树中本文对它们的描述均以 docs/prd/inline-config-assistant.md 的规划为准而 purpose 隔离、autocomplete 示例构建、agents 路由注册等基础设施已可在上述既有源码中验证。赞分享【免费下载链接】superplaneOpen source factory for one-shot engineering项目地址https://gitcode.com/gh_mirrors/su/superplane点击查看免费下载相关推荐OpenPencil AI Chat 深度指南内置 AI 设计助手、多模型配置与工具调用机制OpenPencil AI Chat 深度指南内置 AI 设计助手、多模型配置与工具调用机制 OpenPencil 是 AI 原生的开源设计编辑器内置的 A前端桌面应用AI 应用MCP 服务Pydantic 字段(Field)详解模型字段的高级配置指南Pydantic 字段 Field 详解模型字段的高级配置指南 引言 在 Python 数据验证和设置管理领域Pydantic 的 Field 功能提供了强后端序列化ArcKit /arckit:story实战八章节叙事自动生成项目完整历史档案ArcKit /arckit:story实战八章节叙事自动生成项目完整历史档案 在 ArcKit 企业架构治理框架中 /arckit:story 命令只需输CLI开发工具企业应用AI 技能MCP Clients上一篇gh_mirrors/tool/tools 开发环境配置从源码编译到贡献代码的终极指南下一篇Compose Multiplatform Web字体渲染优化跨平台一致性解决方案深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考