Back to Details

zhihe-legal-research

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

智合法律研究

Zhihe Legal Research

连接智合AI法律大模型平台，提供专业的法律调研分析服务。
Connect to the Zhihe AI Legal Large Model Platform to provide professional legal research and analysis services.

⚠️ 异步任务处理机制

⚠️ Asynchronous Task Processing Mechanism

法律研究是异步长任务（3-10分钟）。采用用户主动查询机制，兼容所有 AI Agent 平台（Claude Code、OpenClaw 等）：
用户提交 → 获得任务 ID → 用户稍后主动查询 → 获取结果并归档
核心原则：
  • 不在每次消息前自动检查结果——避免旧结果污染当前对话
  • 仅在用户主动询问研究结果时才查询状态和结果
  • 每次查询完毕后立即归档——确保状态干净，不留残留数据
Legal research is an asynchronous long-running task (3-10 minutes). Adopts a user-initiated query mechanism, compatible with all AI Agent platforms (Claude Code, OpenClaw, etc.):
User submission → Obtain task ID → User actively queries later → Get results and archive
Core Principles:
  • Do not automatically check results before each message - Avoid contaminating current conversations with old results
  • Only query status and results when users actively ask about research results
  • Archive immediately after each query - Ensure clean status with no residual data

工作流程

Workflow

步骤 1：检查登录状态

Step 1: Check Login Status

bash
./scripts/auth.sh check
  • is_vip: true
    → 已登录，继续
  • code: 401
    → 需要登录（执行步骤 2）
bash
./scripts/auth.sh check
  • is_vip: true
    → Logged in, proceed
  • code: 401
    → Need to log in (perform Step 2)

步骤 2：登录（如需）

Step 2: Login (if needed)

bash
undefined
bash
undefined

发送验证码（如果已保存手机号，可省略手机号参数）

Send verification code (omit phone number parameter if phone number is saved)

./scripts/auth.sh send-code [手机号]
./scripts/auth.sh send-code [phone number]

验证登录（自动保存 Token 和手机号）

Verify login (automatically save Token and phone number)

./scripts/auth.sh verify <手机号> <6位验证码>

**自动重登流程**：如果 `config` 中已保存 `LEGAL_RESEARCH_PHONE`，token 失效时可直接执行 `./scripts/auth.sh send-code`（无需传入手机号），系统自动使用保存的手机号发送验证码。用户只需提供验证码即可完成重登。
./scripts/auth.sh verify <phone number> <6-digit verification code>

**Automatic Re-login Process:** If `LEGAL_RESEARCH_PHONE` is saved in `config`, when the token expires, you can directly execute `./scripts/auth.sh send-code` (no need to pass in the phone number), and the system will automatically use the saved phone number to send the verification code. Users only need to provide the verification code to complete re-login.

步骤 3：提交法律问题

Step 3: Submit Legal Question

bash
undefined
bash
undefined

提交问题

Submit question

./scripts/research.sh submit "<用户的法律问题>"

**提交成功后，记录 task_id 并告知用户：**

> ✅ 您的法律问题已提交，后台正在进行调研分析。
> ⏱️ 预计需要 3-4 分钟完成。
> 📋 任务 ID：`{task_id}`
>
> 👉 请在约 4 分钟后回复"查看结果"或"研究结果好了吗"来获取分析报告。
./scripts/research.sh submit "<user's legal question>"

**After successful submission, record the task_id and inform the user:**

> ✅ Your legal question has been submitted, and background research and analysis are in progress.
> ⏱️ It is expected to take 3-4 minutes to complete.
> 📋 Task ID: `{task_id}`
>
> 👉 Please reply "Check results" or "Is the research result ready?" after about 4 minutes to get the analysis report.

步骤 4：查询结果（仅当用户主动询问时）

Step 4: Query Results (only when users actively ask)

触发条件： 用户主动询问研究结果（如"查看结果"、"结果出来了吗"等）。
如果用户提供了 task_id，直接查询；如果未提供，先查历史获取最近任务：
bash
undefined
Trigger Condition: Users actively ask about research results (e.g., "Check results", "Is the result out?", etc.).
If the user provides a task_id, query directly; if not, first check history to get the latest task:
bash
undefined

如果没有 task_id，先查历史

If no task_id, check history first

./scripts/research.sh history 1 3

然后查询状态：

```bash
./scripts/research.sh history 1 3

Then query the status:

```bash

查询状态

Query status

./scripts/research.sh status <task_id>

**根据状态处理：**

| 状态 | 处理方式 |
|------|----------|
| `completed` | 获取结果 → 获取报告 → 归档 → 展示给用户 |
| `running` | 告知用户继续等待 1-2 分钟后再查询 |
| `pending` | 告知用户仍在排队中，稍后再查 |
| `failed` | 告知用户失败原因，建议重新提交 |
| `timeout` | 告知用户超时，建议简化问题重试 |

**当状态为 completed 时，依次执行：**

```bash
./scripts/research.sh status <task_id>

**Process according to status:**

| Status | Processing Method |
|--------|-------------------|
| `completed` | Get results → Get report → Archive → Display to user |
| `running` | Inform user to wait another 1-2 minutes before querying |
| `pending` | Inform user that it is still in queue, check later |
| `failed` | Inform user of failure reason, suggest resubmission |
| `timeout` | Inform user of timeout, suggest simplifying the question and retrying |

**When status is completed, execute in sequence:**

```bash

1. 获取文字结果

1. Get text results

./scripts/research.sh result <task_id>
./scripts/research.sh result <task_id>

2. 获取报告下载链接

2. Get report download link

./scripts/research.sh report <task_id>
./scripts/research.sh report <task_id>

3. 自动归档（下载报告到 archive/ 目录，含 Markdown 转换）

3. Auto-archive (download report to archive/ directory, including Markdown conversion)

./scripts/research.sh archive <task_id>

归档完成后，展示研究结果和报告链接给用户。

---
./scripts/research.sh archive <task_id>

After archiving is completed, display the research results and report link to the user.

---

Claude Code 增强模式（可选）

Claude Code Enhanced Mode (Optional)

仅在 Claude Code 环境下可用。 提供更好的异步体验，无需用户手动查询。
提交任务后，使用 
Bash
工具的 
run_in_background: true
启动后台监控：
bash
command: "./scripts/monitor.sh monitor <task_id> 600 30"
run_in_background: true
timeout: 600000
关键注意事项：
  1. timeout 必须设为 600000（10分钟），否则默认 2 分钟会超时
  2. 后台监控完成后会自动收到通知，此时展示结果给用户
  3. 监控脚本会自动归档到 
    archive/
    目录
OpenClaw 环境不支持此增强模式，请使用标准流程（步骤 1-4）。
Only available in Claude Code environment. Provides a better asynchronous experience without requiring manual queries from users.
After submitting the task, use 
Bash
tool's 
run_in_background: true
to start background monitoring:
bash
command: "./scripts/monitor.sh monitor <task_id> 600 30"
run_in_background: true
timeout: 600000
Key Notes:
  1. timeout must be set to 600000 (10 minutes), otherwise the default 2 minutes will cause timeout
  2. A notification will be automatically received after background monitoring is completed, and the results will be displayed to the user at this time
  3. The monitoring script will automatically archive to the 
    archive/
    directory
This enhanced mode is not supported in OpenClaw environment, please use the standard process (Steps 1-4).

常用命令

Common Commands

认证

Authentication

命令用途
./scripts/auth.sh check
检查登录状态
./scripts/auth.sh send-code [phone]
发送验证码（省略手机号时使用已保存的号码）
./scripts/auth.sh verify <phone> <code>
验证登录（自动保存 Token 和手机号）
./scripts/auth.sh logout
清除凭证
CommandPurpose
./scripts/auth.sh check
Check login status
./scripts/auth.sh send-code [phone]
Send verification code (use saved phone number when omitted)
./scripts/auth.sh verify <phone> <code>
Verify login (automatically save Token and phone number)
./scripts/auth.sh logout
Clear credentials

研究操作

Research Operations

命令用途
./scripts/research.sh submit "<query>"
提交问题
./scripts/research.sh status <task_id>
查询状态
./scripts/research.sh result <task_id>
获取结果
./scripts/research.sh report <task_id>
获取报告链接
./scripts/research.sh archive <task_id>
归档研究结果
./scripts/research.sh history [page] [size]
查看历史任务
CommandPurpose
./scripts/research.sh submit "<query>"
Submit question
./scripts/research.sh status <task_id>
Query status
./scripts/research.sh result <task_id>
Get results
./scripts/research.sh report <task_id>
Get report link
./scripts/research.sh archive <task_id>
Archive research results
./scripts/research.sh history [page] [size]
View historical tasks

监控管理（仅 Claude Code 增强模式）

Monitoring Management (Only for Claude Code Enhanced Mode)

命令用途
./scripts/monitor.sh monitor <task_id> [timeout] [interval]
阻塞监控
./scripts/monitor.sh status
查看监控状态
./scripts/monitor.sh results
获取已完成待通知的结果
./scripts/monitor.sh clear <task_id>
标记为已通知
CommandPurpose
./scripts/monitor.sh monitor <task_id> [timeout] [interval]
Blocking monitoring
./scripts/monitor.sh status
Check monitoring status
./scripts/monitor.sh results
Get completed pending notification results
./scripts/monitor.sh clear <task_id>
Mark as notified

状态处理

Status Handling

状态说明处理
pending
排队中告知用户等待
running
处理中告知用户继续等待
completed
已完成获取结果 → 归档 → 通知用户
failed
失败通知用户失败原因
timeout
超时通知用户超时
StatusDescriptionProcessing
pending
In queueInform user to wait
running
ProcessingInform user to continue waiting
completed
CompletedGet results → Archive → Notify user
failed
FailedNotify user of failure reason
timeout
TimeoutNotify user of timeout

配置

Configuration

所有配置文件自包含在 skill 内部：
assets/
文件用途
.env
Token 和手机号配置（已加入 .gitignore）
pending.json
待处理任务
completed.json
已完成待通知
notified.json
已通知历史
注意：
assets/.env
已加入 
.gitignore
，敏感信息不会被提交到 git。
配置示例见 assets/.env.example
All configuration files are self-contained within the skill: 
assets/
FilePurpose
.env
Token and phone number configuration (added to .gitignore)
pending.json
Pending tasks
completed.json
Completed pending notification
notified.json
Notified history
Note: 
assets/.env
has been added to 
.gitignore
, and sensitive information will not be submitted to git.
See assets/.env.example for configuration examples.

归档功能

Archive Function

自动归档

Auto-archive

任务完成时自动归档：归档时会自动下载报告并保存到 
archive/
目录。
归档命名格式：
YYMMDD 主题_法律研究报告
示例：
archive/
├── 260326 美术作品著作权侵权纠纷_法律研究报告/
│   ├── result.md       # 研究结果摘要（Markdown）
│   ├── report.docx     # 详细报告（自动下载）
│   ├── report.md       # 报告 Markdown 版本（需安装 pandoc）
│   └── media/          # 报告中的图片（如有）
└── 260310 劳动合同解除赔偿_法律研究报告/
    └── result.md
Auto-archive when task is completed: During archiving, the report will be automatically downloaded and saved to the 
archive/
directory.
Archive Naming Format: 
YYMMDD Topic_Legal Research Report
Example:
archive/
├── 260326 美术作品著作权侵权纠纷_法律研究报告/
│   ├── result.md       # Research result summary (Markdown)
│   ├── report.docx     # Detailed report (auto-downloaded)
│   ├── report.md       # Report Markdown version (requires pandoc installation)
│   └── media/          # Images in the report (if any)
└── 260310 劳动合同解除赔偿_法律研究报告/
    └── result.md

手动归档

Manual Archive

bash
undefined
bash
undefined

归档研究结果（自动下载报告并转换为 Markdown）

Archive research results (auto-download report and convert to Markdown)

./scripts/research.sh archive <task_id>
./scripts/research.sh archive <task_id>

列出所有归档

List all archives

./scripts/research.sh list-archive
undefined
./scripts/research.sh list-archive
undefined

Markdown 转换依赖

Markdown Conversion Dependencies

归档时会自动尝试将 docx 报告转换为 Markdown：
  • 依赖：需要安装 pandoc
  • 格式：使用 GitHub Flavored Markdown (GFM)，保留原始层级结构
  • 图片：自动提取到 
    media/
    子目录
bash
undefined
The system will automatically attempt to convert docx reports to Markdown during archiving:
  • Dependency: Need to install pandoc
  • Format: Uses GitHub Flavored Markdown (GFM), retains original hierarchical structure
  • Images: Automatically extracted to 
    media/
    subdirectory
bash
undefined

macOS 安装 pandoc

Install pandoc on macOS

brew install pandoc

---
brew install pandoc

---

详细文档

Detailed Documentation

  • API 参考文档 - 完整 API 说明
  • 交互示例 - 各种场景的完整流程
  • API Reference - Complete API description
  • Interaction Examples - Complete workflows for various scenarios

注意事项

Notes

  1. 会员要求：需要智合AI平台会员，非会员引导至 https://www.zhiexa.com
  2. Token 有效期：72 小时，过期需重新登录
  3. 频率限制：每分钟仅可提交 1 个问题，同时只能有 1 个进行中任务
  4. 报告链接：有效期 7 天，过期后重新调用接口会自动刷新
  5. 隐私保护：手机号仅用于鉴权，展示时脱敏
  6. 跨平台兼容：核心流程仅依赖 bash 脚本，兼容所有 Agent 平台（Claude Code、OpenClaw）
  1. Membership Requirement: Requires a Zhihe AI platform membership; non-members are directed to https://www.zhiexa.com
  2. Token Validity: 72 hours, need to re-login after expiration
  3. Frequency Limit: Only 1 question can be submitted per minute, and only 1 ongoing task is allowed at a time
  4. Report Link Validity: 7 days; re-calling the interface will automatically refresh it after expiration
  5. Privacy Protection: Phone numbers are only used for authentication and will be desensitized when displayed
  6. Cross-Platform Compatibility: The core process only relies on bash scripts, compatible with all Agent platforms (Claude Code, OpenClaw)