From 0cc3a2412d63e798dddf4a76103eb384783f2349 Mon Sep 17 00:00:00 2001
From: baiqing <lbx12309@icloud.com>
Date: Sun, 10 May 2026 11:05:50 +0800
Subject: [PATCH] docs: codify subagent-mediated API research workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User-requested mechanism (/init args): when implementing against any
external surface — third-party HTTP APIs, unfamiliar Rust crates / npm
packages, or platform APIs (Apple Security framework / Win32 / Carbon
/ AppKit) — Claude must dispatch a dedicated subagent to fetch
authoritative documentation rather than write integration code from
training memory. The subagent acts as a network-search-and-retrieval
layer that returns distilled, version-aware usage data so the main
context stays uncluttered and the implementation always tracks the
current upstream surface.

Two surgical edits:

1. AGENTS.md §"Third-party service integrations" — heading widened to
   "Third-party service integrations & library / platform API research"
   so the existing 5-step research-first workflow explicitly covers
   library + platform APIs, not just HTTP service integrations.
   Rephrased the lead-in paragraph to enumerate the broader scope.

2. CLAUDE.md — new top-level section "调研先于编码：派子 agent 查 API
   / 库 / 平台文档" pointing back to AGENTS.md as the canonical rules
   and listing the concrete tooling Claude Code has available:
   Context7 MCP (resolve-library-id + query-docs), the
   documentation-lookup skill, and Agent dispatch with
   subagent_type=general-purpose. Specifies trigger conditions,
   non-trigger conditions (when grep is enough), the prompt fields
   every subagent dispatch must include, and the four canonical
   anti-patterns.

No code changes; pure docs.
---
 AGENTS.md | 24 ++++++++++++++++++++++++
 CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 76 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 15145daf..11b59cdb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -167,3 +167,27 @@ Windows release 链路修过四颗雷，每一颗的 fix 都是不可合并的
 2. Register it in `lib.rs` (`mod <name>;`).
 3. Wire it into `coordinator.rs` and expose any frontend-callable surface via `commands.rs` + `invoke_handler!`.
 4. Add the matching TS wrapper in `openless-all/app/src/lib/ipc.ts` (with a mock branch for browser dev).
+
+### Third-party service integrations & library / platform API research
+
+When implementing features that depend on **anything outside this repo** — external HTTP APIs (ASR providers, polish endpoints, GitHub API), unfamiliar crates / npm packages, platform APIs (Apple Security framework, Win32, CoreFoundation), or any SDK whose surface shifts faster than your training cut-off — do not write integration code from memory. API surfaces drift; model training data is stale by definition. The same workflow below applies whether you are calling an HTTP endpoint, learning a new Rust crate, or wiring a system framework — substitute "endpoint URL" / "function signature" / "feature flag" as appropriate.
+
+Follow this research-first workflow:
+
+1. **Analyze before coding.** Identify every external call this feature needs: endpoint URL, HTTP method, authentication mechanism, request body schema, expected response schema, and error codes.
+2. **Delegate web search to a sub-agent.** Spawn a read-only sub-agent whose sole job is to search for official documentation. The sub-agent runs in parallel — you continue other work instead of blocking on sequential web pages.
+3. **Filter sub-agent results.** When the sub-agent returns, extract only the information directly relevant to the current implementation. Discard marketing pages, unrelated API versions, or tangential tutorials.
+4. **Cross-verify one key finding.** Before writing code, validate at least one structural claim (endpoint URL, required header, auth format) with a direct `web_search` or `fetch_url` call. Sub-agents can hallucinate.
+5. **Implement from verified documentation.** Only write integration code after the above steps. Never guess.
+
+**Sub-agent search brief:**
+- Focus each sub-agent on a single external service or protocol — one service, one sub-agent.
+- Prioritize official documentation domains (e.g., `docs.volcengine.com`, `platform.openai.com/docs`), falling back to the project's GitHub README.
+- The sub-agent must return **structured** findings: endpoint URL, HTTP method, required headers, request body JSON Schema, response body JSON Schema, and error code meanings.
+- If the documentation covers multiple API versions, the sub-agent must note which version was referenced.
+
+**Anti-patterns (do not do these):**
+- ✗ Writing API integration code from memory without a documentation search.
+- ✗ Pasting entire web pages into the main agent context — the sub-agent does the filtering.
+- ✗ Mixing field names or endpoint paths from different API versions.
+- ✗ Skipping error handling — every external call must degrade gracefully when the service is unavailable.
diff --git a/CLAUDE.md b/CLAUDE.md
index d99ec085..ddad74c9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -161,3 +161,55 @@ If any step fails, do not announce the release; investigate `release-tauri.yml`
 2. Register it in `lib.rs` (`mod <name>;`).
 3. Wire it into `coordinator.rs` and expose any frontend-callable surface via `commands.rs` + `invoke_handler!`.
 4. Add the matching TS wrapper in `openless-all/app/src/lib/ipc.ts` (with a mock branch for browser dev).
+
+## 调研先于编码：派子 agent 查 API / 库 / 平台文档
+
+**完整规则在 [AGENTS.md `Third-party service integrations & library / platform API research`](AGENTS.md) 段落（line 171-191）。** 这里列的是 Claude Code 入场后用得上的具体工具映射。
+
+### 触发条件 — 命中任一项都先派子 agent 调研，再下笔
+
+- 第三方 HTTP API（ASR 厂家 / LLM 端点 / GitHub API / Tauri plugin 服务等）
+- 不熟的 Rust crate / npm 包：连签名和 feature flag 都不确定时
+- 平台 API：Apple Security framework / CoreFoundation / Win32 / Carbon / AppKit
+- 仓库 lock 文件锁着的某版本到底支持什么 — 训练记忆和 `Cargo.lock` / `package-lock.json` 实际版本可能不一致
+- 任何跟「训练 cutoff 之后才迭代过」相关的接口
+
+### 不需要派子 agent
+
+- 仓库代码里已有现成调用 → `rg` / `grep` 找参考即可（仓库即文档）
+- 通用编程 / 算法 / 自己能推导的语言特性
+- 单文件 surgical 改动且改动点的 API 已有用例
+- 查本仓库已有模块（`types.rs` / `coordinator.rs` 等）— 直接 Read
+
+### 工具优先级
+
+```text
+1. Context7 MCP（最高优先 — 主流库覆盖广，version-aware）
+   - mcp__context7__resolve-library-id  → 拿 library id
+   - mcp__context7__query-docs          → 当前版本的官方文档片段
+
+2. documentation-lookup skill
+   /skill documentation-lookup —— 包装 Context7，含路由 + 缓存。
+
+3. Agent 子 agent（subagent_type=general-purpose）
+   场景：Context7 没覆盖（小众 crate / 新 SDK / 非英文文档），
+   或需多源交叉（官方文档 + GitHub README + Stack Overflow）。
+   子 agent 用 WebFetch / WebSearch / Context7 综合，回 200-400 字结构化结果。
+
+4. 单点兜底：直接 WebFetch 单页文档（只读最权威一篇时）
+```
+
+### 子 agent prompt 必备字段
+
+1. **目标问题**：一句话讲清要解决的具体技术问题（不要"了解一下 X"这种空靶）
+2. **本仓库现状**：当前 lock 着的版本（`Cargo.lock` / `package-lock.json` 拉一下）+ 现有调用点 `file:line`（若有）
+3. **必须返回的结构**：函数/端点签名 → 最小可运行示例（≤20 行）→ **版本兼容范围**（vs 训练记忆的核心校验点）→ 已知坑 / 平台差异 / 弃用计划
+4. **禁令**：不改本仓库代码；不贴文档原文（distill 关键部分，避免上下文撑爆）；多个独立服务分别派 agent — 一个服务一个 agent
+
+### 反例
+
+- ✗ 凭训练记忆写第三方 API 调用，假定参数签名就这样
+- ✗ 把整段官方文档 paste 进主上下文
+- ✗ 先写代码再查文档
+- ✗ 单子 agent 同时调研 5 个不相关库（每个独立 prompt + 独立上下文）
+- ✗ 子 agent 返回后跳过 cross-verify 直接写代码 — AGENTS.md 第 4 步要求至少用一次 `WebFetch` 直接命中官方源核对一项关键事实