wpfbcr · Oct 12, 2026 · Oct 12, 2026 · Oct 12, 2026
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
@@ -0,0 +1,27 @@
+name: Offline regression tests
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ['3.9', '3.12']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -r requirements-dev.txt
+      - name: Install CJK font for Linux
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y fonts-noto-cjk fonts-wqy-zenhei
+      - run: python -m unittest discover -s tests -v
+      - name: Validate CFF CJK export on Linux
+        if: runner.os == 'Linux' && matrix.python == '3.12'
+        env:
+          ATLAS_FONT: /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc
+        run: python -m unittest discover -s tests -p test_runtime.py -v
diff --git a/AGENTS.md b/AGENTS.md
@@ -14,7 +14,7 @@ Full guide: [docs/install.md](docs/install.md)
 
 ```bash
 export ATLAS_ROOT="${ATLAS_ROOT:-$HOME/AtlasAgent}"
-bash "$ATLAS_ROOT/scripts/atlas-agent doctor"
+bash "$ATLAS_ROOT/scripts/atlas-agent" doctor
 ```
 
 ## Skills (9)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -18,10 +18,21 @@
 
 ## 验证
 
+离线回归检查（安装测试仅写入临时目录，不修改真实的用户配置）：
+
+```bash
+python3 -m pip install -r requirements-dev.txt
+python3 -m unittest discover -s tests -v
+for script in scripts/install.sh scripts/atlas-agent scripts/atlas-env.sh; do
+  bash -n "$script" || exit 1
+done
+```
+
+可选的联网连通检查：
+
 ```bash
 export ATLAS_ROOT="$(pwd)"
 python3 scripts/weather_client.py forecast --city Paris --days 3
-bash scripts/install.sh cursor   # 本地测试安装
 ```
 
 ## License

diff --git a/README.md b/README.md
@@ -191,10 +191,15 @@ scripts/                → 可执行 CLI（doctor 会检查）
 | `atlas-agent install --agent=cursor` | 仅安装到 Cursor |
 | `atlas-agent install --safe` | 只输出手动步骤 |
 | `atlas-agent install --dry-run` | 预览将执行的操作 |
+| `atlas-agent install --overwrite` | 备份后替换已有不同内容的技能 |
 | `atlas-agent doctor` | 健康检查 |
 | `atlas-agent doctor --json` | JSON 格式输出 |
+| `atlas-agent doctor --offline` | 跳过联网检查，明确标记降级状态 |
+| `atlas-agent install --env=none` | 保留 shell 配置 |
 | `atlas-agent check-update` | 更新指引 |
 
+安装默认保留已有技能：相同内容跳过，遇到不同内容先停止。检查冲突后，可用 `--overwrite` 备份并替换；备份路径见安装输出。详见[安装说明](docs/install.md#existing-skills)。
+
 ---
 
 ## 贡献

diff --git a/docs/install.md b/docs/install.md
@@ -91,6 +91,18 @@ This installs:
 2. `ATLAS_ROOT` in `~/.zshrc` or `~/.bashrc` (unless `--safe`)
 3. Optional: `pip3 install fpdf2` for PDF export
 
+### Existing skills
+
+Shell configuration is maintained in a project-owned block; moving the checkout updates that block while preserving other settings. `--env=none` skips shell changes. Identical skills are left in place. If any existing skill differs, installation stops before changing any target's skills or shell configuration. Review the conflict first. To replace changed skills explicitly:
+
+```bash
+bash "$ATLAS_ROOT/scripts/atlas-agent" install --agent=cursor --overwrite
+```
+
+Each replaced skill is moved to a unique directory under the target's `skills/.atlas-backups/`; the installer prints the full backup path. The new copy is staged before the old skill moves, and a failed final move restores the previous skill. Backups are retained for manual recovery. This protects each replaced skill; a later installation failure can still leave earlier skills updated.
+
+For an isolated installation or test, `ATLAS_USER_HOME` selects a separate user configuration directory for `install.sh`; it defaults to the current user's home. This setting does not change `HOME`; doctor checks the same selected user configuration directory.
+
 **L0 zero-config channels (no API key):**
 
 - Weather → Open-Meteo (`weather_client.py`)
@@ -181,3 +193,7 @@ rm -rf ~/.cursor/skills/atlas-agent ~/.cursor/skills/weather ~/.cursor/skills/cu
 # Remove ATLAS_ROOT line from ~/.zshrc if desired
 # rm -rf ~/AtlasAgent
 ```
+
+## Diagnostic states
+
+`doctor` validates all runtime scripts and all nine skills in each supported agent directory. Required failures return exit code 1; missing optional PDF support or uninstalled agent copies produce a degraded status. `doctor --json` uses valid JSON serialization for every path. `doctor --offline` skips API requests and reports degraded readiness rather than claiming online availability. PDF capability is verified by a small CJK export, including the installed version and font.
diff --git a/docs/update.md b/docs/update.md
@@ -25,19 +25,27 @@ export ATLAS_ROOT="${ATLAS_ROOT:-$HOME/AtlasAgent}"
 git -C "$ATLAS_ROOT" pull
 
 # 2. Re-install skills (detect user's agent or use all)
-bash "$ATLAS_ROOT/scripts/atlas-agent install --env=auto --agent=all
+bash "$ATLAS_ROOT/scripts/atlas-agent" install --env=auto --agent=all
 
 # 3. Verify
-bash "$ATLAS_ROOT/scripts/atlas-agent doctor"
+bash "$ATLAS_ROOT/scripts/atlas-agent" doctor
 ```
 
 If `git pull` fails (local changes), ask the user before resetting.
 
+If installation reports a skill conflict, inspect the installed changes and the new repository version. The existing skills remain intact. After choosing to replace them, run:
+
+```bash
+bash "$ATLAS_ROOT/scripts/atlas-agent" install --env=auto --agent=all --overwrite
+```
+
+This preserves each replaced skill under its target's `skills/.atlas-backups/` and prints the backup path. Identical skills are skipped. A later failure may leave earlier skills updated; retain the backups until the update is verified.
+
 ### Optional
 
 ```bash
 pip3 install -U fpdf2
-bash "$ATLAS_ROOT/scripts/atlas-agent check-update"
+bash "$ATLAS_ROOT/scripts/atlas-agent" check-update
 ```
 
 Report doctor output to the user. Mention new destinations or skills if CHANGELOG/README changed.
diff --git a/examples/chengdu-5days-zh.md b/examples/chengdu-5days-zh.md
@@ -0,0 +1,127 @@
+# 双人成都5日游 · AtlasAgent 实际验证输出
+
+2026年10月19–23日｜2人｜成都当地集合｜当地总预算 CNY 5000｜可吃微辣
+
+这是一份经用户确认条件的测试方案：没有已订交通和酒店，不包含出发城市往返成都的大交通。景点、酒店和餐厅的存在与部分参观规则有来源；酒店、餐饮、都江堰票价与交通费用为规划估算，并非实时库存报价。餐厅菜品是点餐建议，是否供应及微辣做法需门店确认。
+
+## 行程主题与预算结果
+
+熊猫、城市文化和水利遗产，地铁/步行加少量打车，4晚固定住市中心，避免频繁搬酒店。
+推荐方案A当地合计 CNY 4279，人均 CNY 2139.50；含10%应急金，低于两人预算 CNY 721。仅D4为较紧日，其余保留休息与雨天调整空间。
+国内行程，签证分析不适用；酒店入住和实名预约携带本人有效证件。时区 Asia/Shanghai（UTC+8）。
+
+## 五日行程
+
+| 日期 | 上午、下午与晚间安排 | 住宿 |
+|---|---|---|
+| D1 2026-10-19（周一） | 12:00 成都当地集合、午餐；14:00 酒店入住；15:30 春熙路/太古里慢逛（约2小时）；18:00 晚餐后休息。下雨改逛商场，抵达日保留半天。 | 鼓楼智选假日酒店候选，未预订 |
+| D2 2026-10-20（周二） | 07:00 出发；08:00-11:30 熊猫基地（已核实需实名预约，尚未购票）；12:30 市区午餐；14:00-16:00 文殊院/文殊坊，17:00 返回。雨天优先室内科普展区，不保证熊猫出场。 | 同上 |
+| D3 2026-10-21（周三） | 09:00-11:30 成都博物馆（周三，预约待办）；12:30 青华路午餐；14:00-16:00 杜甫草堂；晚间自由休息。博物馆门票/预约只通过官方渠道，草堂实际开放时间待再次确认。 | 同上 |
+| D4 2026-10-22（周四） | 唯一较紧日：07:30 前往城际站；预留约2小时单程门到门；10:00-14:30 都江堰水利工程，午餐自带便当；15:00-17:30 返蓉，18:30 晚餐。不叠加青城山；车次、余票和景区开放情况未实时核实。若持续降雨或通行不佳，改为市区方案B。 | 同上 |
+| D5 2026-10-23（周五） | 08:15 先退房并寄存行李；09:00-11:00 武侯祠；11:00-12:00 锦里慢逛；12:30 市区午餐，下午自由活动；16:00 回酒店取行李；17:00 提前晚餐，18:00 成都当地行程结束。若另订返程交通，按实际出发时刻至少留足到站/机场缓冲。 | 无，退房 |
+
+## 天气脚本实跑结果
+
+Open-Meteo 查询：2026-10-12 10:05 北京时间。返回日期与10月19–23日逐日完全匹配；对应城市网格预报，不是景区微气候实测。查询距出行较远，后段天气仅看趋势，出行前1–2天重新查询；不要把市区预报直接当作都江堰的精确预报。
+
+| 日期 | 天气 | 最低–最高 | 日降水估计 | 最大降水概率 |
+|---|---|---|---|---|
+| 2026-10-19 | 毛毛雨 | 18.7–21.1°C | 6.0 mm | 14% |
+| 2026-10-20 | 小毛毛雨 | 17.9–21.9°C | 0.9 mm | 25% |
+| 2026-10-21 | 小毛毛雨 | 15.9–19.0°C | 2.1 mm | 24% |
+| 2026-10-22 | 小毛毛雨 | 14.1–20.5°C | 2.1 mm | 20% |
+| 2026-10-23 | 小毛毛雨 | 15.6–21.9°C | 1.2 mm | 23% |
+
+随身雨伞、防滑鞋、薄外套。D1遇雨优先逛商场；D3以室内博物馆为主，草堂遇强降雨可取消并调整票费；D4是否去都江堰，以临近日期的当地预报和景区公告决定。不要因预算已计入而强行出游。
+
+## 每日用餐建议
+
+以下是人均规划金额，不是菜单报价；同一餐厅重复使用以减少未知店名和路线波动，可在预算内换成已核实门店。标签只针对已知“微辣”偏好，不是过敏安全保证。酒店餐厅是否供应晚餐、具体菜名、退房后是否可用餐尚未确认；不方便时用同区域经核实餐厅替代。
+
+| 餐次 | 餐厅/方式 | 建议菜品与限制标签 | 人均估算 |
+|---|---|---|---|
+| D1 早餐 | 集合前自理 | 按出发地安排，不计入成都当地预算 | 房价内/不计 |
+| D1 午餐 | 龙抄手（春熙路总店） | 清汤抄手、少辣小吃拼盘 [需调整并确认] | 约 CNY 45 |
+| D1 晚餐 | 鼓楼智选假日酒店餐厅 | 少辣简餐建议；菜名与晚餐供应待酒店确认 [需调整并确认] | 约 CNY 75 |
+| D2 早餐 | 酒店早餐厅 | 粥、蛋、水果 [符合已知微辣限制]；以所订双早房型为准 | 房价内/不计 |
+| D2 午餐 | 龙抄手（春熙路总店） | 清汤抄手/蒸点，红油另放 [需调整并确认] | 约 CNY 45 |
+| D2 晚餐 | 酒店餐厅 | 清淡热菜、米饭；当日菜单需确认 [需调整并确认] | 约 CNY 75 |
+| D3 早餐 | 酒店早餐厅 | 面点、粥、水果 [符合已知微辣限制] | 房价内/不计 |
+| D3 午餐 | 陈麻婆豆腐（青华路） | 麻婆豆腐请求微辣、荷叶粉蒸肉、米饭；可否减辣由门店确认 [需调整并确认] | 约 CNY 50 |
+| D3 晚餐 | 龙抄手（春熙路总店） | 小吃组合/汤圆，辣油另放 [需调整并确认] | 约 CNY 70 |
+| D4 早餐 | 酒店早餐厅 | 早餐提前准备，打包是否提供需酒店确认 [需调整并确认] | 房价内/不计 |
+| D4 午餐 | 自备便当（前一晚采购） | 熟食/面包、水果、水 [注意保存及食用时间] | 约 CNY 50 |
+| D4 晚餐 | 酒店餐厅 | 清汤面/熟食简餐作为点餐建议，按实际菜单替换 [需调整并确认] | 约 CNY 60 |
+| D5 早餐 | 酒店早餐厅 | 粥、面点、水果 [符合已知微辣限制] | 房价内/不计 |
+| D5 午餐 | 龙抄手（春熙路总店） | 清汤抄手、蒸点 [需调整并确认] | 约 CNY 45 |
+| D5 晚餐 | 酒店餐厅（退房后用餐需确认） | 提前晚餐建议，按实际菜单选少辣简餐 [需调整并确认] | 约 CNY 55 |
+
+15个餐次中的房价内早餐不重复计费；D1集合前早餐不计入当地预算。上表另加两人人均共30元的饮水零食，共形成两人 CNY 1200 餐饮预算。火锅若替换一餐，可选鸳鸯/菌汤锅，额外费用从预算余额中支付。麻婆豆腐和红油小吃默认有辣，明确请求减辣，不能把“清淡”视为自动满足。
+
+## 两人预算
+
+当地与用户货币均为CNY，无需换汇。修复后的汇率脚本对 CNY→CNY 返回等额和无汇率日期，没有伪造汇率。单独的 CNY→USD 调用只是工具连通性测试，不用于此国内预算。
+
+| 项目 | 两人费用 |
+|---|---|
+| 住宿4晚（双人房，含双早预算） | CNY 1400 |
+| 餐饮5天（含饮水零食） | CNY 1200 |
+| 门票预算 | CNY 470 |
+| 市内及都江堰交通预留 | CNY 620 |
+| 观光车、雨具等杂费预留 | CNY 200 |
+| 基础费用小计 | CNY 3890 |
+| 应急10%（按小计计算） | CNY 389 |
+| 合计 | CNY 4279 |
+| 人均 | CNY 2139.50 |
+| 距总预算余额 | CNY 721 |
+
+门票预算构成：熊猫基地55×2=110；武侯祠50×2=100；杜甫草堂预留50×2=100；都江堰预留80×2=160；成都博物馆常设展按免费预约计算，不含另收费展览。熊猫基地与武侯祠基础票价有官方页面支持，草堂和都江堰金额为待核实的预算预留。观光车另从杂费中支付。
+交通620为市内/到站接驳约400和都江堰往返城际及接驳约220的预留；无实际车次报价。不含往返成都机票/铁路票，也不包括大额购物和保险。超过预留时重新核算总额。
+
+## 住宿候选
+
+| 候选 | 位置与特点 | 预算与核实状态 |
+|---|---|---|
+| 成都鼓楼智选假日酒店 | 大墙西街72号，市中心；本方案以此作住宿候选 | 按CNY350/间夜估算，4晚1400；官方页面说明每间房双早，仍须核对实际房型与价格，未预订 |
+| 成都天府广场智选假日酒店 | 金盾路52号；天府广场与人民公园一带 | 备选，按同档预算筛选；官方页面有含早餐说明，实际房价和库存待查 |
+
+## 交通选择与雨天方案
+
+| 比较 | 地铁+步行+少量打车 | 全程租车 | 建议 |
+|---|---|---|---|
+| 市区游览 | 少找停车位，适合市中心路线 | 停车与拥堵费用未报价 | 地铁为主 |
+| 都江堰一天 | 城际车加当地接驳，车次待定 | 灵活，但需核实租金与停车 | 先比较实际车次，雨天可直接取消 |
+| 五天成本 | 已预留CNY620/两人 | 未报价，不能宣称更省钱 | 按本方案先不租车 |
+
+方案B：保留D1、D2、D3和D5，把D4改为市区休息、人民公园短游或室内商场；不新增另一座未经核实开馆日的博物馆。删除都江堰票费160，把交通预算降为450。基础费用3560，应急356，合计CNY3916，人均CNY1958。比A省363，适合持续降雨或不想早起的人。
+
+| 方案 | 总费用（两人，估算） | 体力 | 内容 | 适用情况 |
+|---|---|---|---|---|
+| A 城市+都江堰 | CNY4279 | 一天较紧 | 熊猫、城市文化、水利工程 | 天气和景区通行条件合适 |
+| B 市区慢游 | CNY3916 | 更轻松 | 熊猫、文化、休息 | 下雨或想降低成本 |
+
+先保留A作完整对比；出行前天气不适合都江堰时选B。所有预约与购票尚待本人办理，测试没有自动购票或付款。
+
+## 出发前清单
+
+- 身份证等有效证件；核对住宿入住人和实名预约资料，避免在公开行程文件写证件号码。
+- 熊猫基地实名预约，成都博物馆使用官网/官方公众号；周一不安排成都博物馆。
+- 确认酒店价格、双早、取消政策和晚餐供应；餐厅少辣做法现场确认。
+- 核实杜甫草堂、都江堰开放时间与票价，以及城际车次；实际返程出发点已订后再调整D5。
+- 下载地图、准备支付方式和雨具；需要保险时另行核价，不把未购买保险写成已包含。
+
+## 来源与数据边界
+
+信息核查日期：2026-10-12。以下页面支持景点规则、实体信息和酒店设施；估算价格不引用成实时成交价。
+
+1. [熊猫基地官网](https://www.panda.org.cn/cn/)：实名预约、开放时段；[官方日文版票价](https://m.panda.org.cn/jp/)：成人55元。
+2. [成都博物馆参观指南](https://www.cdmuseum.com/zhinan/)：周一闭馆（法定节假日除外）、入馆时段。来源冲突时以场馆最新公告为准。
+3. [武侯祠官方票务说明](https://whpwm.cdwuhouci.cn/index)：基础全价票50元。
+4. [UNESCO都江堰介绍](https://whc.unesco.org/en/list/1001)：遗产内容；此页不支持门票或交通报价。
+5. [鼓楼智选假日酒店官方页面](https://www.ihg.com/holidayinnexpress/hotels/tw/zh/chengdu/ctugl/hoteldetail)、[天府广场酒店官方页面](https://www.ihg.com/holidayinnexpress/hotels/us/en/chengdu/ctuts/hoteldetail)：地址、早餐与设施；不是所选日期的房价。
+6. [龙抄手高德地点页面](https://www.amap.com/place/B001C7UMYH)：店名与地点；[陈麻婆豆腐米其林页面](https://guide.michelin.com/sg/zh_CN/chengdu-municipality/chengdu/restaurant/chen-mapo-tofu-qinghua-road)：地址与招牌菜。未核实实时营业和当日菜单。
+7. [Open-Meteo官方接口说明](https://open-meteo.com/en/docs?past_days=1)：预报窗口、日期及当前天气字段；原始响应另存运行记录。
+
+## 这次运行如何完成
+
+AtlasAgent是技能文档与工具组合，没有一个自动生成整份旅行攻略的模型程序。本次实际执行了修复后的天气、当前天气、日历、汇率和doctor脚本，再按更新后的技能流程编排这份行程；PDF由仓库的md2pdf实际导出。脚本原始响应、预算/约束校验、PDF内容核对与回归测试日志与本文件一并保存。人工编排内容没有冒充脚本直接生成的文本。