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 齐 |