全局 JS 设置
衡石系统提供了全局 JS 设置功能，用户可以通过自定义 JS 代码实现系统的个性化需求，如使用第三方统计工具对系统平台的 PV 、UV 进行监测。
除了直接操作 DOM，系统还会在运行时注入一些可复用 Hook，适合更稳定地做文案覆盖和 Data Agent 能力扩展。
遇到需求时先怎么选
很多客户第一次接触全局 JS 时，最容易遇到的问题不是“代码怎么写”，而是“不知道该用哪种能力”。可以先按下面这张表选型：
| 需求 | 优先使用 | 为什么 | 常见案例 |
|---|---|---|---|
| 隐藏按钮、隐藏 tab、调整颜色/字体/间距 | 全局 CSS | 这是纯视觉层改动，用 CSS 更直接，也更稳定。 | 隐藏“忘记密码”、隐藏“导出”按钮、隐藏部分图表类型 |
| 替换系统固定文案、欢迎语、提示语 | window.customI18nPostProcessor() | 按 i18n key 改文案，不需要轮询 DOM，维护成本更低。 | 修改 Copilot 欢迎语、统一按钮文案、统一提示语 |
| 页面渲染后按路由或运行状态改内容 | 全局 JS | 需要监听路由变化、等待页面渲染、按上下文动态处理。 | 图表无数据时替换提示语、固定浏览器 tab 标题、按页面位置隐藏下拉选项 |
| 登录/登出跳转、接第三方脚本、监听页面事件 | 全局 JS | 这类需求依赖浏览器事件或外部脚本，不属于 CSS 能力范围。 | 登出后跳第三方地址、SSO 租户屏蔽登录页、接百度统计 |
| 让 Data Agent 访问企业知识库、内部 API、搜索引擎 | window.heisenberg.createTool() | 这是给 Agent 扩展“能力”，不是改页面展示。 | 接内部知识库、调用工单接口、查询外部搜索服务 |
内置 Hook
| Hook | 用途 | 说明 |
|---|---|---|
window.customI18nPostProcessor(value, key, options) | 按 i18n key 覆盖页面文案 | 在系统完成 i18n 查找后调用；不需要改动的 key 直接返回原始 value。 |
window.heisenberg.createTool(tool) | 给 Data Agent 注册自定义 Tool | 代码同样写在“系统设置 → 全局 JS”中，保存并刷新后在网页端 Data Agent 的 Agent 模式下生效。完整参数说明见 Data Agent 调试。 |
使用场景
场景1：接第三方统计或监听页面事件
这一类需求通常是“页面打开后要额外执行一段逻辑”，例如：
- 接百度统计、神策、Google Analytics 等第三方统计脚本。
- 用户点击退出登录后，自动跳转到企业统一门户或其它第三方页面。
- 监听
hs_urlchange、资源请求、浏览器 history 变化，做路由级联动作。
示例：增加百度统计
下图示例中使用 js 代码引用了百度网站统计功能对系统进行分析，开启 JS 功能后，可以在百度系统中查看到系统的流量分析及网站分析数据。
场景2：页面渲染后再修改展示内容
这一类需求通常是“页面本身没有配置项，只能在元素渲染出来之后再改”，例如：
- 图表无数据时，将默认提示语替换成业务文案。
- 将浏览器 tab 标题长期固定为客户公司名称。
- 在指定页面中隐藏某个下拉选项，例如隐藏“新建数据集”。
- 对老页面中的面包屑、标题等 DOM 内容做定制替换。
如果只是改固定文案，优先看下一节的 window.customI18nPostProcessor；只有在拿不到 i18n key，或需要结合页面结构一起处理时，才建议直接操作 DOM。
以下示例中，通过自定义 JS 代码将系统中图表的无数据文案进行了替换。
/**
* 替换文案
*/
var replaceTimer;
function replace(element, from, to) {
const cont = element.textContent;
if (cont) element.textContent = cont.replace(from, to);
};
function setTimer() {
if (!window.location.pathname.includes('dashboard')) return;
clearInterval(replaceTimer);
replaceTimer = setInterval(function () {
var elements = document.querySelectorAll('.hst__chart__no__data hr ~ span');
var len = elements.length;
console.log('In timer');
while (len--) {
replace(
elements[len],
new RegExp("图表无符合条件的数据", "g"),
"暂无数据",
);
}
}, 300);
}
document.addEventListener('hs_urlchange', setTimer);
setTimer();场景3：按 i18n key 定制页面文案
如果只是想覆盖某个固定文案，优先使用 window.customI18nPostProcessor。它比定时扫描 DOM 更稳定，也更容易维护，特别适合技术经验不多、但需要快速改欢迎语和按钮文案的场景。
window.customI18nPostProcessor = function (value, key, options) {
if (key === 'copilot.recommend_more') {
return '你好，我是衡石AI数据助理，辅助您完成数据查询工作';
}
return value;
};常见需求：
- 统一 Copilot / Data Agent 欢迎语。
- 覆盖按钮、空态、提示语等平台内置文案。
- 做租户级品牌化，让不同客户看到自己的业务表述。
使用建议：
- 仅对需要覆盖的 key 返回新文案，其他情况直接返回
value。 - 先通过浏览器开发者工具或现有语言包确认 key，再编写定制逻辑。
- 如果文案会随着页面结构变化而变化，不要强行用这个 Hook，改用全局 JS 处理 DOM。
场景4：给 Data Agent 注册自定义 Tool
在“系统设置 → 全局 JS”的 Data Agent 页签中，可以使用 window.heisenberg.createTool() 给运行时 Agent 挂载自定义工具。它适合的不是“改页面”，而是“补能力”，也就是让 Agent 能访问平台外的数据和动作。
典型需求包括：
- 查询企业内部知识库、FAQ、制度文档。
- 接内部 HTTP API 查询业务数据，例如库存、订单、工单状态。
- 调外部搜索服务或 SaaS API，补充 Agent 的实时信息来源。
- 执行轻量动作，例如创建工单、发起审批、回写备注等。
if (typeof window.heisenberg?.createTool === 'function') {
window.heisenberg.createTool({
name: 'hello_customer',
description: '返回租户侧自定义欢迎语',
parameters: window.heisenberg.zod.object({}),
execute: async () => '你好，我是客户自定义 Tool',
});
}保存并刷新后，Data Agent 即可在网页端 Agent 模式中调用该 Tool。若要接入企业知识库、搜索引擎或内部 HTTP API，可继续参考 Data Agent 调试 中的完整示例。
如果你的诉求只是改欢迎语、改按钮文案、隐藏某个页面元素，不需要用 createTool()；那属于文案或界面定制，应该优先使用 customI18nPostProcessor、全局 JS 或全局 CSS。
从失控的 JS 代码中恢复
自定义 JS 代码的能力非常强大，同时也有风险，如果您在自定义 JS 代码时，由于代码错误或其它 JS 方面的原因，很可能会导致系统无法正常访问。
为此我们提供了 URL 参数辅助从失控的 JS 代码中恢复的能力，您可以访问 https://{host}/setting/global-js?no-global-js=true 来禁用 JS 代码并访问配置页面，从而能够恢复系统的访问。