脚本执行与成员授权

工作区管理员可为成员开通脚本执行：让智能体在对话中按技能里的 Python 脚本，生成或修改 Excel / Word / PPT 等可下载文件。权限分平台、工作区、成员三层，与联网请求类似。

来源 help/admin-ops/script-execution.md

工作区管理员可为成员开通 脚本执行：让智能体在对话中 按技能里的 Python 脚本，生成或修改 Excel / Word / PPT 等可下载文件。权限分平台、工作区、成员三层，与 联网请求 类似。

能做什么

智能体执行技能 scripts/ 目录下的脚本（如 main.py）
典型结果：导出 .xlsx、生成 .docx、制作 .pptx 等附件
若要 改已有 Office 附件，建议同时开通 办公文档读取，并在脚本里传入源文件

脚本逻辑写在 技能中心；本页说明 谁有权执行，不是教你怎么写 Python。

谁可以配置

角色	能做什么
平台运维	在 `mindlink.json` 打开平台总开关（见服务端配置）
工作区所有者 / 管理员	在 `工作区协作` → 助手能力包 → 脚本执行中开通，并为每位成员单独授权
普通成员	查看自己是否被授权；未开通时可提交能力申请

如何查看是否已允许

脚本执行须 平台、工作区、成员 三层都满足，对话里才能按技能跑脚本。可按角色对照下面路径查看。

平台运维

在 backend/mindlink.json（勿提交 Git）查看：

"agent_script_tool": {
  "enabled": true,
  // ...
}

enabled 为 true 且改配置后 已重启后端 → 平台层允许
也可用环境变量 AGENT_SCRIPT_TOOL_ENABLED=1（会覆盖 JSON）
平台未开时，全站均不能执行脚本，与工作区卡片是否显示「已开通」无关

详情见服务端配置第 3.11 节。

工作区管理员

进入 工作区协作 → 助手能力包
看 脚本执行 卡片状态：未开通 / 已到期 / 已开通
点击卡片打开设置对话框（布局与 联网请求 相同）：

- 顶部开通开关 → 工作区是否允许 - 左侧 工作区设置 → 有效期、前置能力说明 - 左侧 成员脚本授权 → 各成员是跟随工作区、禁止使用，还是单独授权

某成员「工作区已开但仍不能用」时，在 成员脚本授权 里点该成员，看是否为 禁止使用，或 单独授权 下是否勾选了对应技能。

普通成员

同样进入 助手能力包 → 脚本执行 卡片
点击卡片查看详情，常见提示：

- 工作区未开通或已到期 → 可 提交能力申请 - 「本工作区已开通脚本执行，但您尚未被授权使用」→ 工作区已开、个人未授权 - 「您有单独的脚本执行策略」→ 管理员为您单独配置，可能与工作区默认不同

对话中若助手说明不能执行脚本，可按上表联系管理员，或对照下方常见问题

三层对照（排查用）

层级	谁配置	怎么查
平台	运维	`mindlink.json` → `agent_script_tool.enabled`
工作区	管理员	助手能力包 → 脚本执行 → 开通 + 有效期；须已开基础文档工具
成员	管理员	脚本执行对话框 → 成员脚本授权 → 该成员授权方式

开通步骤（管理员）

1. 平台总开关

运维在 backend/mindlink.json 中配置（勿提交到 Git）：

"agent_script_tool": {
  "enabled": true,
  "timeout_sec": 60,
  "max_output_bytes": 10485760,
},

改后 重启后端。也可用环境变量 AGENT_SCRIPT_TOOL_ENABLED=1（会覆盖 JSON）。

平台未开启时，全站智能体均不能执行脚本，与工作区是否开通无关。

2. 工作区能力包

进入 工作区协作
打开 助手能力包 → 卡片 脚本执行
打开开通，按需设置 有效期

前置条件：

须已开通 基础文档工具（脚本产出的文件需注册为可下载附件）
若要读取或修改已有 Word/Excel/PPT 附件，建议同时开通 办公文档读取

3. 成员脚本授权

在 脚本执行 设置对话框中，左侧选 成员脚本授权（与 联网请求 的成员对接同一布局：左侧成员列表，右侧详情）：

左侧选成员，右侧设置 授权方式

授权方式	含义
跟随工作区	工作区已开通即可用（默认）
禁止使用	该成员不能执行脚本，即使工作区已开通
单独授权	从列表勾选允许执行的技能（须技能已声明脚本且含 `scripts/.py`）；全部勾选* 表示不限制；还可控制是否允许临时脚本

建议：

大多数成员用 跟随工作区
HR、财务等需要导出报表的岗位用 单独授权，只勾选相关技能（如导出 Excel 的技能）
允许临时脚本 默认关闭；仅在高信任场景开启

与技能的关系

智能体不会随意运行任意代码，须同时满足：

成员已被授权脚本执行
对话中命中了带脚本的 工作区技能
技能正文含 ## 脚本执行，或在技能说明里声明可执行脚本

在 技能中心 创建技能时，可点 描述创建，形态选 以脚本为主；生成后在左侧文件树编辑 scripts/。

撰写要求见怎么写好工作区技能第 8.4 节。

成员侧会看到什么

已授权：对话中可请智能体「按某某技能导出 Excel」等；成功后会得到 可下载附件
工作区已开通但未授权：能力包对话框或对话中助手会说明需联系管理员，在 脚本执行 → 成员脚本授权 里配置
工作区未开通：可在能力包页 提交申请，或请管理员开通

安全说明

脚本在服务端 受限环境 中运行（超时、产出大小上限、禁止联网类语句等）
密钥不要写进脚本；对接外部系统仍用 联网请求 + 对接授权
允许临时脚本 风险较高，默认关闭

后端 Python 与依赖（运维）

脚本在 Cadau 后端进程所在机器 上运行（不是用户浏览器里）。

安装 Python 3.10+，并保证命令行可执行 python 或 py -3。
可选：设置环境变量 MINDLINK_PYTHON 指向解释器绝对路径（例如 C:\Python312\python.exe）。
技能可在 scripts/requirements.txt 声明依赖；Cadau 对 reportlab、pypdf、matplotlib、pillow 等白名单包会在执行前 自动 pip 安装 到每次脚本运行的临时目录（.packages），不是改用户本机 Python。.xlsx/.docx/.pptx 禁止由脚本产出，须用 办公文档工具（office_document / OfficeCLI）。
对话中改脚本：智能体可用 skill_script_read / skill_script_write 更新 scripts/*.py（skill_update 只改 Markdown 正文）；改后须 run_script 验证，output_files 非空才算成功。
一键补齐默认技能（工作区管理员）：POST /api/v1/workspaces/{工作区id}/seed-office-script-skills 会幂等创建演示文稿（ppt-deck-builder，走 OfficeCLI）与简单 PDF 脚本技能；本地亦可用 go run ./cmd/seed-office-skills -workspace <id>。
国内网络：若自动安装报 ConnectionResetError / No matching distribution found，在 mindlink.json 配置 pip 镜像，例如：

``json "agent_script_tool": { "pip_index_url": "https://pypi.tuna.tsinghua.edu.cn/simple" } ` 或设置环境变量 MINDLINK_PIP_INDEX_URL（也可沿用系统 PIP_INDEX_URL`）。改后 重启后端。

安装系统软件、改 PATH/注册表 等仍须运维手动处理；智能体遇到 error_code=python_not_found 时应向用户说明，而不是假装已生成文件。

常见问题

现象	优先检查
助手说不能执行脚本 / 没有相关能力	平台 `agent_script_tool.enabled`；工作区脚本执行是否开通
工作区已开通，某成员仍不能用	该成员是否为禁止使用；或单独授权下是否勾选了该技能
助手说技能未声明脚本	技能是否有 `scripts/.py`，正文是否有 ## 脚本执行*
脚本报错找不到模块（exit 9009 / ModuleNotFoundError）	后端是否已安装 Python 3.10+（Windows 需 `python`/`py` 在 PATH，或设置 `MINDLINK_PYTHON`）；Cadau 会对白名单库自动 `pip install`
pip 安装失败 / ConnectionResetError / 国内连不上 PyPI	配置 `agent_script_tool.pip_index_url` 或 `MINDLINK_PIP_INDEX_URL` 为国内镜像，重启后端
无法读取要修改的 Word/Excel	工作区是否开通办公文档读取
只能导出 CSV，不能导出 xlsx/docx/pptx	工作区是否开通办公文档工具，助手是否用 office_document（不是 run_script）
不能导出简单 PDF	是否已配置 PDF 脚本技能并成功 run_script；依赖 reportlab 是否在白名单内