docs(agents): dedupe evidence rules and make link commands self-contained

Author: ulleo

AGENTS.md

@@ -4,16 +4,14 @@ SQLBot 让业务用户用自然语言提问，基于已配置的数据源生成
 
 ## 任务流程与交付
 
-- 开始前确认目标仓库、分支、HEAD 和已有改动；验证 PR 时记录 head SHA。需要其他版本时优先用独立 worktree，不覆盖、清理或提交用户已有无关改动。
-- 根据任务定义可观察的验收条件，再阅读相关入口、调用方和测试；只加载下表中与任务有关的文档。评审不等于授权修复或合并，已授权的动作不重复询问。
-- 在范围内自主处理可逆的实现和验证细节；先查源码、测试和文档，只对无法确定且影响业务语义、数据安全或交付范围的问题询问，同时继续不依赖答案的工作。
-- Bug 修复先复现，再验证修复后行为；证据层级、基线对照和环境失败处理见 `docs/agents/testing.md`。不要以消除报错代替满足验收条件。
-- 交付说明改了什么、为何改、实际执行的验证及结果、未覆盖范围和阻塞项；明确是建议合并、已创建 PR 还是已合并。测试代码应与交付提交一致，之后如有相关改动需重新验证。
-- 任务要求最新代码时，在开始和交付前核对远端目标 SHA；远端变化后评估影响，必要时更新并重测，不把旧版本结果标成最新验证。
+- 开始前确认目标仓库、分支、HEAD 和已有改动；需要其他版本时优先用独立 worktree，不覆盖、清理或提交用户已有无关改动。验证 PR 或最新代码时，开始和交付前都核对远端目标 SHA；远端变化后评估影响，必要时更新并重测，不把旧版本结果标成最新验证。
+- 根据任务定义可观察的验收条件，再阅读相关入口、调用方和测试；只加载下表中与任务有关的文档，不以消除报错代替满足验收条件。评审不等于授权修复或合并，已授权的动作不重复询问。
+- 在范围内自主处理可逆的实现和验证细节；只对无法确定且影响业务语义、数据安全或交付范围的问题询问，同时继续不依赖答案的工作。
+- 交付说明改了什么、为何改、实际执行的验证及结果、未覆盖范围和阻塞项，并明确交付形态（建议合并 / 已创建 PR / 已合并）。证据记录、Bug 复现和基线对照以 `docs/agents/testing.md` 为准；测试代码应与交付提交一致。
 
 ## 规范维护
 
-本文及按需文档是开发约定，不是现有实现已满足所有约束的证明。文档与实现冲突时先核实并报告差异；不要为迎合旧实现削弱安全要求。行为和命令变更时同步维护对应文档；易漂移的实现细节注明源码入口或适用版本，避免多处复制。领域词汇约定不要求重命名现有 API、数据库字段或翻译键。
+本文及按需文档是开发约定，不是现有实现已满足所有约束的证明。文档与实现冲突时先核实并报告差异，不要为迎合旧实现削弱安全要求；易漂移的实现细节注明源码入口或适用版本，避免多处复制。领域词汇约定不要求重命名现有 API、数据库字段或翻译键。
 
 ## 仓库结构
 

docs/agents/xpack.md

@@ -27,11 +27,14 @@ SQLBOT_XPACK_REPO=/replace/with/your/sqlbot-xpack-checkout
 | `false` | 继续使用已发布 wheel。不读取路径、不安装 editable 包、不修改 xpack、不重复询问。若任务无法绕开闭源实现，说明需要用户主动开启开关。 |
 | `true` | 验证路径后读取目标仓库根目录的 `AGENTS.md`，在已授权的任务范围内联调；开关本身不授权无关修改、推送或发布。 |
 
-路径目录名可以任意，但必须是指向 xpack Git 仓库根目录的绝对路径；用 `git -C "$SQLBOT_XPACK_REPO" rev-parse --show-toplevel` 验证。环境变量优先于 `AGENTS.local.env`。不要静默覆盖该文件，也不要在其中保存密钥。
+路径目录名可以任意，但必须是指向 xpack Git 仓库根目录的绝对路径；用 `git -C "$SQLBOT_XPACK_REPO" rev-parse --show-toplevel` 验证。环境变量优先于 `AGENTS.local.env`；文件按键值读取（不 `source` 执行内容、不展开变量），只接受 `SQLBOT_XPACK_LINK_ENABLED` 和 `SQLBOT_XPACK_REPO` 两个键，未知键或值无效时报错而非忽略。不要静默覆盖该文件，也不要在其中保存密钥。
 
 本地联调前按上述优先级读取两个配置值：已设置的环境变量优先，只从本机可信配置文件补齐未设置项；不要直接 `source` 文件覆盖环境变量或执行其中任意 shell 内容。确认开关为 `true` 且路径验证通过后，导出解析得到的 `SQLBOT_XPACK_REPO`。下面命令从 SQLBot 根目录运行，作用于选定后端环境；优先使用隔离环境，使用共享环境时先确认受影响的运行服务，并记录恢复方式：
 
 ```bash
+# 按键值读取 AGENTS.local.env（只取值，不 source 执行文件内容）；环境变量已设置时优先
+SQLBOT_XPACK_REPO="${SQLBOT_XPACK_REPO:-$(sed -n 's/^SQLBOT_XPACK_REPO=//p' AGENTS.local.env | tr -d "\"'")}"
+test -n "$SQLBOT_XPACK_REPO" || { echo "SQLBOT_XPACK_REPO 未配置" >&2; exit 1; }
 cd backend
 uv pip install -e "$SQLBOT_XPACK_REPO"
 uv run --no-sync pytest -q