--- name: youdao-youju description: 用有道有据检索资料、基于来源回答研究问题、阅读论文和管理研究项目。当用户要求用有据调研、整理项目资料或延续已有研究时使用，自动恢复当前工作目录对应的有据项目。 --- # 有道有据 把有据作为外部研究与资料工作区，保留引用和产出。适用于能读取文件、执行 Python 3.10+ 和访问 HTTPS 的 Codex、DeepSeek harness 等 agent。只收到本文件链接时，先完成下面的安装；不要假定脚本已存在。 ## 从链接安装（一次） 这是公共模板，不包含用户 Key。**要实现贴一个链接就能安装并使用**，请用户登录 https://ju.youdao.com/agent/api-docs/ ，点击「生成我的安装链接（含 Key）」，将生成的个人链接交给当前 agent。个人链接返回已经配置 Key 的安装说明和完整包，agent 可直接完成安装、保存凭据和连接检查，无需再次向用户索要 Key 或要求用户手工传包。 个人链接有效期 30 分钟；安装后的 Key 持续有效，直到用户吊销。不要把个人链接作为日常 API 地址或分享给其他人。 如果你已经从个人链接下载了完整包，保留 `youdao-youju/` 内的目录结构，包内 `credentials.json` 已配置好，无需再生成链接。Codex 可放到用户级 `~/.agents/skills/youdao-youju/` 或项目级 `.agents/skills/youdao-youju/`；已有自定义 skills 目录时沿用它。DeepSeek 等 harness 没有统一安装目录：放入其配置的 skills 目录，并让 harness 加载本 `SKILL.md`、允许运行附带脚本；如果不支持自动发现，显式将本文件加入 agent 指令。无需更换用户使用的模型。 安装后运行 `python3 /scripts/youju.py setup` 收紧凭据文件权限并检查连接。不读取或打印凭据内容。包内 `.gitignore` 已排除凭据；用户级安装更适合多个本地项目共用。 已有 Key 的开发者可手工下载公共包 https://ju.youdao.com/agent/api/v1/skill.zip 并设置环境变量 `YOUJU_API_KEY`。环境变量优先于包内凭据。不要把 Key 写进聊天回复、命令参数、项目映射或 URL。Agent 不能继承用户浏览器登录，也不能从公共链接领取他人的 Key。 以下命令中的 `` 均指安装目录内 `scripts/youju.py` 的绝对路径，工作目录始终是用户正在处理的本地项目，不是 skill 安装目录。 ## 项目关联：不让用户记 ID 先运行 `python3 status`。脚本会从当前目录向上找到 `.youju/project.json`（遇到 Git 根目录即停止），并用 API 核验项目存在且当前 Key 有访问权。已有有效绑定就继续使用，不再问 ID，不另建项目。 未绑定、换设备或映射丢失时，运行 `python3 projects`，结合用户给的项目名称、目标和网页链接辨认已有项目。不能仅凭目录同名、列表第一条或“最近更新”擅自选择。明确匹配用户指定项目时直接 `bind `；同名或目标不明确时展示名称、目标和 ID，让用户选择。用户给的 `/agent/research//workspace/` 链接可提取 ID 后核验。 ```bash python3 projects python3 bind <用户选定的项目ID> # 只有用户要求新建或明确需要一个新研究项目时： python3 create --name "项目名称" --goal "研究目标" ``` `bind` 和 `create` 将项目 ID、名称、Base URL 和网页地址保存到当前本地项目的 `.youju/project.json`，不保存密钥。可用 `--root <本地项目根目录>` 明确指定范围。切换现有绑定必须传 `--replace`，仅在用户意图明确时使用。换到另一个代码仓库时重新检查绑定，不沿用对话记忆中的 ID。Git worktree/新克隆若无映射，从项目列表恢复，避免重复创建。 遇到 401 先处理 Key；403/404 告知项目不可访问或已删除，列出现有项目重新关联，保留旧映射。不要自动建一个同名替代项目，也不要在失败时把请求发给别的项目。 ## 完成研究任务 ```bash python3 search "需要检索的主题" python3 upload ./资料.pdf python3 ask "结合项目资料调研这个问题，请给出来源和局限" python3 outputs python3 download 'outputs/报告.md' ./报告.md ``` `ask` 使用 SSE 流，处理 `answer_replace` / `answer_discard`、引用与失败事件；只有完整结束才返回成功。超时/断连时先到项目网页检查任务或产出，不自动重发可能重复计费的请求。创建、上传同理：结果不明确时先检查远端，不能盲目重试。 需要单篇全文、收藏、文件管理或更细参数时，读 [references/api.md](references/api.md)，完整契约取 https://ju.youdao.com/agent/api/v1/docs.md 。脚本 `request` 支持相对 API 路径和 JSON 文件，`{project}` 会替换为经核验的当前项目 ID。 回答时保留 API 返回的真实来源 URL、文献标识、引用对应关系；区分来源结论和自己的推断。`unverified` / `validation_warnings` 是未核实项，不能当成已验证依据。生成文件后实际检查产出列表再报告下载位置。只上传用户任务所需资料，不把整个代码仓库或凭据目录上传到有据。429 时按响应区分配额耗尽与限流：配额不足到统一页面查看用量；不通过重建 Key 绕过账户配额。