AI 助手接入 / 新手指南
智能中登 AI Skills 使用指南
在 WorkBuddy、Codex 或 Claude Code 中安装智能中登 AI Skills，按步骤配置 API 密钥、读取账户权益，用自然语言查询企业中登登记、查重及下载原件。附计次说明与常见问题。
更新于
三步开始使用
开始前，请准备好智能中登账户。有效的轻量版、专业版或企业版订阅可以创建 API 密钥并使用相应开放能力，网页与助手共用资料和次数。查看我的订阅，或先了解方案。
1. 安装到你的 AI 助手
下载技能包，在 WorkBuddy 中导入
- 点击下方“下载 Skills ZIP”，保存技能包。
- 在 WorkBuddy 左侧选择“专家·技能·连接器 → 技能”，点击“添加技能 → 上传技能”。
- 选择刚下载的
zdw-skills.zip，查看安全检测结果，再点击“继续安装”。 - 在“我安装的”列表中找到
zdw-skills，确认已启用，再继续连接账户。
以下界面来自 macOS WorkBuddy 5.6.2；不同版本的入口名称可能略有不同。
查看安装步骤截图
请检查已安装并启用的 zdw-skills，读取它的 SKILL.md，告诉我技能是否可用。此时只检查安装，不读取密钥值，不调用 API，不创建业务任务。
检查点 1 · 安装成功：助手能找到并读取该技能说明；这一步尚未连接智能中登账户。
Codex、Claude Code：通过命令安装
在装有 Node.js 的终端运行以下命令，按提示选择你的助手。安装完成后，刷新技能列表或重新打开助手。
npx skills add https://zdwai.com/skills/zdw-skills.zip -g运行这个技能需要 Python 3.10 或更新版本，无需额外安装 Python 依赖。 Node.js 用于上面的命令安装方式；通过 WorkBuddy 导入 ZIP 后，仍需检查助手运行技能的 Python 环境。
其他安装方式、更新与文件校验
手动安装时，解压 ZIP，将其中的 zdw-skills 文件夹放入助手的技能目录。Codex 可使用 ~/.codex/skills/，Claude Code 可使用 ~/.claude/skills/；其他助手按其 Agent Skills 安装方式导入。
WorkBuddy 5.6.2 会拒绝重复导入同名技能。更新时先下载并解压新版 ZIP，在“我安装的”找到技能卡片，点击“更多 → 打开文件夹”。将旧的zdw-skills 目录移到技能目录之外备份，再将解压出的新版同名目录放回原位置。 完成后新建对话，运行配置检查。已保存的密钥不在技能目录中，无需重新配置。
通过命令安装的助手可重新运行安装命令并按提示替换。更新前保留原请求文件和提交凭据， 这些业务文件应存放在独立私有目录；已有任务可凭任务编号继续查看。
2. 连接你的智能中登账户
- 创建专用密钥
登录智能中登，进入“接入中心 → API 密钥”，创建一个便于识别用途的密钥，例如“我的 AI 助手”。完整密钥只显示一次，请复制后用于下一步。
- 在对话中保存密钥并检查连接
复制下方提示词，将【粘贴密钥】替换为刚创建的完整密钥，发给 WorkBuddy 或其他已安装技能的助手。这是智能中登 API 密钥，与 WorkBuddy 或其他助手的模型服务密钥不同。助手会保存配置，再读取你的真实账户权益。
使用智能中登，保存我的 API 密钥【粘贴密钥】，并检查账户连接。请分别说明密钥是否已保存、账户是否连接成功，以及订阅状态和查询、查重可用次数；不要回显密钥，不创建业务任务。
只需配置一次。以后正常打开 WorkBuddy 即可使用，重启应用或更新技能后无需重新配置。 更换密钥时再发送一次相同提示词；更换机器或系统用户后需重新配置。
密钥以明文保存在本机当前系统用户的独立配置文件中，也可能留在这次对话记录中。 助手的检查结果不会显示密钥。
检查点 2 · 配置已保存：助手确认密钥已保存到本机；如果在线检查失败，配置仍会保留，按错误提示排查后再检查连接。 若提示不支持配置命令，请按技能更新步骤安装新版，避免重复导入同名技能。
企业部署需要设置其他地址吗？
普通用户使用默认的 https://zdwai.com/api/open/v1，无需另填地址。企业部署请按管理员提供的 HTTPS 接口入口配置 ZDW_API_BASE；本机开发支持 HTTP loopback 地址。
3. 随时查看账户权益与剩余次数
使用智能中登，运行 scripts/zdw.py doctor --online，查看我的真实账户权益和剩余次数。说明订阅状态、API 新任务资格、查询和查重可用次数；只读取权益，不创建业务任务，不显示密钥或账户标识。
如果助手提示缺少配置、密钥无效或服务暂不可用，按实际提示处理后再试。仅显示“技能已安装”还不代表账户已连接。
接下来，可以这样提问
复制后先替换 【方括号中的内容】，再发给助手。查询和查重示例会创建任务并按规则计次；查看已有证据的示例只读取结果。
查询一个主体
准备好企业全称或18位大陆居民身份证号码。这个指令会发起新查询。
使用智能中登，发起对【企业全称或18位身份证号码】的一次新查询。完成后整理任务编号、执行状态、登记数量、资料时间和完整性，列出需要继续查看的登记证明。若等待超时，保留任务编号供续查，不要重新创建。
查询一份主体名单
将企业全称或18位身份证号码逐行填写；较长名单会分批提交。
使用智能中登，查询以下主体名单：【逐行填写企业全称或18位身份证号码】。请按主体整理任务编号、查询进度和登记数量；已受理的任务继续查看，不要重复提交。
复用已有资料查重
指定已有查询编号、主体和需要核查的完整发票号或关键词。
使用智能中登，复用查询【查询编号】中【企业全称或18位身份证号码】的资料，对【完整发票号码或合同关键词】发起查重。请说明来源资料的时间，列出命中证明、页码和原文片段，并说明本次查重的资料覆盖情况。
继续查看证据与下载原件
填写已有任务编号和需要下载的文件，指定本机保存位置。
使用智能中登，继续查看已有查重任务【任务编号】，解释【登记证明编号】的命中证据和资料完整性，将【需要下载的证明或附件】保存到本机【文件夹路径】。只读取已有结果，不创建新查询或查重任务。
检查点 4 · 业务完成：取得真实任务编号及明确执行终态，同时核对资料时间、来源状态和完整性；下载成功后检查本机文件与哈希。排队、等待超时或只有“已受理”都不代表业务完成。
查看一次真实业务验收的脱敏汇总
哪些操作会使用次数？
明确要求新查询或新查重后，助手会直接提交。与网页共用同一份额度，实际受理和结算以服务端为准。
| 操作 | 查询次数 | 查重次数 |
|---|---|---|
| 读取权益、查看已有结果、下载原件 | 0 | 0 |
| 新查询一个主体 | 1 | 0 |
| 获取新资料并查重一个主体 | 1 | 1 |
| 复用本人已有查询资料查重 | 0 | 1 |
批量查询按去重后的主体数计次，每次请求最多 100 个主体，较长名单可分批处理。每次查重针对一个主体，最多 100 个条件。复用资料保留原查询时点；需要最新资料时，请明确要求发起新查询。
任务需要等待时，保留编号并继续查看原任务；不要因为等待超时重新提交。查看详细计次与重试规则 →
常见问题
| 遇到的情况 | 下一步 |
|---|---|
| 找不到技能 | 在“我安装的”确认 zdw-skills 已启用；新建对话，再明确说“使用智能中登”。手动安装检查目录内是否直接包含 SKILL.md。 |
| Python 无法运行 | 在助手实际执行环境检查 Python 3.10+；按 Python 官网的系统安装指引补齐，再启动助手。Node.js 不能替代 Python。 |
| MISSING_API_KEY | 在当前助手对话中发送“连接账户”里的配置提示词，填入完整密钥，让助手保存并检查连接。 |
| INVALID_API_KEY（本机诊断） | 输入格式不正确。当前智能中登密钥以 zdw_ 开头，共 47 个字符；只粘贴完整密钥，不附带说明、引号或重复片段，也不要自行截断。 |
| 401／UNAUTHENTICATED（在线诊断） | 服务端未接受密钥。先确认本机格式检查通过，再核对是否为该服务的有效密钥；过期或撤销后在接入中心的 API 密钥页创建新密钥并重新保存。 |
| 本机配置文件损坏或无法读取 | 让助手检查当前系统用户的配置文件权限；格式损坏时重新发送配置提示词保存完整密钥。此时不会自动改用环境变量中的其他账户。 |
| 402／403／次数不足 | 查看订阅、新任务资格及对应可用次数；配置检查通过不保证可以创建新任务。已有结果仍按服务端授权读取。 |
| 排队／等待超时 | 保留任务编号，继续查看原任务；提交响应丢失时沿用原请求、幂等键和操作凭据，避免重复计次。 |
| partial／资料覆盖不完整 | 阅读返回的覆盖原因和已有证据；未命中不能排除风险。查询与查重的完整性分别判断。 |
安装后，助手找不到智能中登技能怎么办？
先在助手的已安装技能中查找 zdw-skills，并确认已启用。刷新技能列表或重新打开助手后，明确说“使用智能中登”。手动安装时，确认 zdw-skills 文件夹内直接包含 SKILL.md、scripts 和 references，不要多套一层同名文件夹。
提示缺少 Python，应该怎么处理？
请助手检查实际执行脚本的环境是否有 Python 3.10 或更新版本。缺少时，按操作系统或助手提供的安装指引补齐，再重新检查。Node.js 用于命令安装技能，不能替代运行客户端所需的 Python。
已经保存密钥，为什么仍提示缺少或无效？
先让助手在实际运行技能的环境重新检查配置。确认使用的是完整的智能中登 API 密钥；密钥过期或撤销时，到接入中心的 API 密钥页创建新密钥，再发送一次配置提示词。配置仅对同一机器、同一系统用户生效；更换机器或运行用户后需重新配置。排查时提供错误码即可，不必再次展示密钥。
重启 WorkBuddy 或更新技能后，要重新配置吗？
不用。密钥保存在本机当前系统用户的独立配置文件中，不随技能目录替换。以后正常打开 WorkBuddy 即可；更换密钥时，再发送一次配置提示词覆盖原配置。
一直等待资源，或者助手等待超时了怎么办？
等待资源表示任务仍在排队；助手等待超时也不代表任务已失败。保留任务编号，稍后请助手继续查看原任务。若提交时断线、尚未收到编号，保留原请求及本机提交凭据，让助手按原提交重试，不要换一个新任务重新查询。
次数不足或订阅到期，还能查看原来的结果吗？
已有有效密钥仍可读取已生成的结果。发起新任务需要相应的订阅权益和可用次数，可在网页账户中查看和补充。需要更换密钥时使用同一账户；恢复原提交应沿用原请求和提交凭据。
没有命中，是否说明不存在重复融资？
不能直接得出这个结论。先看查询时间、资料覆盖是否完整，以及是否存在下载或解析失败。资料不完整时，未命中不能用于排除风险；资料完整时，也只能说明该次已覆盖资料中没有找到对应条件，需要结合业务材料与原件核实。系统命中与已有人工确认结论会分别呈现。
哪些操作需要回到网页？
助手可以查询、查重、读取已有人工结论并下载本人原件。提交人工复核、设置登记监控和导出 Excel，请回到网页工作台完成。
需要排查调用问题时，提供助手返回的错误码和请求编号即可，不要提供完整密钥或客户原文。