Files
streamline/docs/external-links.md
2026-11-16 17:26:44 -08:00

2.8 KiB
Raw Permalink Blame History

外部链接(飞书文档 / Figma)

任务描述里的飞书文档、Figma 链接由 shared/src/external_links.ts 识别,执行时 agent 通过节点上配置的 MCP 读取。 节点能读什么由卫星从自己的 MCP 配置推出来、随心跳上报(satellite/src/capabilities.ts,面板健康页可见)。

Figma:按提交人的 Token 读设计稿

每个节点在 MCP 配置里有一把自己的 Figma Token,过去所有 agent 都用它,节点账号打不开的稿子就读不到。 现在提交人可以在面板头像菜单 →「Figma Token」绑定自己的 Personal access token(服务端先用 GET /v1/me 验过才存)。 卫星起 agent 时向控制面要任务创建人的 Token(/api/internal/figma/user-token),放进该子进程的 FIGMA_API_KEY; 创建人没绑、或 Token 已被 Figma 拒绝,就什么都不注入,用节点 Token,和以前一样。不会退到别人的 Token。 开放平台建的单,「创建人」是建单那把 Key 的申请人(接口不收提交人,见 docs/openapi.md「归属与安全」)。

节点需要的一次性改动

Claude Code 会把父进程的环境变量传给 stdio MCP server,但 MCP 配置里写死的值优先于父进程。 所以节点要把 Figma MCP 改成「父进程有值就用父进程的,没有才用节点 Token」。2026-10-16 实测(Claude Code 2.1.301):

env 块里的 FIGMA_API_KEY 父进程有值时 server 拿到
不写 父进程的值
字面量 "figd_…" 字面量(用户 Token 失效)
"${FIGMA_API_KEY:-figd_…}" 父进程的值;父进程没有时取默认值

按节点的配置方式二选一:

  • 包装脚本(例如脚本从 Keychain 取 Token 再 exec Framelink):脚本里不要无条件赋值,改成

    FIGMA_API_KEY="${FIGMA_API_KEY:-$(security find-generic-password -a "$USER" -s figma-api-key -w 2>/dev/null)}"
    export FIGMA_API_KEY
    
  • .mcp.json / ~/.claude.json 里写死了值:

    "env": { "FIGMA_API_KEY": "${FIGMA_API_KEY:-figd_<节点 Token>}" }
    

    args 里用了 --figma-api-key=<值> 的同理,改成 --figma-api-key=${FIGMA_API_KEY:-<节点 Token>} 或去掉该参数改走 env。

卫星不改这些文件(同 DeviceSim skill 的规矩:节点自己维护配置)。不改的节点行为不变,继续用节点 Token。 改完后自己确认一次:用一份只有你能打开的稿子建单,绑定前 agent 拿到 403,绑定后能读。

风险

Token 放在 agent 的环境里,agent 运行期间可以用 shell 读到它。绑定时请只给 file_content:read 和 current_user:read(后者只用来验证 Token 并显示是谁的)、有效期选短,过期后重新绑定。 目前只覆盖 AGENT_MODE=claude;codex / cursor 模式从各自的配置加载 MCP,不经过这条路径。