afeaturemerge

afeaturemerge

参考一个系统的功能，系统性地分析并规划如何在我们自己的系统中实现，产出可执行的需求文档和技术方案。

---

第一步：信息收集

先解析输入 → 再自补 → 确认后动手

清单（按序完成）

1. 解析用户输入——从消息中提取已知信息
2. 自行补全——在追问前，先尝试从代码库/网络获取缺失信息
3. 展示理解摘要——向用户确认理解，收到确认后才开始调研

未展示摘要并收到用户确认前，不得开始调研。

解析清单

从用户消息中识别以下信息：

信息项	若缺失，如何处理
参考系统名称及目标功能	见下方"参考系统缺失时的处理逻辑"
我方目标应用/模块	必须追问，无法继续
参考系统文档/代码位置	自行 WebSearch 搜索；若 WebSearch 不可用，请用户提供链接
我方代码位置	自行 Grep 搜索，无需追问
特殊需求/约束	无则默认对齐参考系统

参考系统缺失时的处理逻辑

当用户明确说不知道参考哪个开源项目（如"我想加 X 功能，但不知道参考谁"），不要直接追问，而是：

第一步：WebSearch 主动推荐

用 WebSearch 搜索与该功能最相关的开源项目，关键词示例：

"{功能关键词} open source library best 2024"
"{功能关键词} framework comparison"

第二步：整理候选项

每个候选项说明：项目名、一句话定位、GitHub stars 量级、与用户场景的匹配度。

第三步：用 AskUserQuestion 让用户选择

AskUserQuestion({
  questions: [{
    header: "参考系统",
    question: "我找到以下几个常用的开源项目可供参考，你想对标哪一个？",
    multiSelect: false,
    options: [
      { label: "项目 A", description: "一句话定位，⭐ stars 量级" },
      { label: "项目 B", description: "一句话定位，⭐ stars 量级" },
      { label: "项目 C", description: "一句话定位，⭐ stars 量级" },
      { label: "其他", description: "请在 Other 文本框中填写你想参考的项目" }
    ]
  }]
})

用户选定后，将其作为"参考系统"填入摘要，继续执行 理解摘要确认 流程。

若参考系统名称已由用户明确提供但无文档位置，走原有的 WebSearch 自动补全逻辑，无需推荐。

理解摘要模板

解析完成后，先在消息中展示理解摘要，然后紧跟一个 AskUserQuestion 确认工具调用，让用户可以直接选择"确认，开始调研"或"需要调整"而无需手动输入：

我的理解：

• 参考系统：[X 系统的 Y 功能]
• 目标应用：[Z 应用/模块]
• 实现目标：[具体能力描述]
• 特殊约束：[无 / 列出约束]

AskUserQuestion({
  questions: [{
    header: "确认信息",
    question: "以上理解是否正确？",
    multiSelect: false,
    options: [
      { label: "确认，开始调研", description: "信息无误，可以继续" },
      { label: "需要调整", description: "请在 Other 文本框中说明需要修改的地方" }
    ]
  }]
})

追问规则

若有关键信息缺失（参考系统或目标应用不明确）：

• 每次只问一个问题，不要列出多个问题
• 必须使用 AskUserQuestion 工具呈现选项，不要在消息文本中写 A/B/C 列表——工具提供可用光标/回车选中的交互 UI，用户体验更好
• 收到回答后更新摘要，再次确认

AskUserQuestion 使用规范：

• header：问题的短标签（≤12 字），如"目标应用"、"功能范围"
• question：完整问题文字
• options：列出已知的候选项，最后一项留给"其他"，并在 description 里提示"请在 Other 文本框中填写"
• 若候选项超过 4 个，优先列出最可能的 3 项 + "其他"

示例（目标应用不明确时）：

AskUserQuestion({
  questions: [{
    header: "目标应用",
    question: "你希望在哪个应用里实现这个功能？",
    multiSelect: false,
    options: [
      { label: "应用 A", description: "..." },
      { label: "应用 B", description: "..." },
      { label: "其他", description: "请在 Other 文本框中填写应用名称" }
    ]
  }]
})

没有明确说明的地方，默认与参考系统保持一致。 若无参考系统可对标，直接进入 brainstorming 进行分析。

---

第二步：并行调研

使用 Agent 工具在同一条消息中启动两个 subagent（subagent_type: Explore），真正并行执行。 在发出调用前，将以下 prompt 模板中的占位符替换为第一步确认的真实值，再下发给 subagent。 两个 subagent 完成后，在主 context 中汇总其结构化报告，不要将原始调研内容搬入主 context。

启动 subagent 前：在主 context 调用 Skill({ skill: "slib:search" }) 加载多层检索策略，确认策略已加载后再发起并行调用。

Subagent A：参考系统调研

prompt 模板（将 {...} 替换为真实值后下发）：

你是一个技术调研 agent。请深入调研 {参考系统名} 的 {功能名} 实现。

调研目标（按顺序完成）：
1. 核心设计理念（为什么这样设计）
2. 关键接口/API，说明入参、出参、调用方式
3. 典型使用示例（保留最能说明问题的代码片段）
4. 已知限制或注意事项

调研资源——按以下 4 层顺序尝试，失败自动降级，不要停下来询问用户：

Layer 1：WebSearch（首选）
  WebSearch({ query: "{参考系统名} {功能名} 官方文档 OR github" })
  失败条件：报错 / 空结果 / 疑似防火墙拦截页（含"访问受限""sign in""403"等）→ 跳至 Layer 2

Layer 2：WebFetch
  WebFetch({ url: "<Layer 1 返回的可信 URL 或用户提供的链接>", prompt: "提取与「{功能名}」相关的核心信息" })
  失败条件：403 / 连接拒绝 / 超时 / 内容少于 200 字 → 跳至 Layer 3

Layer 3：curl
  Bash({ command: "curl -sL --max-time 15 -A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36' '<URL>' | sed 's/<[^>]*>//g' | grep -v '^$' | head -200" })
  失败条件：返回空 / 内容少于 100 字 / 含"403""404""blocked" → 跳至 Layer 4

Layer 4：chrome-mcp
  mcp__chrome-mcp__get_page_content(url="<URL>")
  若 ECONNREFUSED：pkill -f mcp-chrome-bridge && sleep 2 后重试一次

用户提供的链接或文档位置：{用户提供的链接，若无则填"无"}
知识库 MCP（如当前 session 已配置）可作为补充

要求：
- 结论必须有文档或代码来源，不要猜测
- 只返回结构化报告，不要返回原始文档全文

Subagent B：现有系统调研

prompt 模板（将 {...} 替换为真实值后下发）：

你是一个代码调研 agent。请在以下代码库中搜索 {功能名} 的现有实现。
代码库路径：{当前工作目录}

调研目标（按顺序完成）：
1. 是否有类似功能？实现程度如何？
2. 核心类/接口位置（包名/类名/文件路径）
3. 现有实现的局限性

调研方式：
1. Glob 查找相关目录和文件
2. Grep 搜索关键词：{从功能名推导的关键词，如类名、注解、方法名}
3. Read 阅读核心实现文件
4. 知识库 MCP（如当前 session 已配置）

要求：
- 若无任何相关实现，直接说明"当前无相关实现"
- 只返回结构化报告，不要返回完整代码文件

---

第三步：产出分析文档

基于调研结果，产出三份结构化文档，每份完成后立即写入当前项目的 docs/afeaturemerge/ 目录。

写入后由 SLib 通用 slib-sync hook 自动判断是否同步到云端知识库，无需在 skill 内手动处理。

文档一：参考系统功能实现分析

路径：docs/afeaturemerge/YYYY-MM-DD-[功能名]-ref-analysis.md

# [参考系统名] - [功能名] 实现分析

> 输入命令：[用户原始请求]
> 分析日期：YYYY-MM-DD
> 参考系统：[名称及版本]
> 文档/代码来源：[链接]

## 功能概述

（核心设计理念，3-5句话）

## 核心实现机制

（关键技术点，说明它如何工作）

## 关键接口 / API

（最重要的接口，带入参/出参说明）

```代码示例```

## 典型使用方式

（开发者如何使用，代码示例）

## 已知限制

（注意事项、边界条件）

文档二：现有系统功能情况分析

路径：docs/afeaturemerge/YYYY-MM-DD-[功能名]-current-analysis.md

# [我们的系统] - [功能名] 现状分析

> 输入命令：[用户原始请求]
> 分析日期：YYYY-MM-DD
> 系统：[应用/模块名称]

## 现有能力

（目前支持什么，哪怕部分支持也列出）
若无现有实现，直接写：**当前无相关实现**

## 当前实现

（核心实现位置：包名/类名/文件路径）

```代码示例（核心片段）```

## 已知局限

（现有实现的不足之处）

文档三：对比分析与实现规划

路径：docs/afeaturemerge/YYYY-MM-DD-[功能名]-implementation-plan.md

这是核心文档，分两部分：

3.1 对比分析表

功能点	参考系统	我们系统	是否可参考	说明
功能 A	✅ 支持	❌ 无	✅ 可直接参考	实现思路相同
功能 B	✅ 支持	⚠️ 部分	✅ 可参考改造	需适配我们的框架
功能 C	✅ 支持	❌ 无	❌ 不可参考	依赖其闭源组件

3.2 可以参考的部分

列出可以参考实现的功能点，调用 brainstorming 进行分析，产出：

• 需求文档：明确要实现什么，用户价值，验收标准
• 技术方案：具体实现步骤，涉及的类/模块，代码改动范围

3.3 不可以参考的部分

列出无法直接参考的功能点（依赖专有实现、技术栈不兼容等），调用 brainstorming 进行分析，从头设计，产出：

• 需求文档：明确要实现什么，用户价值，验收标准
• 技术方案：独立设计的实现方案

---

第四步：brainstorming → writing-plans

brainstorming 调用说明

对"可参考"和"不可参考"的每个功能块，分别调用 brainstorming。

调用时提供的上下文：

• 参考系统的相关实现（文档三·3.1 的分析结论）
• 我们系统的现有状态
• 需求的特殊要求（无特殊要求则默认对齐参考系统）
• 明确告知：可参考 → "请基于参考系统的实现方式给出方案"；不可参考 → "请独立设计方案"

---

调研质量标准

• 有依据，不猜测：结论来自实际文档或代码
• 两边都深入：参考系统和我们系统都要认真研究
• 差距有证据：指出"我们缺 X"时，要有参考系统的来源和我们缺失的代码证据
• 方案可落地：实现路径具体到模块/类级别
• 代码片段精选：只保留最能说明问题的关键片段

---

资源不足时的处理

情况	处理方式
参考系统文档找不到	WebSearch 搜索，若不可用则请用户提供链接
参考系统是闭源/内部系统	说明情况，请用户提供文档或描述
我们系统代码范围不确定	先用 Grep 搜关键词，逐步缩小范围
无现有实现	记录"无现有实现"，文档三的分析全部走"不可参考"流程（即 brainstorming 独立设计）
两边差距极小	诚实说明，指出可直接复用的具体实现

---

示例触发

示例一（参考系统明确）：

「参考 LangChain 的 Memory 机制，在 my-chat-app 里实现会话记忆功能」

执行顺序：

1. 解析需求，确认信息完整（参考系统、目标系统、功能点明确）
2. 展示理解摘要，等待用户确认
3. 收到确认后：并行调研 LangChain Memory 文档 + 搜索 my-chat-app 现有会话存储实现
4. 产出文档一（LangChain Memory 分析）→ 写入 docs/afeaturemerge/
5. 产出文档二（现有实现分析）→ 写入 docs/afeaturemerge/
6. 产出文档三（对比分析）→ 写入 docs/afeaturemerge/，区分可参考/不可参考部分，分别调用 brainstorming
7. brainstorming 产出设计文档和实现计划

---

示例二（参考系统未知，需推荐）：

「我想在 my-chat-app 里加个会话记忆功能，但不知道参考哪些开源项目比较好」

执行顺序：

1. 解析需求：目标系统明确（my-chat-app），功能点明确（会话记忆），参考系统缺失且用户不确定
2. WebSearch 搜索相关开源项目（如 "conversation memory open source library best 2024"）
3. 整理候选项（如 LangChain、LlamaIndex、MemGPT 等），用 AskUserQuestion 让用户选择
4. 用户选定（如 LangChain）后，补全摘要，展示理解摘要并请用户确认
5. 收到确认后：后续流程与示例一相同（并行调研 → 产出三份文档 → brainstorming）