io.github.horace-maxwell/horosa-skill
18 changes recorded. MCP Harbor re-reads this listing from the official registry every six hours and asks the live server what it exposes, and keeps what changed between one look and the next.
https://raw.githubusercontent.com/horace-maxwell/horosa-skill/HEAD/AGENTS.md
− Horosa Skill 把星阙（Horosa）的 **110 个**术数/占星技法打包成 local-first 的 **MCP server + CLI**：− planetaryarc 等——Python `_call_remote` + Python snapshot builder。− `math.ceil`；动周期数学必对星阙 `decennials.test.js` 金标（`tests/test_decennials.py`）。− （`/chart` 需 `predictive` 真值才出 `predictives.yearsystem129`）/ persiandirected 等——读已算好的 chart− 根因是 moment `add(x,'days')` 把小数天四舍五入到整天，移植成 `timedelta(days=float)`；现按 `js_round` 取整天。− （27 域/236 条，逐条带出处；幂等 = generated_at 取上游 commit 时间；**正文读上游 HEAD blob、不读工作区**，− 客户端 `/mcp` 确认工具计数不掉。依赖钉 `mcp[cli]>=1.29.0,<2`（锁 1.30.0，`pydantic>=2.11` 随之；SDK v2 是破坏性重写，单独跟踪）；− 不新增依赖 sampling/roots/logging（2026-07-28 规范起废弃，本仓未使用）。elicit 必须在任何副作用之前− （v2 会重放整个工具函数）。− （`test_simplified_server_never_calls_the_converter`）。出口只有三处：MCP（`HorosaFastMCP.call_tool`，全部工具含错误信封）、− 这套机制与上游星阙「界面简繁」（`hantRules.js`）相同，规则 ⊇ 上游：2026-10-23 双方互相对齐后（上游 fe0b5d3e），− 110 技法语料上逐字 0 差异，唯一偏离是本仓另收「占有」→ 佔有（写在 JSON 的 `deviations`）。− 4. **新技法 / 新术语** → 用 110 技法真实输出跑一遍残差（看术数字是否被转成普通义）：术数字的普通义例外进− （对上游 READ-ONLY）。**顶层共享件必须显式补**：上游把子逻辑上提为 vendor 根级单文件时（如− `verify_vendor_runtime_sources.py` 断言该文件 + vendored aiExport `AI_EXPORT_SETTINGS_VERSION` **等于** `MIRRORED_UPSTREAM_AIEXPORT_VERSION`（今 58）。− 分支必须排除 卜卦/horary/起卦/占问 短语，否则「卜卦问婚姻」误路由 `gua_desc`——同类新词照此办理）。− 闸门、技法名写法、参数形状、CLI 退出码、HTTP 鉴权只存在于表面层，发版前另跑 `scripts/surface_audit.py`（全 110 技法 × MCP 全量 /− - **PDF 按字补字形（v0.43.1-dev）。** 主字体（Songti / 雅黑）缺的字逐字走补字链 `_PDF_GLYPH_FALLBACK_CANDIDATES`：扩展 B 古籍字− （Win：SimSun-ExtB / MingLiU-ExtB）→ 符号与拉丁扩展（mac：Arial Unicode + Apple Symbols；Win：Segoe UI Symbol + Arial；Linux：DejaVu）。− 阈值 0x80（埃及历 ḥ ṭ、梵文 ṇ ṃ 在 U+2E80 以下，旧阈值永远不补）。reportlab 只吃 TrueType 轮廓（.otf CFF 会抛 TTFError）。− `_render_pdf` 里的 `Paragraph` 是包过一层的同名函数——新增段落照旧写 `Paragraph(...)` 即自动补字，别绕过它。− 守卫 `tests/test_pdf_glyph_fallback.py`、`tests/test_report_polish.py`。− - **完整排盘报告与 PDF 排版（v0.43.0 → v0.43.1-dev 重做）。** `style:"chart"` 不要 AI 解读、收录全部有内容的导出段；− 缺省 `analysis` 没解读仍回 `analysis_required`；没有盘面的工具（解析 / 注册表 / 知识检索）回 `report.no_chart_content`。现行规矩：− - reportlab 的 flowable **排过一次就不能再排**：每遍 `compose(pages)` 现组 story，目录自绘，两遍间页码稳定才停；分栏用 `Panels`− （每屏按剩余高度现切，保证「先左栏后右栏」的读序——Table 跨页只会竖着断）。− - 引擎没给内容的段（正文是 `_missing_detail_text` 的护栏话）：builder 标 `placeholder` + `human_visible: False`，人读版只在技法依据表− 「本次未产出」一行列名——那句话是写给 AI 的，不给人看。规则库查询（`_RULE_LOOKUP_TOOLS`）同样拒绝出 chart 报告。− - 附录只放人读口径：设置值经 `builder._setting_text`（布尔 → 是 / 否、有码表的 → 文字；宫制 / 黄道 / 岁差 / 性别不列——技法卡是请求口径，− 实际值看正文；没码表的枚举不列），不放引擎内部名 / 导出设置版本 / aiExport 来源串（它们留在 JSON）；基本信息里经纬度写「东经 121°28′」、`gender` 布尔写男 / 女、非字符串的 `name` 不列。− - 盘图在 `reports/figures.py`：**只取**引擎数据（宫头、经度、lonspeed 正负、`aspects.normalAsp`、紫微 houses、奇门 cells、六壬− layout / ke / sanChuan），绝不自己算位置或量相位（铁律 1）。七政 / 印度 / 宿占不套西洋轮；任何一种取不全就整张不画。− 位置键 `branch` / `gua` / `kind` / `layout` 登记在 `localize._DOCUMENT_MACHINE_KEYS`（繁体输出不转，渲染器按简体地支、卦名定格）。− 无宫体系（`_WHEEL_NO_HOUSES`，巴比伦）只画星座环 + 行星、不画相位；卜卦 / 择日的相位取 `data.raw.aspects`。六爻变卦**只在− `changed_code` 与本卦 + 动爻对得上时才画**（结果里没有引擎推出的之卦码；样例载荷的 changed_code 与动爻不符），对不上只画本卦；− 卦图不画六神（`data.lines[].god` 可与「断卦结构」表不一致）；三式合一不画 `data.qimen` 子盘（与合盘概览对不上）。− 通则：**同一结果有两处来源时，图只取能与正文对上的那处，对不上就不画**。轮上度数紧贴星名正下方，标签间隔按两行字高折角度。− - v0.44.1 补齐：太乙十六宫（`pan.palace16` / 三式的 `data.taiyi`，对照正文「十六宫标记」）、七政四余地支方盘（星名跟引擎换位后的− id 走、对照庙旺表的曜 → 地支）、七政择日动盘（对照「择日动盘」每行的宫）、南印方盘（按 `params.varga` 的分盘、宫的 sign 在− `chart.houses`）、量化盘 90° 度盘（因子集同正文、对照折叠值）、合盘双圈（轴线不穿外圈）、择日画 `data.base` 那一刻的盘。+ Horosa Skill 把星阙（Horosa）的 **114 个**术数/占星技法打包成 local-first 的 **MCP server + CLI**：+ **`lunar-javascript` 的年缓存由 `src/shared/lunarYearCache.js` 撑大（v0.47.2-dev）**：库只缓存一个 LunarYear、构造一次重算 31 个节气，而 `buildSmallDirection` 每起一盘逐年排约百年流年表；容量必须大于一次横扫（LRU 小于横扫长度命中率恒为 0，第一版 32 实测没快）。`tools/index.js` 第一行引入；太乙 / 三式择时一周 30 秒 → 4.8 秒，320 条引擎请求修前修后逐字节相同。+ planetaryarc 等——Python `_call_remote` + Python snapshot builder。推运图族四法（neroman / bezzafigure / jayprofection / michon，+ v0.47.0）后端 `/astroextra/<接口>` 算、vendored 上游 `AstroDirectedFigures.snapshotText` 排版（progextra）。+ - **上游无头路径是「请求型」**（builder 自己 fetch，如 `buildDirectedFigureSnapshotText`）时，请求体只能由 Python 手算——这是一份+ 手抄件。让 JS 工具用 vendored 上游函数把同一份设置重算成 `request_fields` 回传，runner 与自己发出的逐键比对，不一致即报错+ （`tool.directed_request_mismatch`；v0.47.0）——值错了后端照样算出一张「合理」的盘，没有这一步漂移零信号。+ `math.ceil`；动周期数学必对星阙 `decennials.test.js` 金标（`tests/test_decennials.py`）。v0.46.0 起出生时刻按上游+ `zonedBirthMomentOfChart(…, '+08:00')`（此前误作 +00:00）、时刻走 civil 轴，公元前 / 1582 前儒略历与上游逐值相同。+ - **命盘日期一律经 `horosa_skill/civil_calendar.py`（v0.46.0）**：上游 v3.12.0 把日期收口到 civilCalendar / civilMoment /+ dateStrSafe（1582-10-15 前儒略历、无 0 年、公元前前导负号、1–6 位年）；Python `datetime` 只认外推格里历 1–9999 年。禁止对命盘+ 日期新写 `strptime` / `fromisoformat` / `datetime + timedelta` / `[:4]` / `replace("-", "/")` / `len()==10`——公元前会被 try 吞成+ 「无数据」，1500 年静默差一天；派生请求的 `ad` 随时刻本身（chartAtMoment）。值对拍用上游源在 node 里跑（`tests/test_sync313_historical.py`）。+ **调用方给的目标日 / 区间日也算（v0.47.0）**：`PredictiveRunners._astroextra_date` 曾是四位年正则 + `datetime()`，公元前本命盘一给+ targetDate / 星历区间就报「不是合法日期」，区间先后又是字符串比较（`'-0400…' < '-0500…'`）——校验用 `_civil_ymd_exists`、输出+ `_format_signed_date`、比较用 `_civil_jdn`（`tests/test_sync3131_civil_dates.py`）。+ / persiandirected 等——读已算好的 chart（yearsystem129 / agepoint / distributions v0.46.0 起改为 vendored 上游 JS 出文本：上游删了+ 后端 yearsystem129.py，`/chart` 不再回 `predictives.yearsystem129`）+ 根因是 moment `add(x,'days')` 把小数天四舍五入到整天，移植成 `timedelta(days=float)`；现按 `js_round` 取整天；v0.46.0 起+ 日期走 `civilDateAfterDays`（公元前 / 1500 年与上游逐值相同）。+ （27 域/243 条，逐条带出处；幂等 = generated_at 取上游 commit 时间；**正文读上游 HEAD blob、不读工作区**，+ - **自备知识库的检索（v0.45.0，`knowledge/index.py`，照搬 qmd / basic-memory / FastGPT / RAGFlow，调研见 LESSONS v0.45.0-dev）。**+ - 分块：先按 Markdown 标题分节、不跨标题；节超 1000 字在 空行 > 。！？； > 换行 处挑断点切成约 600 字，同节相邻块重叠一句；+ 只有标题的上级节并进**下级**节（不并平级）。每块记正文字符区间 + 行号；对外的行号一律是**原文件**行号（`line_offset`）。+ - 中文检索：归一（NFKC → 繁→简 → casefold）后汉字切相邻双字，查询每个词 = 双字短语、词间 OR；单字走子串回退。不用 jieba+ （现代汉语词典切错古籍），不用 trigram（两字词查不到）。FTS5 只找候选，分数自己算 BM25（Lucene IDF）——FTS5 的 bm25()+ 对过半块都有的词给 0 分。+ - 索引在 `<data_dir>/knowledge-state/index.sqlite`，contentless（不存正文、只存区间）+ secure_delete + 回滚日志；按条目 sha256 增量同步，+ 文件没了整条删；刚改过 2 秒内的文件不进扫描缓存（racy-clean）。索引坏 / FTS5 不可用 → 记 `problems`、退回逐条子串，不报错。+ - 计算时：装得下整条就整条；装不下**只带与本盘导出正文相关的块**（零分块不凑数），每段【标题 · 第几行】；`?检索词` 跨库带最相关几段。+ - 工具：`horosa_knowledge_search`（门面，常驻）检索 → `horosa_knowledge_read(domain="user", key, from_line, max_lines)` 按行翻页；+ 内置与自备结果用 RRF（k=60）合并，不比分数。CLI `knowledge search`（兼检索测试）/ `knowledge index [--rebuild]`。+ - 守卫：`tests/test_user_knowledge_index.py`（每条都有负向对照；其中四条第一版「因为错误的原因通过」，见 LESSONS）。+ - **可选向量（v0.45.1，`knowledge/vectors.py`）**：`[vectors]` 额外依赖 + `knowledge index --vectors` 下载（钉提交号 + sha256）才开；+ 任何一环缺了就是纯 BM25、不报错。RRF 同分按 BM25 名次定序。测试用概念替身，dev 组带 numpy（别让守卫在 CI 里 skip）。+ - 内置知识检索（`knowledge/store.py`）与自备同一套归一 + BM25；正文分封顶 60，精确键（100）永远在前。+ **tools/list 预算（v0.47.0）**：全量面硬顶 256 KB 已近满（v0.47.0 推运图族四法之后 260 223 B，余量 ~1.9 KB）；一个 BirthInput 技法工具的广告层+ ≈ 1.9–2.7 KB。新工具只广告域核心 + 推运目标字段 + 闸门三键，口径旋钮一律 `ADVERTISE_HIDDEN`（guidance `options_keys` 必须有说明，+ `test_guidance_documents_house_systems_hidden_knobs_and_gate_vocab` 守）；对该技法**不改结果**的域核心键（如只按回归黄道算的四法的+ `zodiacal` / `siderealAyanamsa`）也可列进 `ADVERTISE_HIDDEN`——广告层会剔除，校验层照收。硬顶与 2% 容差永不为放新工具而抬；新增工具后
Showing the first 40 of each.
https://raw.githubusercontent.com/horace-maxwell/horosa-skill/HEAD/AGENTS.md
− 5. **发布不信绿灯**：release-completeness guard 绿 ≠ 完整（pin-forward 模式下它必绿）；− `sync_windows_release.py --check` 的 `[GAP]` 才是权威（§7）。− 版本号用 `horosa-skill/scripts/bump_version.py <new>`（16 个站点一处清单）。− Devin 那样的改名旧路径留作候选）。（这里曾写「`verify_docs_sync.check_client_matrix` 锁」——那个函数早已不存在，− 规则写着有人锁、实际没人锁；v0.41.0 起由 `tests/test_client_lockstep.py` 真锁，见下条。）− - **版本 bump 只有一个入口**（代码站点 pyproject / `__init__.py` 只改版本赋值行，历史注释不许动——v0.40.1 误改过；bump 后逐行看 diff）：`horosa-skill/scripts/bump_version.py <new>`（`SITES` 16 个站点：`pyproject.toml`、`__init__.py`、`uv.lock`、− `server.json`、`CITATION.cff`、`.claude-plugin/plugin.json`、`README.md`/`README_EN.md`/SKILL/`INSTALL_RESTRICTED_NETWORK` 的钉版本命令与− 「当前版本」行、两份 manifest 示例 JSON）；`--check` 断言全部站点同版本，CI 由 `verify_docs_sync.check_versions` 锁步。− 钉回 v0.16.1）——guard 绿、install 不炸、sha 也对，Windows 用户静默拿到落后 N 版的 runtime。+ 5. **发布不信绿灯**：release-completeness guard 绿 ≠ 完整——它只巡检**已公开**的 latest，草稿期看不到（v0.38.0 起它会拒清单 URL+ 钉到别的 tag 的 pin-forward）；发版期 `sync_windows_release.py --check [--tag vX --draft]` 的 `[GAP]` 才是权威（§7）。+ 版本号用 `horosa-skill/scripts/bump_version.py <new>`（站点一处清单 `SITES`）。+ ### 4.1 算权：ken 后端、本地路由与端点登记+ ### 4.2 算源普查（每个技法由谁算）与算源标注+ ### 4.3 知识包与上游同步守卫+ 🔴 **判空看值、判型看边界、主计算失败必须是失败（v0.41.2 移植的缺陷）。** 恒有固定键的 dict 判空要看值（五行计数全 0 也「非空」）；+ 类型检查放在合并 / 转换**之前**的原始数据上（对 `{**defaults, **raw}` 判型恒真，真正会炸的是合并本身）；只有可选增强许 `_degrade`，+ 主引擎调用不许吞成 ok + 空结果；安装期写进清单的快照（`services.*_url`）不得压过实时 settings——探针、启动器、技法客户端只认同一组地址+ （`endpoint_identities` 探的就是当前端口）。+ - **自备知识库的数据管理（v0.43.1-dev 重做，`knowledge/user.py`）。** 文件是唯一真相；状态（锁 / 回收站）在 `<data_dir>/knowledge-state/`，+ **不进用户的文件夹**。规矩：+ - 技法入参 `knowledge` 在 `run_tool` **校验前**取走，不进 `input_normalized` / 引擎请求；`build_context` 出错只加告警、不坏盘。+ - **存档只存引用**（`redact_for_storage`：id / 标题 / 字数 / sha256），返回给 AI 的那份才有正文；报告附录只列引用、不印正文。+ - 编码 utf-8-sig → UTF-16（BOM）→ GB18030；读不了 / 超 2 MB / 空 / 链出文件夹 / id 撞车 / 元数据没收尾 / 技法名不认识，一律进+ `problems`，绝不静默消失；点名告警分「没找到 / 读不了 / 有歧义 / 超额未带入 / auto 没选中」。+ - 选取、精读、删除共用 `resolve()`：精确 id → 带扩展名文件名 → **唯一**标题，歧义报 `knowledge.user_ambiguous` 并列候选；键 NFC + casefold。+ - 写：条目名不合法就拒（`validate_id`，不改名）；扩展名追加（不用 `with_suffix`）；覆盖写回原文件、沿用没给的元数据；+ 覆盖与删除先进回收站（`knowledge trash` / `restore`）；文件锁 + mkstemp + fsync + 原子替换。+ - `runtime uninstall --purge-data` **默认保留知识库与回收站**，`--purge-knowledge` 才连它们删。+ - 守卫：`tests/test_user_knowledge_store.py`、`tests/test_user_knowledge_and_chart_report.py`（负向对照见 LESSONS v0.43.1-dev / 2026-10-24）。+ ### 4.4 MCP 面、决策层与错误信封+ ### 4.5 输出文字：简体（缺省）/ 繁体（v0.42.0，`src/horosa_skill/textscript/`）——**以后加东西必须同步**+ **模型**：存档、引擎、门禁、内部逻辑永远是简体原文；只在结果**离开进程**时按 `HOROSA_OUTPUT_SCRIPT`+ （`zh-Hans` 缺省 / `zh-Hant` 台湾字形 / `zh-Hant-HK` 香港字形；设置界面是一个布尔勾选：MCPB `traditional_chinese`、+ 插件 `traditionalChinese`；`setup` / `client config --output-script`）转换。缺省简体 = **逐字节不变**、转换器根本不跑+ （`test_simplified_server_never_calls_the_converter`）。出口只有三处：MCP（`HorosaFastMCP.call_tool`，全部工具含错误信封）、+ CLI（`_localized`）、报告落盘（`localize_document` + `render_report(script=)` 选繁体字形字体）。+ **只转给人读的字段**（`textscript/localize.py` 白名单 `TEXT_KEYS`）；回显入参、引擎原始 `data`、设置值、选项、错误码、+ 给 AI 的协议（guidance / registry / 报告模板 / 合参契约）一字不动——AI 会把这些原样送回下一次调用。+ AI 送回来的**标识**（段名、知识库键）经 `canonical_name` 按词表反查对回原名：上游段名本就有「命宮」「佈局」「大运·歲運」，+ **不能一律繁转简**；检索词才用繁转简（`fold_to_simplified`），且只在原值零命中时再试一次。+ **转换器**：OpenCC 1.4.2 文本字典（vendored，`data/opencc/SOURCE.json` 记哈希）+ 纯 Python 最长匹配；不装 `opencc` 包+ （无 Windows ARM64 轮子）。去掉术数规则时与官方 opencc 逐字相同（600 句参考样本锁住）。**OpenCC 在术数字上系统性转错**——+ 干→幹、丑→醜、冲→衝、克→克（应剋）、斗→鬥、凶→兇、占→佔、咸→鹹、历→歷——所以最后一步按**原文逐位定字**+ （`data/horosa_char_rules.json`：每字一个缺省 + 普通义白名单，冲→沖、克→剋、历→曆、钟→鐘，干 / 丑 / 斗 / 占 / 凶 / 咸 / 表保持，+ 引书「云」后跟冒号保持）。**不能靠词组表**：最长匹配先吃掉前一个字（「真实干支」切出「实干」→ 真實幹支），补不完。+ 这套机制与上游星阙「界面简繁」（`hantRules.js`）相同，规则 ⊇ 上游：2026-10-23 双方互相对齐后（上游 fe0b5d3e），+ 110 技法语料上逐字 0 差异，唯一偏离是本仓另收「占有」→ 佔有（写在 JSON 的 `deviations`）。+ `test_character_rules_cover_upstream_except_documented_deviations` 在有上游 checkout 时核对；上游再改规则 → 这条红 → 合并或写偏离。
Showing the first 40 of each.
https://raw.githubusercontent.com/horace-maxwell/horosa-skill/HEAD/AGENTS.md
− `/taiyi/pan` · `/jinkou/pan`）计算，与星阙桌面端逐值同源。`service.py::_run_{qimen,taiyi,jinkou}_tool`− 为假 → **静默回退本地旧引擎 = 错结果无报错**。守卫：`service.py::_require_ken_pan` 在每次 ken− 守卫 = `service.py::_require_electionscan_ok`。凡「200 也回失败信封」的端点，一律照此办理。− `service.py::_PYTHON_CHART_ENDPOINTS`。** chart 服务族 = `/chart` · `/predict/*` · `/astroextra/*` ·− **MCP 服务器面法则**（`surfaces/mcp_server.py`）：全部工具带 **tool annotations**（口径：openWorldHint− 1. `schemas/tools.py` 输入模型（神数用 split 年月日时分 + `options` passthrough 的 `ShenShuInput` 模式；− 2. `service.py` `_run_*_tool` runner；远端端点进 `_PYTHON_CHART_ENDPOINTS`；ken-backed 加 `_require_ken_pan`。− 16a. **新客户端 = 三件套（v0.38.1 B2）**：① `CLIENT_PLACEHOLDER_WHITELIST` 里登记它**真的会展开**的 `${…}` 变量（按它的官方文档，− | 看不懂 doctor 的码 / agent 把 issue 码原样甩给用户 | 码是给脚本的 | `doctor --explain`（stderr 6–10 行人话，stdout 仍纯 JSON）；报告 `advice[]` 每码一句 `user_summary` + `next_action`（码表 `cli._DOCTOR_ADVICE` 与 `manager.DOCTOR_ISSUE_CODES` 锁步） |− warning 码 = `cli._DOCTOR_WARNING_CODES`；`cli._DOCTOR_ADVICE` 逐码给 `user_summary` + `next_action`，报告 `advice[]` 与 `--explain`− `taiyi` / `sanshiunited` / `jieqi_year` / `nongli_time`（schema 字段 + `service.py` 白名单转发），以及+ `/taiyi/pan` · `/jinkou/pan`）计算，与星阙桌面端逐值同源。`service/runners/sanshi.py::_run_{qimen,taiyi,jinkou}_tool`+ 为假 → **静默回退本地旧引擎 = 错结果无报错**。守卫：`service/remote.py::_require_ken_pan` 在每次 ken+ 守卫 = `service/remote.py::_require_electionscan_ok`。凡「200 也回失败信封」的端点，一律照此办理。+ `service/endpoints.py::_PYTHON_CHART_ENDPOINTS`。** chart 服务族 = `/chart` · `/predict/*` · `/astroextra/*` ·+ **MCP 服务器面法则**（`surfaces/mcp_server.py` 注册工具；注解 / 工具集在 `mcp_surface.py`、入参归一在 `mcp_requests.py`、错误信封在 `mcp_errors.py`、并发与兜底在 `mcp_runner.py`、elicitation 在 `mcp_elicitation.py`）：全部工具带 **tool annotations**（口径：openWorldHint+ 1. `schemas/tools/<族>.py` 输入模型（v0.41.1 起按技法族分模块，`__init__` 显式 re-export；神数用 split 年月日时分 + `options` passthrough 的 `ShenShuInput` 模式；+ 2. `service/runners/<族>.py` 里加 `_run_*_tool` runner（mixin 方法；跨族只经 `self.` 调）；远端端点进 `_PYTHON_CHART_ENDPOINTS`；ken-backed 加 `_require_ken_pan`。+ 共享 runner 表 `SHARED_RUNNER` 写错名字 = 扫不到证据 = 被兜底成 `local_data`「不起盘」（v0.41.1 前 keypoints / lunationphase /+ triplicityrulers 就这样挂了两个月）；生成器现在对非空值断言存在，一行转发的 runner（如 balbillus）也要映射到真正干活的那个。+ 16a. **新客户端 = 三件套（v0.38.1 B2；v0.41.1 起这些表与函数住在 `client_config/`——`locations` / `merge` / `audit` / `payload` / `openclaw`，命令仍在 cli.py）**：① `CLIENT_PLACEHOLDER_WHITELIST` 里登记它**真的会展开**的 `${…}` 变量（按它的官方文档，+ | 看不懂 doctor 的码 / agent 把 issue 码原样甩给用户 | 码是给脚本的 | `doctor --explain`（stderr 6–10 行人话，stdout 仍纯 JSON）；报告 `advice[]` 每码一句 `user_summary` + `next_action`（码表 `doctor._DOCTOR_ADVICE` 与 `manager.DOCTOR_ISSUE_CODES` 锁步） |+ 同一脚本的第二条规则 `silent_handler`（v0.41.1）：处理体只有 pass / continue / 返回或赋值常量、且什么都不调用的宽 `except` 按文件计数入棘轮+ （基线 = 「拿不到就是答案」的探针，每处带注释）。新增一处要么改 `_degrade`，要么在同一 change 里写明理由并 `--update-baseline`。+ - **`TOOL_GUIDANCE` 的条目可能被多个工具共用（v0.41.1）。** chart 族五个、神数几组都指向同一个策略 dict；往条目里加字段一律写时复制+ （`TOOL_GUIDANCE[t] = {**TOOL_GUIDANCE[t], ...}`），别原地写——`test_options_keys_never_leak_onto_tools_that_share_a_policy_dict` 锁。+ `agent_guidance` 自 v0.41.1 是包（`base` → `policies` → `tool_table` → `contracts` → `catalog` → `preflight`），导入路径不变。+ - **`service` 自 v0.41.1 是包，`HorosaSkillService` 由 16 个 mixin 组合（`remote` / `enrich` / `runners/*` / `api/*`），导入路径不变。**+ 分层：`_context` · `_clock` · `_common` · `endpoints` → `options_*` → `text/*` → `export` · `envelope` → mixin 层；runner 之间、`api/*` 与+ runner 之间只经 `self.` 互调（测试在实例上替换 `run_tool` / `_run_qimen_tool`），下层不反向依赖 mixin，mixin 成员不重名+ （`tests/test_service_structure.py` 三条锁 + 门面对外名单冻结）。读「现在」一律 `_clock.now(...)`（冻结时间的夹具 patch 那里）。+ **monkeypatch 打在用到名字的子模块上**（如 `service.runners.predictive.correct_station_directions`），包根门面上的同名 re-export 够不着+ ——`tests/test_monkeypatch_targets.py` 抓「只 re-export 不使用」的 patch 点。按路径读源码的扫描（端点登记、算源生成 / 校验）扫整个包。+ - **重试 / 回退只许改写法，不许改值（v0.41.1）。** `_java_chart_payload_candidates` 曾在 `param error` 后把 `gpsLon` 取 `abs()` 重试——+ 西经变东经、盘照样起得出来。候选只能换格式（日期分隔符、`zone` 写法、省掉可选键），任何承载结果的数值（经纬度、时刻、时区偏移）必须原样；+ `test_service.py` 的经度符号断言是负向对照。+ warning 码 = `surfaces/doctor.py::_DOCTOR_WARNING_CODES`；`_DOCTOR_ADVICE`（同模块）逐码给 `user_summary` + `next_action`，报告 `advice[]` 与 `--explain`+ - **测试会话永不连桌面版：`tests/conftest.py` 拒连 127.0.0.1:8899/9999、两个后端默认 :9（v0.41.1 重构第 0 批）。** 直接 `uv run pytest` 曾经+ 不钉后端：34 处 `Settings(...)` 用默认端口，没设 `*_SERVER_ROOT` 的代码回落到桌面版——维护机上真发请求（`test_uninstall_dry_run_then_execute`+ 一条就探 20 s），CI 上那两个端口没人所以永远看不见。conftest 把两个根 setdefault 成 :9（与 `run_ci_gates.py` 同形，显式的 8877/9977 不受影响），+ 并在进程内把连这两个端口一律当「没人在听」（`tests/test_desktop_port_guard.py`）。自写的调 service 脚本同理：开头断言两个根已设且不是 8899/9999。+ - **本机门禁镜像也跑多行步骤：`run_ci_gates.ci_test_steps` 收「每一行都是 `uv run …`」的 `run: |` 块（v0.41.1）。** 旧解析器跳过所有多行块，+ 两行的 `verify_runtime_scripts.py`（+ `--self-test`）从没在本机跑过，文档却写「每个 verify_* 都跑」；测试只核单行步骤，所以同样看不见。+ 现在 `tests/test_guard_wiring.py` 要求 ci.yml test 作业里点名的**每一个** `verify_*.py` 都进镜像（镜像 25 步）。+ - **monkeypatch 目标必须被它所在的模块用到（`tests/test_monkeypatch_targets.py` 的 `useless_patch_reason`）。** 函数挪走、旧模块只留 re-export 时，+ `monkeypatch.setattr("horosa_skill.A.f", …)` 照样成功却不起作用，测试「因为错误的原因通过」。拆大模块时：被 patch 的名字跟着代码走，+ 或让调用方经模块查名（`module.f()`），别靠 re-export 兜。+ `taiyi` / `sanshiunited` / `jieqi_year` / `nongli_time`（schema 字段 + service 层白名单转发），以及
We can't find the internet
Attempting to reconnect
Something went wrong!
Attempting to reconnect