| date | YYYY-MM-DD |
|---|---|
| summary_en | One-line summary in English, used in README.md Updates section. |
| summary_zh | 一行中文摘要，用于 README_ZH.md 更新记录段。 |
必填: 每个 changelog 文件顶部必须有 YAML frontmatter，包含
date、summary_en、summary_zh三个字段。 运行pnpm docs:sync会自动读取这些字段生成 README.md、README_ZH.md 和 docs/README.md 的更新日志段。
本轮更新围绕一个核心收口目标展开：
用一句话概括这次更新的核心意图。建议写成"要把什么能力从什么状态推进到什么状态"。
这里回答“为什么要做这次更新”，而不是直接罗列改了什么。
建议覆盖：
- 当前主路径、能力或运维上遇到了什么真实问题
- 为什么这些问题值得在这一天集中收口
- 这次是新增能力、默认化、治理化，还是补齐一致性
可直接套用的写法：
- 某项能力已经具备最小可用性，但仍停留在可选或分散状态
- 当前实现、默认行为、测试和文档之间存在落差
- 在真实使用、接入或运维过程中，已经出现重复样板、解释不足或口径漂移
这里回答“这次想解决哪几类问题”。
建议写成 3-5 条明确目标，例如：
- 降低某条主路径的接入门槛
- 统一实现、注册元数据、测试和文档口径
- 提升解释性、可观测性或治理能力
- 保留兼容路径，避免默认增强变成破坏性变化
这里回答“具体是怎么改的”。
建议分 2-5 组动作写，每组最好有明确标题。
可直接套用的结构：
- 改了什么默认值
- 哪个入口成为主路径
- 哪些旧入口保持兼容
- 哪些 handler / store / schema / pipeline 发生了调整
- 是否做了迁移、兼容、降级或兜底
- 改了哪些测试
- 哪些 README / docs / 监控面一起同步
这里回答“用户、调用方、值班同学、后续开发者因此少踩了哪些坑”。
建议写成问题导向：
- 问题 1 之前是什么现象，这次怎么缓解。
- 问题 2 之前为什么难用、难查或难解释，这次怎么改善。
不要只写“新增了 X、支持了 Y”，而要写“因此解决了什么”。
这里回答“这次没打算解决什么，以及现在推进到了什么程度”。
建议覆盖：
- 这次更新刻意保持了哪些边界
- 哪些旧调用或旧数据仍然兼容
- 当前能力已经推进到什么状态，但还不代表解决了所有相关问题
这里列“哪些文件、命令、MCP 工具或 HTTP 入口是本次变化的主要承载点”。
建议按用户最容易定位的入口写，例如：
src/...tests/...docs/...contextatlas ...tool_name/healthz
对外文档约束：
- 不要写本地文件系统路径，例如
~/...、/home/...、/Users/... - 不要写仅作者自己可见的工作区、沙箱或临时目录信息
- 如果需要引用外部项目，对外只写公开项目名，必要时补公开链接
这里回答“什么证据表明这次更新是收口过的，不是只改了代码或文档”。
建议包含：
pnpm build
pnpm test如果有特殊说明，也写清楚：
- 哪些验证是本次放行门槛
- 哪些相关链路暂时不作为门槛，以及原因是什么
以下是一段最小示例，展示这套模板的写法风格：
某个 MCP 工具已经支持可选参数，但默认行为仍停留在旧模式，导致调用方需要反复补同一个参数。
# ContextAtlas 更新总结（2026-04-10）
本轮更新围绕一个核心收口目标展开：
> 让 `codebase-retrieval` 的轻量图谱摘要从“可选增强”升级为“默认带出”，降低调用方参数负担，同时保持显式关闭能力。
## 一、为什么要更新
- 轻量图谱摘要已经具备独立可用性，但仍要求调用方显式传参
- 客户端、prompt 模板和 wrapper 层反复补同一个参数
- 实现已准备好，但默认行为、测试和文档仍停留在旧口径
## 二、这次更新的目标
1. 让常见检索调用默认更完整
2. 统一实现、元数据、测试和文档口径
3. 保留显式关闭能力
## 三、如何更新
### 1. 默认值调整
- schema 默认值改为开启
- 注册元数据同步改为开启
### 2. 同步回归与文档
- 更新回归测试覆盖默认开启
- 更新 MCP 文档和 changelog 索引
## 四、解决了什么问题
- 默认结果信息密度不足的问题得到缓解
- 客户端接入不再需要重复补样板参数
## 五、边界、兼容性与当前状态
- 仍然只返回轻量直接图谱摘要
- 仍可显式传 `false` 关闭
## 六、涉及文件、命令与入口
- `src/mcp/tools/codebaseRetrieval.ts`
- `src/mcp/registry/tools.ts`
- `tests/codebase-retrieval.test.ts`
## 七、验证口径
```bash
pnpm build
node --import tsx --test tests/codebase-retrieval.test.ts