# Skein Research

> SKEIN planning 调研方法论 — skein-researcher agent 绑定 skill。数据源路由 (先本地勘察 → 按需加载用户 research skills 增强方法论 → 外部检索补证) + 边研边增量双写落盘 (research/ 过程证据 + findings.md 收敛结论) + bootstrap 模式 (扫五维既有约定 + product overview)。只读不改码, 结论带来源, 不替用户拍板。

- Skill: `lazygophers/skein-research` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lazygophers/skein-research`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lazygophers/skein-research/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: lazygophers (https://skillmd.com/u/lazygophers)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lazygophers/skein-research

---


# skein-research — planning 调研方法论

> 🔒 本 skill 是 skein-researcher agent 的调研纪律单一真值源; agent .md 只留入参/回传/边界。
> 全局流程规则 (状态机/调度/优先级) 以 skein-flow/references/ 为单一真值源。

planning 阶段 main 派 agent 搜集信息 (库选型/方案对比/代码勘察/API 文档/第三方平台检索), 回传压缩结论 + 把全量调研落盘 `research/`。agent 自己负责数据源路由: 先本地代码/环境/API 文档勘察, 再发现并加载用户已有 research 类 skills, 最后按需做外部平台检索补证。

## 工作流五步 (normal 模式)

### 1. 本地勘察

```
Grep / Glob / Read 定位既有实现、约定、约束、依赖版本、本地 API 文档
```

- 带来源 (file:line); 无来源前缀 `推测:`。
- 环境事实优先来自仓内配置 / lockfile / README / docs / OpenAPI / SDK 文档; 需要命令探测时只跑只读 Bash。

### 2. 加载用户已有 research skills (如有)

```bash
find ~/.claude/skills ~/.trae-cn/skills .claude/skills .trae/skills -maxdepth 3 -iname 'SKILL.md' 2>/dev/null
```

- 只读取名称 / description / 适用边界; 命中 deep research / web research / social research / code research / policy research / market research 等与 query 相关的 skill 时, 采用其调研框架和检查清单增强本次调研。
- 不把已存在 skill 当事实源; 它只提供方法论。事实仍必须来自本地文件、官方文档、平台页面、搜索结果或明确标 `推测:`。
- 未发现合适 skill 时继续执行, 回传不需要额外标错。

### 3. 外部检索 (本地不足时)

```
WebSearch / WebFetch 取官方文档、库选型、方案对比、社区实践、GitHub、小红书等第三方平台信息
```

- 每条带 URL; 区分「文档写的」vs「社区说的」vs「推断的」。检索失败 → `[工具失败: 检索 <query> 失败]`, 报已得素材。
- 外部平台按意图分层组合, 非全跑: 官方/API 文档优先 WebFetch 精读; GitHub 用于仓库实现 / issue / PR / stars 活跃度; 小红书/Twitter/Reddit/V2EX/B站用于真实用户场景和社区反馈。无登录态或平台不可达时声明覆盖缺口, 禁假装全网覆盖。
- 如果本地存在 `agent-reach` 之类第三方平台检索器, 可先只读探测 `command -v agent-reach`; 存在则按它自己的文档路由, 不重抄命令或自造抓取方案。不可用时降级 WebSearch/WebFetch 并声明限制。

### 4. 结论落盘 (MUST 做, 边研边增量双写)

经 Bash 落盘 (唯一写盘处), **每完成一主题即同步写, 非最后一次性**; 这两文件只在真调研时产出 (main 未派你 = 不生, 不预建空壳):

```
mkdir -p .skein/task/<task-id>/research
# ① 过程证据 → research/<sid>.md = 当前 subtask 的完整结论 + 全部证据 + 权衡
# ② 收敛结论 → 追加进 .skein/task/<task-id>/findings.md (增量, 每主题一段: 结论 + 关键依据/引用 + 未决项)
```

- **findings.md 由 agent 边研边增量写** (每主题收敛即追加, 首次写补 `# <task> — 调研收敛` 标题), 使后续 planning 整理**只读 findings.md 不重读 research/**。research/ = 过程证据留档, findings.md = 收敛交付。

### 5. 回传压缩结论 + research 任务收尾

按 agent 定义的返回 JSON 格式填: 收敛结论 (已增量写入 findings.md) + findings.md 路径 + subtask 收尾状态 + 需要 + 工具失败。

**报告落盘后必须完成 research 任务状态收尾** (research 条目存 task.json 的 research_tasks[], 不在 subtasks[], 走 `subtask done/fail` 必报「subtask 不存在」):

```
skein research done <tid> <sid>
```

调研失败或缺少关键资料 → `skein research fail <tid> <sid> --note "<原因>"`。

入参 `sid` 为 null (未 claim 派发, 如 main 手派调研) 时跳过收尾自跑, 由 main 收。

## bootstrap 模式 (入参 `mode` 为 `bootstrap`)

**替换步骤 1-4** (本地勘察 / 加载 research skills / 外部检索 / 落盘) 为下述扫库动作; 步骤 5 回传照跑不变。无外部检索 (只读本仓代码), 落盘路径也另有专属值, 见末条。

扫代码库提炼既有约定为候选规则:

- 扫五维 (命名 / 错误处理 / 测试 / 架构边界 / 构建), 只提既有约定 (≥2 处一致证据), 命令式化描述, 产 rules namespace 候选。
- **第六项 product overview** (与前五维性质不同): 额外扫一遍 `README` / `docs/` / 顶层入口文件, 提炼当前系统是什么 (产品定位/核心功能域/主要用户流程), 产 1 篇 product namespace 现状快照候选 (非规则, 不要求 ≥2 处一致证据); 无 README/docs 可提炼 → 该项留空, 不用硬猜填充。
- 落盘 `.skein/task/bootstrap/research/conventions.md`; 层判定/取舍归 main+用户。

## 检查点

🛑 **不碰项目代码** — 无 Write/Edit; 唯一写盘是 research/ 目录 (经 Bash)。
🛑 **结论必落盘 (边研边增量)** — 每主题即时写 research/<topic>.md (过程) + 追加 findings.md (收敛), 非最后一次性; 只回传不落盘 = 素材丢失且逼后续重读 research/。两文件仅真调研时产出。
🛑 **先本地后外部** — 代码/环境/API 文档是本仓真值; 外部结论必须回扣本仓版本和约定。
🛑 **用户 research skills 只增强方法论** — 可以加载其框架, 但不能把 skill 文案当事实证据。
🛑 **带来源, 无来源标 `推测:`** — file:line / URL; 区分文档/社区/推断。
🛑 **不替用户拍板** — 给收敛结论 + 权衡, 选型决策交 main+用户。
🛑 **缺信息标 `需要: <问题>` 回传, 由 main 转达用户** — 无 AskUserQuestion 权限。
🛑 **工具失败必标 `[工具失败: <原因>]`** — 检索/Fetch 失败时, 只标 `[工具失败: <原因>]`, 空结果不当成功结果返回 (main 误判无信息)。
🛑 **允许自跑 `research done/fail`；其余生命周期命令归 main** — agent 是 research 任务状态唯一收尾者，main 只校验状态。

## 失败模式 (if-then 三段式)

| 触发                      | 一线处理                           | 兜底                                                        |
| ------------------------- | ---------------------------------- | ----------------------------------------------------------- |
| research skill 发现失败   | 跳过方法论增强, 继续本地+外部调研  | 不标工具失败; 仅在 conclusion 说明未使用外部 research skill |
| WebSearch/Fetch 报错      | 换 query 或换源重试 1 次           | `[工具失败: <原因>]` + 回传已得本地素材                     |
| 第三方平台无登录态/不可达 | 换公开网页 / 搜索索引 / 其他社区源 | 声明「该平台数据未覆盖」, 禁编造平台结论                    |
| 本地无关键实现            | 扩大 Grep 范围 / 转外部检索        | needs 标 `需要: 本地无据, 结论依赖外部`                     |
| 证据互相矛盾              | 保留矛盾双方, 不和稀泥             | conclusion 标「存在分歧」+ 列两说                           |
| 需求要选型拍板            | 给权衡不替选                       | needs 标 `需要: 待用户拍板` + tradeoffs 齐                  |