安全边界与排障

基本原则

• 为每个 Agent 创建独立、最小 scope、最小环境范围、带到期时间的项目 Token。
• 不打印、复述、提交或记录 ENTMESH_API_TOKEN；stdout 只保留 JSON 结果，stderr 用于诊断。
• 只有 GET 可针对 429/5xx 做有限重试；所有写操作不自动重试。
• 更新、归档或运行控制前先读取当前资源和乐观锁版本；409 时停止并展示冲突。
• 分析/画像 Token 只能取消自己创建的任务。
• 高风险实验操作必须同时满足用户明确请求和 CLI --apply。

常见问题

Skill 未被宿主发现

确认三个目录直接位于宿主 Skills 目录下，并且每个目录包含 SKILL.md、agents/openai.yaml、scripts/ 和 references/。启动新会话后再测试显式 $entmesh-* 调用。

缺少环境变量

CLI 要求 ENTMESH_BASE_URL、ENTMESH_API_TOKEN、ENTMESH_PROJECT_ID、ENTMESH_ENVIRONMENT。Token 必须以 emt_ 开头；不要误用 pk_、sk_ 或 ck_ 采集密钥。

401 或 403

检查 Token 是否撤销/到期、项目和环境是否匹配、scope 是否足够，以及 analytics、user_profile、ab_testing 套餐是否有效。

409 冲突

资源已被其他用户或 Agent 修改。重新 GET 当前资源和 version，展示差异并请求用户决定；不要自动覆盖或重复提交。

任务失败、取消或过期

用对应 job/run/result-job 命令读取状态。报告错误码、阶段和数据状态，不静默重新提交；只有用户明确授权后才能创建新任务或重试失败 run。

数据为 incomplete/unavailable

不能把缺失事实日或未成熟数据补成零。报告覆盖起点、data_through、缺失事件/属性、物化 gap 和指标版本。

实验无法发布或部署

检查历史 baseline、Flag 环境占用、Targeting 分群快照、样本计划和权限。项目 Token 不能提供手工 baseline；遇到 experiment_baseline_required 时由 Owner/Admin 在 Panel 处理。

旧 Release 缺少 experiment

当前 v0.1.0 压缩包只包含 analysis/profile。按本手册从固定源码提交复制三个目录，不要把不同提交的 Skill 混装。

撤销与轮换

在“项目 → 项目设置 → 外部 Agent API Token”撤销旧 Token。更新宿主安全配置并启动新会话；确认新 Token 只读请求成功后，再恢复需要的写入工作流。