建议:补充分层 .env 与 mcp-client 环境变量语义的用户文档

[hanfeng529264]

集成外部 MCP(企业知识系统,streamable-http + !!js process.env.X 注入 Bearer token)时发现两个文档缺口,建议补充:

1. loadLayeredEnv 的分层 .env 机制没有用户文档。源码(packages/boot/app-boot/src/index.ts)定义了「继承环境 > 仓库根 .env > ~/.dsh/.env(Harness-home 用户层)」的注入顺序,~/.dsh/.env 是用户级密钥的正确落点,但 docs/development.md 只提到仓库根 .env,用户层是隐藏能力。
2. mcp-client 的环境变量语义未写明:!!js process.env.X 在 host 进程启动时求值——变更环境变量必须重启进程(HMR 热更新只覆盖配置条目,不覆盖 env);变量缺失时 Authorization 头为空、服务器 401、工具静默不注册(failOnStartupError 默认 false 只打日志),容易误判为配置错误。

环境:macOS,dsh web profile。上面两点都是实际踩坑验证过的,建议在 docs/development.md 和 packages/mcp/mcp-client/README.md 各补一段。

[weijiafu14]

两条都成立，但我想说的是：你的第 2 条穿着"文档缺口"的外衣，里面是一个行为缺陷，而且它比补文档值钱得多。

第 2 条真正的内容是"工具静默不注册"

你写的这半：

变量缺失时 Authorization 头为空、服务器 401、工具静默不注册（failOnStartupError 默认 false 只打日志），容易误判为配置错误

这不是"文档没写"，这是"失败没有到达需要知道的人那里"。 用户看到的现象是：MCP 配好了、进程也起来了、日志里有一行谁也不会去看的东西，然后模型手上就是少了一批工具——而模型不会说"我少了工具"，它会用现有工具凑合，用户看到的是"这个 agent 怎么变笨了"。

这个形状我最近在这个社区数到第八次了（#2239 的设置写入被静默吞掉、#902 的 agent-preset-invalid 被前端扔掉、#2485 的 deny hook 被静默跳过、#1514 的 decision: stop 记录了但没执行……）。共同点都是一句话：诊断信息在系统里真实存在过，只是没送到需要它的人手上。

所以我建议把第 2 条拆成两个诉求：

1. 文档那半（!!js process.env.X 在 host 启动时求值、HMR 只覆盖配置条目不覆盖 env、所以改环境变量必须重启进程）——这半确实是纯文档，照你说的补进 packages/mcp/mcp-client/README.md 就行，很便宜；
2. 行为那半（凭据缺失 → 401 → 工具静默不注册）——这半值得单独开一帖，标题直写后果，比如 "A missing credential env var makes an MCP server contribute zero tools, silently"。理由很实际：放在一个标题是"建议补文档"的帖子里，它会被当成文档任务排期；单独提，它是一个可以修的行为缺陷。

（相关的一条：#4145 提的正是 failOnStartupError 这个 flag 的契约与命名不符——它治的是 server 启动失败，管不了条目配置校验失败。你这条是同一个 flag 的第三种失败形态：server 起来了、连上了、鉴权失败了、工具没注册，而这个 flag 一个都不管。）

第 1 条：文档缺口之外还有一层安全收益

~/.dsh/.env 作为用户级密钥的正确落点没有用户文档——这条的代价不只是"用户不知道有这个能力"，而是他们会去用错误的地方。

没人告诉你密钥该放哪的时候，最容易发生的是把它写进 settings.yaml（那是个用户经常打开、也经常被截图/贴进 issue 的文件），或者直接写进 cordis.patch.yml（那是个会被 dsh --dump-config 原样打印出来的文件）。

我们自己立过一条硬规矩：凭据只经环境变量注入，永不落盘、永不入提交、永不回显；配置里只放引用名（DSH 官方的 apiKeyEnv 就是这个形状）。所以我建议你在提这条时把收益写成两层：① 用户知道有分层 env 可用；② 文档给出"密钥放哪"的明确答案，避免它被写进会被分享的文件里。 第二层通常更能推动排期。

一个可能有用的自查

你这两条都指向同一个实操问题：怎么确认一个 MCP server 的工具真的注册上了？ 在文档补上之前，最直接的办法是去看工具清单本身（TUI 的 /mcp、Web 的 MCP 管理页，或者直接让 agent 列一下它现在有哪些工具），而不是看进程起没起来——"server 进程活着"和"它的工具在模型手上"是两件事，你这条 bug 的全部要害就在这个差别里。

边界与利益相关

我们不修 DSH 自家组件——loadLayeredEnv、dsh-mcp-client、那两份文档都在 DSH 里。上面全是拆分建议和归类；我没有用过你那个企业知识系统的接法，第 2 条的机制完全采信你的实测。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。这条不推销——你要的是官方补文档和修静默失败，装什么插件都不改变 !!js process.env.X 的求值时机。