| name | t-tech-research |
| description | Assess technical feasibility for a feature. Scans codebase, checks dependencies, researches libraries, and writes a structured report under .ai/tech-research/. |
| allowed-tools | ["AskUserQuestion","Read","Glob","Grep","Task","Write","Bash","WebSearch","mcp__context7__resolve-library-id","mcp__context7__query-docs"] |
需求技术预研
运行时边界统一参考：${CLAUDE_PLUGIN_ROOT}/protocols/runtime-boundaries.md
需求来源边界统一参考：${CLAUDE_PLUGIN_ROOT}/protocols/requirement-source-contract.md
目标
基于 Decision Brief、用户需求和现有代码库，评估技术可行性、依赖缺口、代码影响范围和关键风险，生成报告供后续 /t-prd 或纯技术方案 /t-design 参考。
会影响技术路线、依赖选择、范围边界、兼容性、成本/风险结论、PRD 建议或后续 /t-design 输入的问题，必须通过 AskUserQuestion 解决；不得只写成 P0/P1 风险、显式假设或"需要更多信息"后继续收敛。
输出文件：
.ai/tech-research/<file-name>.md（file-name 取自 $ARGUMENTS 第一个空格前的部分）
如果未传 feature 名称，立即终止并提示：
请提供 feature 名称。例如：/t-tech-research user-management
输入与输出
输入：
.ai/decision/<file-name>.md（可选但推荐，来自 /t-decision）- 用户原始需求描述（参数、当前对话或补问获取）
- 现有代码库
- 可选：
docs/prd/00-index.md、docs/user-stories/00-index.md、.ai/user-stories/**/*.md、.ai/design/**/*.md
输出报告必须包含：
- 需求理解与技术需求提取
- 现有代码库评估（依赖和可复用模块）
- 差距分析
- 库调研与最佳实践（如适用）
- 影响分析
- 可行性判定
- PRD 编写建议
- 纯技术方案设计建议（如不涉及业务逻辑变动）
- 参考资料
参数规则
$ARGUMENTS 可包含两部分：<file-name> [补充描述]
- 第一个空格前的部分作为输出文件名（如
rag-otel-metrics）
- 空格后的部分作为额外的需求上下文，纳入需求理解
- 如果用户只传了一个词，则同时作为文件名和需求主题
- 文件名仅允许中文、英文、数字、下划线、连字符；推荐 kebab-case
- 拒绝
.., /, \
- 文件名长度限制 1 到 60 字符
- 如果用户传入的完整参数不含空格且为长中文描述（>20字符），主动提议一个简短的英文 kebab-case 文件名，经用户确认后使用
- 如果
.ai/tech-research/<file-name>.md 已存在，先询问是否覆盖
核心约束
- 先分析现有代码和依赖，再评估缺口；不凭空列举库
- 如果存在
.ai/decision/<file-name>.md，必须承接其中 Verdict、Scope Direction、D0/D1 决策和 Handoff；不得用技术预研改写产品立项结论
- 如果 Decision Brief 的 Verdict 是
Needs Clarification、Park 或 Reject，除非用户明确要求技术探索，否则应停止并提示先回到 /t-decision
- 依赖评估必须基于真实
Cargo.toml、package.json 和 lock 文件（如存在）
- 外部搜索只用于库级事实、最佳实践和兼容性信息，不能替代本地代码分析
- Context7 优先，WebSearch 只作补充
- 影响分析中的文件路径必须使用仓库真实路径，但只到文件或模块粒度；不写具体行号、函数签名、字段名、SQL 语句、DTO 字段或中间件实现细节
- 不产出 API 接口设计、数据库设计或任务拆解
- 报告聚焦于"能否做""需要什么""影响什么"；不写成"/t-design"级别的实现说明
- 技术路线只描述方向、集成方式与依赖选择，不给出具体 schema、接口字段、路由路径、代码结构或配置项命名
- 讨论时可多方案；最终报告必须收敛为单一、明确、可执行的技术路线
- 最终报告不得保留方案对比、候选排序或"可选/视情况"等开放式描述
- 被排除方向只写成确定约束或风险，不展开对比
- 显式假设只允许用于不影响技术路线、依赖选择、范围边界、兼容性、成本/风险结论和后续交付判断的非阻塞缺口
工作流程
1. 明确需求
如果当前对话中已有足够需求背景，不要重复提问。
仅在需求目标、约束、技术偏好或排除项不足以支撑可行性判断时，使用 AskUserQuestion 补问最少问题：
- 需求目标或问题陈述
- 期望的技术能力或效果
- 特定库或技术方向偏好
- 已知约束或排除项
如果缺失或冲突会影响技术路线、依赖选择、兼容性、影响范围、风险等级、是否进入 PRD 或是否可直接进入 /t-design，必须等待用户回答；回答前不得写入报告或给出收敛结论。
只有非阻塞缺口才可在写报告前转为 §6.2 显式假设。报告中不得留下"待确认"/"需确认"/"待定"/"TBD"等未决项。
2. 建立本地上下文
按需读取以下文件，跳过不存在的文件：
.ai/decision/<file-name>.mdbackend/Cargo.tomlfrontend/package.jsonCargo.lockpackage-lock.jsondocs/prd/00-index.mddocs/user-stories/00-index.md.ai/user-stories/**/*.md.ai/design/**/*.md
扫描真实代码目录，重点关注：
backend/api/backend/core/backend/sdk/frontend/src/
如果代码分析较复杂，可委托探索任务，要求返回相关实现位置、可复用点、影响模块和理由。
3. 分析差距
对比需求与现状，明确：
- 现有栈已覆盖的能力
- 需要新增或升级的依赖
- 可能需要替换的依赖
- 版本兼容性问题
- 现有代码需要修改的部分
4. 调研新依赖
仅当本地分析表明需要新依赖或需要补充库级事实时执行。
对每个候选库调研：
- 核心用法和 API 概览
- 与目标项目技术栈的集成方式
- 版本迁移注意事项（如适用）
- 常见陷阱、限制和兼容性问题
- 推荐版本和引入方式
如果不需要新依赖，在报告中写明"现有依赖栈可满足需求"并说明理由。
5. 决策收敛
把本地分析、依赖调研和人类讨论收敛为一个最终技术路线。
收敛规则：
- 只把最终选定的依赖、集成方式、影响范围和风险写入报告
- 不保留候选比较、备选路线或"可二选一"表达
- 因技术事实不足无法收敛时，结论可写"需要更多信息"，并列出需要继续调研的技术证据
- 因用户决策不足无法收敛时，必须使用
AskUserQuestion 提问；回答前不得把结论写成"需要更多信息"并继续交付
- 已排除方向只作为确定约束或风险写入
6. 生成影响分析
输出文件级和架构级影响：
- 需要新增或修改的文件
- 可能受影响的配置文件和测试文件
- 需要调整的模块边界、接口契约、数据流或全局配置
- 风险矩阵，风险等级使用 P0/P1/P2
7. 写入报告
使用 template.md 的结构生成 .ai/tech-research/<file-name>.md。
如果某章节不适用，保留章节并标记"不适用"及原因，不要直接删除。
收尾输出
完成后说明：
- 报告路径
- 可行性结论（可行 / 有条件可行 / 需更多信息 / 不建议）
- 需要引入的新库数量和名称（如适用）
- 主要影响范围
- 关键风险点
- 下一步命令：业务功能进入
/t-prd <file-name>；不涉及业务逻辑变动的纯技术方案可进入 /t-design <file-name>
质量门禁
生成前自检：
- 是否基于真实依赖文件做盘点
- 是否优先从现有依赖和代码中寻找方案
- 外部库调研是否覆盖核心 API、集成方式和已知限制
- 是否已收敛为单一明确技术路线
- 是否移除了方案对比、候选排序和开放式选择
- 报告是否不含任何"待确认"/"需确认"/"待定"/"TBD"等未决项；阻塞性未确认信息是否已通过
AskUserQuestion 解决，非阻塞缺口是否已转为显式假设
- PRD 编写建议是否明确可执行；如不涉及业务逻辑变动，是否说明可直接进入
/t-design
- 如存在 Decision Brief，是否没有偏离其目标用户、范围方向和已确认产品决策
- 影响分析中的路径是否真实存在
- 可行性判定是否明确
- 风险评估是否区分 P0/P1/P2
- 是否避免替代
/t-design 和 /t-task 的职责
失败处理
- 参数缺失：终止并给出
/t-tech-research <file-name> 示例
- Decision Brief 明确
Reject / Park 且用户未要求继续探索：终止并提示先回到 /t-decision
- 文件名非法：终止并说明允许字符范围
- 无法创建输出目录或写文件：终止并报告
- 需求描述不足：若影响可行性或路线判断，使用
AskUserQuestion 补齐，回答前不写报告；若不影响，只在报告中写入显式假设
- 既无代码库也无依赖文件：继续，但标记"无法评估现有实现，仅基于需求分析"
- Context7 查询无结果：降级到 WebSearch，在报告中标注信息来源
- WebSearch 也无结果：在报告中标记"外部信息不可用，依赖本地分析"
