Repowise Why 深度指南:用决策记录、意图溯源与 Git 考古回答"代码为什么长这样"
Repowise Why 深度指南:用决策记录、意图溯源与 Git 考古回答"代码为什么长这样"
repowise why 是 Repowise 代码库情报系统中专门回答"代码为什么长这样"的命令:它查询已记录的架构决策(ADR)、代码内 rationale 注释,并在决策缺失时回退到 Git 历史考古,把"规则"与"推测"严格区分开。本指南以 repowise-why.md 为核心骨架,结合 why_cmd.py 与 MCP 工具 get_why 的源码实现,完整讲解五种调用模式、共享定位参数与底层工作流。读完你将能在重构、模式偏离或代码评审之前,用一条命令获得一份可溯源、绝不臆造的设计依据。
命令定位:get_why 的 CLI 适配层
repowise why 是 MCP 工具 get_why 的 CLI 适配器(why_cmd.py 的模块 docstring 明确写道:"the CLI adapter over the get_why MCP tool")。它的职责是查询代码为什么是现在这个样子,而不是管理决策记录:
/prompts:repowise-decision(对应 repowise-decision.md)负责决策记录的管理:列出、新增、确认(accept)与弃用;repowise why只负责查询:给出决策、对齐度(alignment)与考古证据。
因此官方用法建议是:在重构之前、或刻意偏离既有模式之前,先运行 repowise why,确保 Agent 不是在对着一份用户已经签字认可的决策盲改。
前置条件:仓库必须先被索引
运行前检查 .repowise/ 目录是否存在:
- 若
.repowise/不存在,直接回复:"This repo isn't indexed yet. Run/prompts:repowise-initfirst." 并停止执行——决策存储、Git 元数据与语义向量都依赖索引产物; - 若已索引,将
$ARGUMENTS映射到下方五种模式之一,执行repowise why,并向用户展示决策(decisions)、对齐度(alignment)与考古证据(archaeology)。
其中有一条对 Agent 的硬性约束:绝不虚构 rationale。如果命令回退到了 Git 考古(即证据来自历史提交而非决策记录),必须明确告知用户这一点,让用户知道答案是"重建的"而非"记录的"。
五种调用模式
模式一:自然语言问题
repowise why "why is auth using JWT?"
将整个问题作为 query 传给 get_why,进入搜索模式(Mode 3)。从 tool.py 的源码可以看到分发逻辑:
- 若
query被_is_path(query)判定为路径,走路径模式; - 否则进入
_why_search(query, targets, repo),即自然语言、目标感知的决策 + 文档搜索。
搜索模式内部(search.py)会:先对决策语料做关键词排序,再视索引是否含语义向量决定是否补充一次向量检索(决策与文档按命名空间拆分,DECISION_VECTOR_PREFIX 前缀判定),最后合并去重后的决策行、相关文档与 episodes,并附上 evidence 标注。
模式二:文件路径(治理决策 + 起源故事)
repowise why src/api/auth.py
query 是一个文件或模块路径时,get_why 返回三块内容(path_mode.py):
- governing decisions:按
_records_naming_path筛选出 scope 真正绑定到该路径的记录(只匹配binds_to_paths(d.scope_basis)为真的记录,避免把"决策来源提交的波及文件"误当作被治理文件),再按_path_decision_sort_key排序、按权威性拆分; - origin story:
_build_origin_story从 Git 元数据重建起源——总提交数、年龄(天)、主要作者及占比、首个/最近提交、关键提交列表; - alignment score:
_compute_alignment用该路径命中的决策标题/ID 对全体决策计算覆盖度分数,并附解释。
权威性拆分(_split_by_authority)把命中记录分成三档:governing(被 accept 且当前仍生效)、candidates(从未被 accept,是评审请求而非规则)、retired(曾被 accept 但已 superseded/withdrawn,是历史而非规则)。对排名第一的 governing 记录,_stamp_still_true 还会询问 Git 判断"该决策现在是否仍然成立",把结果作为 still_true 一句话印在记录上。
模式三:目标锚定搜索(Target-anchored search)
repowise why "why the retry cap?" --target src/api/client.py
问题 + --target 的组合,让搜索锚定到具体文件。--target 可重复传入(multiple=True),每个目标会生成一张卡片(target_context[target]),包含其 governing decisions、candidates、origin 与 archaeology。
源码层面有一个值得注意的细节:_focus_target_context(search.py)会按问题相关性收窄每张卡片——否则一张基于路径构建的卡片会对关于该文件的所有问题给出相同字节。收窄规则:
governing_decisions豁免:被 accept 的规则无论问题是什么都约束该文件;candidate_decisions、origin.linked_decisions与 archaeology 各层都要过query_scorer的相关性底线;全部落空时,该 lane 变成<key>_omitted:一个计数加一条恢复调用(get_why(targets=[...])),让"没有历史提到你问的问题"与"没有历史"两种情形区分开。
模式四:--target 且无问题(单目标 = 路径模式,多目标 = 每张卡片)
repowise why --target src/api/client.py # 单目标
repowise why --target src/api/client.py --target src/api/server.py
不带问题只带目标时,目标本身就是问题。源码(path_mode.py)给出了明确的工程取舍:
- 单目标直接路由到
_why_path(targets[0], repo),即完整的路径模式答复; - 多目标为每个目标构建
_target_card:governing decisions(仅 accepted)、candidate_decisions、origin 与 archaeology 回退。卡片模式而非逐一路径模式,是因为每个路径模式都要一次语料扫描加一次 Git 子进程,多目标时成本过高。
_target_card 的 archaeology 回退键在 accepted 语言上:只有 candidates 而没有 accepted 记录的文件被视为"无治理",此时其提交历史比一条未确认的 candidate 更有证据力。
模式五:无参数——决策健康仪表盘
repowise why
无 query、无 target 时,命令变成一次**定向调用(orientation call)**而非回答:返回决策健康仪表盘(dashboard.py),通过 get_decision_health_summary 汇总:
summary/counts:active、stale、proposed、ungoverned hotspots 的数量;stale_decisions:含staleness_score的过期决策;proposed_awaiting_review:待评审提案;ungoverned_hotspots:无任何决策治理的热点路径;conflicts、retired_decisions、unscoped_decisions(已 accept 但未命名任何文件的记录)。
CLI 侧渲染(why_cmd.py)会把 counts 画成一张 rich 表格(标题 "Decision health"),随后按序渲染各 lane。
机器可读与原始载荷:--format json / --full
repowise why "why is auth using JWT?" --format json
repowise why src/api/auth.py --full
--format json:输出project()裁剪后的 JSON。project的裁剪策略(why_cmd.py)按模式保留不同字段:搜索模式保留query/decisions/related_documentation/episodes;路径模式保留path/alignment/decisions/origin_story及无治理时的三个替代块(git_archaeology、code_rationale、target_context);仪表盘模式保留 summary、counts 与各 lane 的头部。--full:返回get_why的原始字典,不做裁剪。由于原始字典没有表格渲染形式,--full隐含 JSON 格式(resolve_format_for:--fullimplies json)。
被裁剪掉的字段(如决策的 context、consequences、alternatives、lineage、confidence、staleness_score,以及 origin_story.summary 等约 2K 字符的散文)在 --full 下都会回来。CLI 还会诚实标注截断:每个被裁剪的列表都附 N of M shown 计数与 "pass --full for the rest" 提示。
共享定位参数
repowise why 与其余 tool-adapter 命令共享同一组定位选项(target_options):
| 参数 | 作用 | 默认值 |
|---|---|---|
--path <dir> |
指定仓库(或工作区)根目录 | 当前目录 |
--repo <alias> |
在工作区模式下选择要查询的仓库别名(隐含工作区模式) | 主仓库 |
--no-workspace |
即使从工作区调用也强制单仓库模式 | false |
--format <fmt> |
输出格式(含 json) | 表格 |
--full |
输出原始完整载荷(隐含 json) | false |
仓库解析由 resolve_indexed_repo 完成:工作区模式会选出一个仓库而非扇出执行——这些工具按构造就是单仓库的(见 tool_bridge),--repo <alias> 选择接谁的资源,默认主仓库。--no-workspace 用于明确强制单仓库语义。
回答边界与诚实原则(Notes)
原文档的三条 Notes 定义了命令的行为契约,源码完全印证:
- 路径永不返回空:路径没有决策时,
get_why回退到 Git 考古——_add_ungoverned_evidence调用_git_archaeology_fallback生成三层考古(file_commits本文件关键提交、cross_references交叉引用、git_log活日志),并顺带挖掘代码内 rationale 注释(_mine_rationale)。CLI 必须把这一点讲清楚:回答是重建的(reconstructed),不是记录的(recorded)。 - 问题无答案时重定向而非填补:决策存储回答不了的问题,返回空决策、一句原因说明,并指向更契合该问题形态的工具(
redirect_for/redirect_when_served,见 search.py 的_why_no_match)。Agent 要转达这个重定向,而不是自行脑补答案——空结果只说明决策存储里没有东西,不代表问题不可回答。若有 rationale 注释或携带问题词条的提交能过相关性底线,则作为证据(而非决策)一并提供。 - 管理 vs 查询分离:新增 / confirm / 弃用 ADR 记录请用
/prompts:repowise-decision。
另外有一条面向 Agent 的协作规则:在反驳一条既有决策之前,先把该决策展示给用户。
响应预算与裁剪:get_why 的源码级细节
get_why 对每种模式都设定了响应上限(caps.py),避免长列表浪费 Agent 的上下文:
- 路径模式:governing 记录最多
_MAX_PATH_DECISIONS = 8条;每条记录的受影响文件最多 10 个;candidates 内联最多 3 条; - 搜索模式:决策最多
_MAX_SEARCH_DECISIONS = 3条("超过第三个命中后排序已不足以让 Agent 花费上下文");语义窗口_SEMANTIC_WINDOW = 50;决策语料上限_DECISION_CORPUS_LIMIT = 2000; - 仪表盘:stale / proposed 各 5 条,ungoverned hotspots 8 条,retired / unscoped 各 5 条,conflicts 10 条;
- archaeology 各层:
file_commits10、cross_references10、git_log20。
路径模式还有一层传输预算贴合:_fit_path_response(caps.py)按"最廉价损失优先"逐级裁剪——先丢与 decisions 重复的 linked_decisions、再丢评审 lane、然后丢 episodes、再从尾部丢 governing 记录(空列表 + 标记也胜过被拒收的响应)、最后裁剪 ungoverned 分支的 rationale/archaeology/origin_story。每次裁剪都进入 omission collector(_meta.omitted + omission_marker),保证被剪掉的每一行都可恢复。
CLI 侧的 _project_decision、_project_archaeology、_project_target_entry(why_cmd.py)与之一致:每个被裁剪列表都携带 _total 计数,让 "5 of 18" 不会被误读成 "18"。
验证与测试
仓库为 get_why 提供了系统的测试覆盖,可作为行为契约的补充阅读:
- tests/unit/server/mcp/test_why.py、test_why_question_lanes.py、test_why_health_payload.py、test_why_search_payload.py、test_why_scope_basis.py 分别锁定各模式契约;
- tests/unit/cli/test_tool_adapter_commands.py 与 tests/unit/cli/test_tool_bridge.py 验证 CLI 适配层与参数解析;
- test_why_evidence_contract.py 验证 evidence 标注契约——相同
provenance/evidence_refs匹配 ID 表示共享证据,而非独立佐证。
何时该用 repowise why
一句话总结适用场景:在重构、模式偏离、代码评审或"这段代码为什么没有按常识写"的质疑发生之前,先跑 repowise why 拿到治理决策、对齐度与考古证据;如果目标是新增、确认或弃用一条决策记录,则改用 repowise decision。两者配合,才能在代码库中建立"有据可循、可追溯、不靠猜"的设计变更文化。