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

49 lines
2.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 外部链接(飞书文档 / 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):脚本里不要无条件赋值,改成
```bash
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` 里写死了值**:
```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,不经过这条路径。