chore: add task docs

sylingd · sylingd · commit e20b0be12422 · 2026-01-08T20:10:52.000+08:00
diff --git a/docs/docs/zh-CN/guide/task.md b/docs/docs/zh-CN/guide/task.md
@@ -0,0 +1,75 @@
+---
+title: 任务
+---
+
+## 任务是什么
+
+该功能可以按照配置，静默运行代码、发起请求，并将响应用于规则中。例如，您可以使用该功能定期刷新某个 token，并将其放入 header 中。
+
+## 配置指南
+
+### 任务 Key
+
+任务 Key 是任务的唯一标识，必须以字母开头，且只能包含字母、数字、下划线。Key 设置后不可修改。
+
+### 运行类型
+
+您可以选择在何时运行任务：
+
+* 仅运行一次：仅在浏览器启动时运行一次。
+* 固定间隔任务：在浏览器启动时运行一次，并每隔固定时间运行一次。
+* 定时任务：配置 Cron 表达式，在浏览器启动时运行一次，并在指定时间重复运行。
+
+您可以参考[该文档](https://help.aliyun.com/document_detail/133509.html)学习 Cron 表达式。
+
+### 执行类型
+
+常规方式下，您需要配置一个请求地址及请求参数。Header Editor 会定时向该地址发起请求。
+
+响应类型可以用于后续步骤处理。
+
+您可以使用 [JsonLogic](https://jsonlogic.com/) 对结果进行校验。使用 status 获取响应的 HTTP 状态码，使用 body 获取响应体。例如：
+
+```js
+// 响应结果
+{
+  "code": 200,
+}
+
+// JsonLogic
+{
+  "==": [{ "var" : "body.code" }, 200]
+}
+```
+
+您也可以使用自定义函数。自定义函数不会传入任何参数，在函数中处理请求及校验逻辑，并返回结果。例如：
+
+```js
+const res = await fetch('https://example.com');
+if (res.status !== 200) {
+  throw new Error('Request failed');
+}
+return res.json();
+```
+
+## 在规则中使用
+
+在规则中，使用 `{$TASK.TASK_KEY.Path}` 获取任务返回的响应结果。
+
+例如，您有一个 Key 为 `task1` 的任务，该任务返回了如下结果：
+
+```json
+{
+  "code": 200,
+  "data": {
+    "token": "123456"
+  }
+}
+```
+
+在规则中，您可以使用 `{$TASK.task1.data.token}` 获取任务返回的 token。
+
+注意：
+* 可以在规则的 重定向至、请求/响应头内容、响应体中使用此语法。
+* 如果响应类型配置为“文本”，则任何 `{$TASK.task1.*}` 均会获取到完整的响应文本。
+* 当请求失败或尚未完成请求时，该语法会被替换为空字符串。
diff --git a/src/pages/background/request-handler/utils.ts b/src/pages/background/request-handler/utils.ts
@@ -55,8 +55,15 @@ export function parseJSONPath(text: string) {
       return;
     }
 
-    const value = get(run.result, restPath);
-    result = result.replace(match, value);
+    if (typeof run.result === 'string') {
+      result = result.replaceAll(match, run.result);
+    } else {
+      const value = get(run.result, restPath);
+      result = result.replaceAll(
+        match,
+        typeof value === 'undefined' || value === null ? '' : value,
+      );
+    }
   });
 
   return result;
diff --git a/src/pages/options/sections/import-and-export/import-drawer/index.tsx b/src/pages/options/sections/import-and-export/import-drawer/index.tsx
@@ -1,14 +1,14 @@
-import * as React from 'react';
-import { SideSheet, Button, Table, Select, Toast } from '@douyinfe/semi-ui';
-import { css } from '@emotion/css';
 import { IconSave } from '@douyinfe/semi-icons';
+import { Button, Select, SideSheet, Table, Toast } from '@douyinfe/semi-ui';
+import { css } from '@emotion/css';
+import * as React from 'react';
+import BoolRadioGroup from '@/pages/options/components/bool-radio';
 import { selectGroup } from '@/pages/options/utils';
-import Api from '@/share/pages/api';
+import { TABLE_NAMES_ARR } from '@/share/core/constant';
 import { fromJson } from '@/share/core/rule-utils';
+import type { BasicRule, ImportRule } from '@/share/core/types';
 import { t } from '@/share/core/utils';
-import type { ImportRule, BasicRule } from '@/share/core/types';
-import BoolRadioGroup from '@/pages/options/components/bool-radio';
-import { TABLE_NAMES_ARR } from '@/share/core/constant';
+import Api from '@/share/pages/api';
 
 interface ImportDrawerProps {
   onCancel?: () => void;
@@ -22,7 +22,10 @@ interface ImportDrawerState {
   useRecommend: boolean;
 }
 
-export default class ImportDrawer extends React.Component<ImportDrawerProps, ImportDrawerState> {
+export default class ImportDrawer extends React.Component<
+  ImportDrawerProps,
+  ImportDrawerState
+> {
   constructor(props: any) {
     super(props);
 
@@ -50,13 +53,13 @@ export default class ImportDrawer extends React.Component<ImportDrawerProps, Imp
       let totalCount = 0;
       const importList: ImportRule[] = [];
       const list = typeof content === 'string' ? fromJson(content) : content;
-      TABLE_NAMES_ARR.forEach((tableName) => {
+      TABLE_NAMES_ARR.forEach(tableName => {
         if (!list[tableName]) {
           return;
         }
-        list[tableName].forEach((e) => {
+        list[tableName].forEach(e => {
           totalCount++;
-          Api.getRules(tableName, { name: e.name }).then((rule) => {
+          Api.getRules(tableName, { name: e.name }).then(rule => {
             const it: ImportRule = {
               ...e,
               group: e.group || t('ungrouped'),
@@ -82,9 +85,10 @@ export default class ImportDrawer extends React.Component<ImportDrawerProps, Imp
   }
 
   handleConfirm() {
+    // TODO: 处理 task 导入
     // 确认导入
     const queue: any[] = [];
-    this.state.list.forEach((e: BasicRule) => {
+    this.state.list.forEach((e: any) => {
       // 不导入
       if (e.importAction === 3) {
         return;
@@ -131,7 +135,7 @@ export default class ImportDrawer extends React.Component<ImportDrawerProps, Imp
   }
 
   handleSelectGroup(item: ImportRule) {
-    selectGroup(item.group).then((res) => {
+    selectGroup(item.group).then(res => {
       item.group = res;
       this.forceUpdate();
     });
@@ -166,11 +170,18 @@ export default class ImportDrawer extends React.Component<ImportDrawerProps, Imp
           }
         `}
         footer={
-          <div style={{ display: 'flex', justifyContent: 'flex-end', gap: '8px' }}>
+          <div
+            style={{ display: 'flex', justifyContent: 'flex-end', gap: '8px' }}
+          >
             <Button type="tertiary" theme="light" onClick={this.handleCancel}>
               {t('cancel')}
             </Button>
-            <Button type="primary" theme="solid" onClick={this.handleConfirm} icon={<IconSave />}>
+            <Button
+              type="primary"
+              theme="solid"
+              onClick={this.handleConfirm}
+              icon={<IconSave />}
+            >
               {t('save')}
             </Button>
           </div>
@@ -196,7 +207,11 @@ export default class ImportDrawer extends React.Component<ImportDrawerProps, Imp
                 <span>
                   <span>{value}</span>
                   &nbsp;
-                  <Button className="select-group" size="small" onClick={this.handleSelectGroup.bind(this, item)}>
+                  <Button
+                    className="select-group"
+                    size="small"
+                    onClick={this.handleSelectGroup.bind(this, item)}
+                  >
                     {t('choose')}
                   </Button>
                 </span>
@@ -207,10 +222,16 @@ export default class ImportDrawer extends React.Component<ImportDrawerProps, Imp
               render: (_v: any, item: ImportRule) => (
                 <Select
                   value={item.importAction}
-                  onChange={(value: string) => this.handleActionChange(item, value)}
+                  onChange={(value: string) =>
+                    this.handleActionChange(item, value)
+                  }
                   optionList={[
                     { label: t('import_new'), value: 1 },
-                    { label: t('import_override'), value: 2, disabled: item.importOldId === -1 },
+                    {
+                      label: t('import_override'),
+                      value: 2,
+                      disabled: item.importOldId === -1,
+                    },
                     { label: t('import_drop'), value: 3 },
                   ]}
                 />
@@ -243,10 +264,15 @@ export default class ImportDrawer extends React.Component<ImportDrawerProps, Imp
                   <span>
                     <span>{this.state.group}</span>
                     &nbsp;
-                    <Button className="select-group" size="small" onClick={this.handleSelectAll}>
+                    <Button
+                      className="select-group"
+                      size="small"
+                      onClick={this.handleSelectAll}
+                    >
                       {t('choose')}
                     </Button>
-                  </span>),
+                  </span>
+                ),
                 value: false,
               },
             ]}
diff --git a/src/pages/options/sections/tasks/edit/index.tsx b/src/pages/options/sections/tasks/edit/index.tsx
@@ -71,7 +71,6 @@ const TaskConfig = () => {
           <Form.TextArea
             field="fetch.body"
             label={t('request_body')}
-            placeholder={t('request_body_placeholder')}
             rows={4}
           />
           <Form.Select
@@ -255,6 +254,7 @@ const Edit = ({ visible, task: taskProp, onClose }: EditProps) => {
           field="key"
           label={t('task_key')}
           placeholder={t('task_key_placeholder')}
+          disabled={Boolean(initInput?.key)}
         />
 
         <Form.Input
diff --git a/src/share/core/rule-utils.ts b/src/share/core/rule-utils.ts
@@ -69,6 +69,7 @@ export function initRule(
 }
 
 export function createExport(arr: { [key: string]: Array<Rule | InitdRule> }) {
+  // TODO: 一并导出规则
   const result: { [key: string]: BasicRule[] } = {};
   Object.keys(arr).forEach(k => {
     result[k] = arr[k].map(e => convertToBasicRule(e));

Original file line number	Diff line number	Diff line change
`@@ -69,6 +69,7 @@ export function initRule(`
`69`	`69`	`}`
`70`	`70`
`71`	`71`	`export function createExport(arr: { [key: string]: Array<Rule \| InitdRule> }) {`
	`72`	`+ // TODO: 一并导出规则`
`72`	`73`	`const result: { [key: string]: BasicRule[] } = {};`
`73`	`74`	`Object.keys(arr).forEach(k => {`
`74`	`75`	`result[k] = arr[k].map(e => convertToBasicRule(e));`