dsh-tap 0.20.0

package/docs/rules/trae-surface.md

@@ -0,0 +1,242 @@
+# TRAE API 面 / OAuth / 插件 侦察规则文档
+
+> 日期：2026-08-19
+> 方法：dsh-tap 同款逆向方法论 —— 现象 → 假设 → 探测 → 规则 → 预测验证
+> 目标：把 TRAE（字节火山系）API 面、OAuth、插件体系摸成白箱，供未来做 provider/自动化接入
+> 主线来源：TRAE 官方日志 + 本地配置 + 实际 HTTP 探测
+
+---
+
+## 0. 一句话结论
+
+TRAE（TRAE SOLO CN / trae.cn）是字节火山系的 Electron IDE，与 CodeBuddy（腾讯 copilot.tencent.com）不是同一套后端：
+
+- 认证：字节账号体系（手机号登录，内部用 Supabase OAuth 服务）
+- API 面：api.trae.cn + api.trae.com.cn + trae-api-cn.mchost.guru 三个域名，专用协议（非 OpenAI 兼容）
+- 插件：trae-remote-official registry 的 16 个官方插件，全部本地 ~/.trae-cn/plugins/
+- MCP：支持本地集成模式（solo_design_lite / dev_agent / browser_use），无远程 HTTP MCP
+- Skills：本地 skills + builtin skills + 远端 skill market
+
+CodeBuddy 那套规则（UA/缓存/路由/额度）对 TRAE 不直接适用，但方法论完全可迁移——本文档就是 TRAE 版的第一份侦察基线。
+
+---
+
+## 1. 主机事实（侦察基线）
+
+### 1.1 安装与数据目录
+
+| 项 | 路径 | 说明 |
+|---|---|---|
+| 可执行文件 | AppData\Local\Programs\TRAE SOLO CN\TRAE SOLO CN.exe | Electron，214MB |
+| 资源 | ...\resources\app | 未打包 asar（只有 node_modules.asar），源码可读 |
+| 数据目录 | AppData\Roaming\TRAE SOLO CN\ | 配置、日志、会话存储 |
+| 用户数据 | %USERPROFILE%\.trae-cn\ | 插件、skills、mcps、extensions、plugin-config 都在这 |
+| 日志 | AppData\Roaming\TRAE SOLO CN\logs\<timestamp>\main.log | 主日志，含全部 API 调用 |
+| 构建 | version 2.3.71801 / app 0.1.51 / vscode 1.107.1 | 2026-08-14 构建 |
+
+### 1.2 本地服务端口（运行时）
+
+| 端口 | 用途 |
+|---|---|
+| 17788 | Supabase OAuth 本地服务（回调 /callback） |
+| 51000 | ckg 本地嵌入服务（local_embedding） |
+| 8644 / 9097 / 9900 | 其他本地网络服务 |
+
+### 1.3 关键事实
+
+- TRAE 使用 ttnet（火山网络库）做 HTTP，带 ttnet fetch 日志前缀
+- 用户已登录（手机号 <redacted:phone>，用户 ID <redacted:userId>，LastLoginType=sms，注册 2025-08-09）
+- token 有效期：expiredAt=2026-08-29、refreshExpiredAt=2027-02-11、tokenReleaseAt=2026-08-15，JWT refresh 被禁用
+
+---
+
+## 2. API 面（已实测）
+
+### 2.1 域名三件套
+
+| 域名 | 归属 | 典型端点 |
+|---|---|---|
+| api.trae.cn | 主 API | pay、ug、GetThirdPartyToken、cloudide GetUserInfo |
+| api.trae.com.cn | 扩展/icube | extensions skill/list、icube user/native/config/notifications |
+| trae-api-cn.mchost.guru | 远端技能 market | /api/remote/v1/skills |
+
+### 2.2 已抓到的完整端点清单（启动时自动调用）
+
+| 端点 | 需要认证? | 响应 | 说明 |
+|---|---|---|---|
+| api.trae.cn/ | 否 | 404 | 根路径无内容 |
+| api.trae.cn/trae/api/v2/ug/checkin_credits/status | 是 | 200 JSON，未认证时 code:1001 | 签到积分状态 |
+| api.trae.cn/trae/api/v2/pay/ide_user_pay_status | 是 | 200 JSON（code 1001 变体） | 套餐/付费状态 |
+| api.trae.cn/trae/api/v2/pay/ide_user_ent_usage | 是 | 200 | 企业用量 |
+| api.trae.cn/trae/api/v3/GetThirdPartyToken | 是 | 404 未带参数；正常调用 3 次（feishu/lark） | 三方 token 获取 |
+| api.trae.cn/cloudide/api/v3/trae/GetUserInfo | 是（x-cloudide-token） | ResponseMetadata+Result | 用户信息 |
+| api.trae.com.cn/extensions/api/-/skill/list | 否 | 200 JSON | 技能市场列表（公开） |
+| trae-api-cn.mchost.guru/api/remote/v1/skills | 是 | 401 未认证 | 远端技能 |
+| api.trae.com.cn/icube/api/v1/user | 未知 | 404 | icube 用户 |
+| api.trae.com.cn/icube/api/v1/native/config/query | 混合 | 带 mid/did/uid 参数 | 动态配置 |
+| api.trae.com.cn/icube/api/v1/notifications/count | 混合 | 200 | 通知数 |
+| api.trae.com.cn/icube/api/v1/package/check_update | 否 | — | 更新检查 |
+
+> 错误码规律（已实测）：未认证错误统一为 code: 1001 + 英文 apologize 文案，与 CodeBuddy 的 12403/11101/11102/14407 完全不同。
+
+### 2.3 认证头
+
+- x-cloudide-token: <token> 用于 cloudide API（日志确认）
+- 其他端点带 x-cloudide-token / 可能还有 ttnet 特有头
+- GetUserInfo 请求头：Content-Type: application/json + x-cloudide-token
+
+---
+
+## 3. OAuth（Supabase 服务，已实测触发）
+
+### 3.1 架构
+
+用户点击登录/扫码
+  -> TRAE 启动本地 SupabaseOAuthLocalServer (127.0.0.1:17788)
+  -> 浏览器/回调端点 http://127.0.0.1:17788/callback?code=XXX&state=YYY
+  -> 服务解析 code/state -> 换 token -> 写文件
+
+### 3.2 已实测行为
+
+| 探测 | 结果 | 结论 |
+|---|---|---|
+| GET /callback（无参数） | 400 | 端点存在，缺参数 |
+| GET /callback?code=test123&state=xyz | 500 + Failed to write supabase token to file | 完整链路被触发：接受参数->尝试换 token->写盘失败（假 code） |
+| GET /oauth /auth /health | 404 | 只有 /callback 一个公开端点 |
+| token 保存路径 | AppData\Roaming\TRAE SOLO CN\User\supabase-token.json | 日志明确，当前文件不存在（token 存在别处/unset） |
+
+### 3.3 规则（已确立）
+
+1. 本地 OAuth 服务端口固定 17788（可被占用则换端口，日志会打 Found available port）
+2. /callback 是唯一公开暴露端点，接受 code + state 参数
+3. 认证 token 主存储不在 supabase-token.json（文件不存在但应用正常工作）-> 存在 Windows 凭据或内存
+4. JWT refresh 禁用 -> token 到期（8-29）后需重新登录，refreshToken 无自动续期
+5. GetThirdPartyToken 启动时 fetch 3 次（feishu/lark），响应非数组则告警 Result is not an array（不影响主功能）
+
+> 未解（需真登录一次才可测）：token 在 GetUserInfo/其他 API 间的复用、refresh 轮换的真实条件、state 生命周期真实 TTL。
+
+---
+
+## 4. 插件体系（已完整侦察）
+
+### 4.1 插件来源
+
+- 只装官方 registry：trae-remote-official（display: Remote Official Plugins）
+- 安装清单：~/.trae-cn/installed-plugins.json（含 marketplace、page、plugin 详情）
+- 启用配置：~/.trae-cn/plugin-config.json
+
+### 4.2 16 个官方插件（全清单，本地实装）
+
+| 插件 | 版本 | 用户启用 | 说明 |
+|---|---|---|---|
+| browser | 1.0.3 | 是 | 浏览器控制 |
+| build-web-apps | 0.1.2 | 是 | Web 应用构建 |
+| build-web-data-visualization | 0.1.21 | 否 | 数据可视化 |
+| frontend-design | 0.0.0 | 否 | 前端设计 |
+| github | 0.1.2 | 是 | GitHub |
+| ip-strategy | 0.1.2 | 否 | IP 策略 |
+| lark | 1.0.3 | 否 | 飞书 |
+| personal-workbench | 0.1.0 | 否 | 个人工作台 |
+| product-lifecycle-workbench | 0.2.1 | 否 | 产品生命周期 |
+| seedance | 1.0.1 | 是 | 即梦视频 |
+| seedream | 1.0.1 | 是 | 即梦图片 |
+| staff-engineer-mode | 2.1.0 | 否 | 员工工程师模式 |
+| stark | 0.7.2 | 是 | 智能体协调 |
+| story-craft | 0.1.1 | 否 | 故事创作 |
+| web-app-development | 0.1.1 | 是 | Web 应用开发 |
+| whiteboard | 0.2.0 | 是 | 白板 |
+
+### 4.3 插件安装位置
+
+~/.trae-cn/plugins/trae-remote-official/<name>/<version>/
+
+每个插件含 manifest_json（name/version/i18n/interface/capabilities）、connector_json、mcp_servers_json、skills_json。
+
+### 4.4 MCP 系统（已实测）
+
+TRAE 的 MCP 是本地集成模式，三个 profile：
+
+| profile | 来源 | 发现 |
+|---|---|---|
+| solo_design_lite | dsh-tap 项目 | integrated_code_mode（V8 沙箱 Exec） + GitHub server |
+| dev_agent | 规则动乱项目 | mcp_Blender（Blender 3D/混元 3D/Hyper3D 全套工具） |
+| browser_use | 习惯项目 | GitHub server |
+
+- 每个 MCP server 有 SERVER_METADATA.json（只含 server_name）+ tools/*.json（完整工具 schema）
+- 工具 JSON 只有 schema 无实际端点 -> 本地集成 MCP，不带网络 API
+- integrated_code_mode 的 Exec 是核心：V8 沙箱，无 console/fetch/require/process/fs/network，只有 tools/text/exit/ALL_TOOLS
+
+### 4.5 Skills
+
+| 类别 | 位置 | 内容 |
+|---|---|---|
+| 本地 skills | ~/.trae-cn/skills/ | algorithmic-art、defuddle、flux-best-practices、json-canvas、obsidian-*、prompt-images、shadcn、study-habits、write-xiaohongshu、xiaohongshu-note-analyzer、zhihu-publisher |
+| builtin skills | ~/.trae-cn/builtin_skills/ | TRAE-dynamic-ui、TRAE-security-review、_shared |
+| 远端 skill market | api.trae.com.cn/extensions/api/-/skill/list | 未认证 200，公开 |
+
+skill 开关：~/.trae-cn/skill-config.json（disabledSkills 60+ 个，含 lark-* 全家、visualization 全家）
+
+---
+
+## 5. 与 CodeBuddy 规则的关系（方法论迁移）
+
+| CodeBuddy 课题 | TRAE 对应 | 结论 |
+|---|---|---|
+| UA 校验（/v3/config） | 无 UA 门 | 不适用 |
+| 提示缓存（按内容寻址） | 未测（TRAE 有自己的 ttnet 缓存体系） | 待探索 |
+| 路由配置（14407） | 错误码完全不同（1001 vs 14407） | 重做 |
+| 额度信号（pay/usage） | 有 pay/usage 端点（ide_user_pay_status / ent_usage） | 高度相关，下一步重点 |
+| OAuth 握手 | Supabase 本地服务 + /callback，与 CodeBuddy 网页授权不同 | 方法论同，实现重做 |
+| 内容审核 | 未测 | 待探索 |
+
+### 迁移规则（铁律）
+
+1. 先把 CodeBuddy 的 docs/rules/ 视为方法论模板，不是数据源
+2. 对 TRAE 所有"必须长这样"的结论，必须重新验证（每个端点真实探测）
+3. 错误码/头名/域名不通用，逐项重测
+4. OAuth 研究注意：只理解不绕过（沿用红线）
+
+---
+
+## 5.5 agent 面实测事实（function=solo_work_lite，2026-10-05 探针落地）
+
+同一聊天端点 `POST trae-api-cn.mchost.guru/api/agent/v3/llm_utils_chat` 的「agent 用法」由
+`function` 参数切换——**solo_work_lite 面**（证据 docs/probes/trae-agent-v3-*.jsonl，
+探针 scripts/probe-trae-agent-v3.mjs，8 臂 + function 名扫描 ×2；社区参照
+dsh-connect-trae SOLO_ROUTE_DECISION / Trae2api-cn build_llm_chat_body）：
+
+- **能力面（实测证实）**：接受 OpenAI 风格 tools（parameters 必须序列化为字符串，同
+  inline 面 Go string 型约束）+ tool_choice=auto；返回结构化 tool_calls（SSE
+  output 事件的 tool_calls[i] 键为 **function_call**，arguments 增量片段按 index
+  拼接）；**并行调用**（A4 臂单事件双 tool_calls）；**role:tool 回传闭环**——
+  第二轮历史携带 assistant.tool_calls + role:tool 结果后产出最终回答（A3 臂）。
+- **方言陷阱（踩坑 #68）**：历史 assistant.tool_calls 的出站键必须是
+  **function_call**——OpenAI 同构的 function 键被 proto 层拒：
+  2001 `*idecopilot.ToolCall read field 4 'FunctionCall' error: required field
+  Name is not set`。inline_chat 面则用 function 键透传（2026-08-24 校准）——
+  **同端点不同 function 面各有方言**，不能互推。
+- **function 名注册表（扫描实测）**：agent_chat / agent_v3 / solo_agent_chat /
+  agent / assistant_chat 均未注册（2001 "no function config found for appId=…"）；
+  chat 已注册但模型名不被路由（4023 "the model is unknown"——进入模型路由层才报）；
+  solo_agent 被 dsh-connect-trae 标注为 Remote-agent 花名册函数（用它调任何模型
+  回 4011）。
+- **模型路由钉死**：任何 model 名都 200，但 timing_cost.provider_model_name 恒为
+  glm-5.2（A6 臂 kimi-k2.6 / DeepSeek-V4-Flash 实测）——改派由网关 SSE 注释行
+  / message.note 诚实披露，计量记真实模型。
+- **reasoning_effort 被忽略**（A5 臂与 A2 同形态，不报错也不生效）——档位注入
+  仅保留在 remote 面；agent 面照发不虚标（踩坑 #42 纪律）。
+- **宽容面**：错模型名（E1）与坏参数形态（E2，temperature 字符串）均静默容忍
+  返回 200——与 inline 面 3003 硬错相反。
+- **额度**：token_usage 事件携带 prompt/completion/total/reasoning_tokens/
+  cache_read_input_tokens 全字段；消耗 IDE 池（available_endpoint=0，同 raw 面）。
+- 落地：`traeChatTransport:'agent'`（第三档，设置卡可选，逐请求热读取免重启）。
+
+## 6. 未解清单（下一步探测计划）
+
+- [ ] api.trae.cn 各端点的完整认证方案（x-cloudide-token 从哪来、哪些端点共用）
+- [ ] pay/usage 端点的认证响应展开（额度信号的迁移重点）
+- [ ] TRAE 的 ttnet 缓存体系（是否有类似按内容寻址）
+- [ ] Supabase OAuth 的真实 code 交换（需一次真实登录）
+- [ ] token 的 refresh 轮换真实行为（JWT refresh disabled 是否恒真）
+- [ ] 插件 market API：api.trae.com.cn/extensions/api/-/skill/list 的完整清单（未认证可取）
+- [ ] installed-plugins.json 的 marketplace 分页（page_size 16，下一页在哪）

package/docs/rules/ua-validation.md

@@ -0,0 +1,81 @@
+# 规则 01：UA 校验（12403）
+
+> 状态：**规则成立**（主路径）；宽松路径的出现条件**未解**（见 §6）
+> 证据：`docs/probes/ua-2026-08-19.jsonl`（74 条探测记录，含每轮预注册预测与 HIT/MISS 判定）
+> 脚本：`scripts/probe-ua.mjs`（`--set matrix|predict…predict12` 可复跑全部轮次）
+
+## 1. 现象（上游咒语原文）
+
+- AGENTS.md:22 —「`/agenttool/v1/search`、`/agenttool/v1/webfetch`：UA 必须是 CLI 形态（如 `CLI/unknown CodeBuddy/2.136.0`，`CodeBuddyCode/1.0` 被拒 12403）」
+- README.md:159 —「`GET /v3/config`…UA 必须形如 `CLI/unknown CodeBuddy/2.136.0`，否则报 12403」
+- index.js:551 —「/agenttool rejected the /v2 client UA with error 12403 ("check ua")」
+- cordis.patch.yml:29 —「e.g. "CLI/unknown CodeBuddy/2.136.0" — the /v2 client UA is rejected with error 12403」
+
+咒语形态：一个**必须逐字长这样的字符串**。本课题把它拆成了可证伪的字段规则。
+
+## 2. 规则（每条附验证过程）
+
+### R-A：/v3/config 的 UA 门 = 子串正则，不是全串比对
+
+**规则**：UA 通过 ⟺ 其中包含匹配 `/codebuddy\/[^a-z\s]*\./i` 的子串——即 `codebuddy` 产品 token（**大小写不敏感**）后紧跟一段**不含 ASCII 字母、不含空格**且**至少含一个字面点号**的"版本"前缀；点号之后是什么不再检查；token 在 UA 中的位置不限。
+
+**验证链**（全部实测，括号内为该轮 HIT/MISS）：
+
+| 规则迭代 | 内容 | 结局 |
+|---|---|---|
+| H1 | 需要 `CodeBuddy/<semver>` token，其余装饰 | 被 `codebuddy/2.136.0`（小写通过）推翻 |
+| R1 | 不区分大小写子串 `codebuddy/` | 被 `X/y CODEBUDDY/1`（12403）推翻 |
+| R1′ | 白名单两种大小写 | 被 `Codebuddy/1.0`、`codeBuddy/1.0`、`CODEBUDDY/2.136.0` 全通过推翻 |
+| R2/R3 | 版本长度 ≥2 / ≥3 | 被 `CodeBuddy/111`（3 字符仍 12403）、`CodeBuddy/abcd`（4 字符仍 12403）推翻 |
+| R6 | 双正则析取（CLI 形 ∨ semver token） | 被 `CLI/unknown CodeBuddy/abcd`（12403）推翻 |
+| R7/R8 | `/codebuddy\/\d+\.\d+/i` → `/codebuddy\/\d+\./i` | 被 `CodeBuddy/.5`（点前无数字仍通过）推翻 |
+| R9/R10 | 首字符类 `[\d.]` / `[\d.-]` | 被 `-.5`、`+.5`、`_.5` 通过推翻 |
+| **R11→R-A** | `/codebuddy\/[^a-z\s]*\./i` | **12 条预注册预测 11 条 HIT**（见下） |
+
+R-A 的预注册预测命中记录（未观测行为 → 实测）：
+- `CodeBuddy/.` → 200 **HIT**；`CodeBuddy/..` → 200 **HIT**（孤立点号即合法）
+- `CodeBuddy/x.` → 12403 **HIT**（字母打头、点后无内容才构成拒因）
+- `CodeBuddy/汉.5` → 不可测（HTTP 头为 ByteString，非 ASCII 无法发送，证据记 n/a）
+- `CodeBuddy/ .` → 12403 **HIT**（空格断版本段）
+- `CodeBuddy/ab.1`、`CodeBuddy/a1.2` → 12403 **HIT**（点前含字母即拒）
+- `CodeBuddy/1.0` 控制 → 200 **HIT**
+- `CodeBuddy/v1.2`、`CodeBuddy/1a.2`、`CodeBuddy/x.5`、`CodeBuddy/Z.9` → 12403（实测，反向锁定"点前禁字母"）
+
+### R-B：触发 12403 的最小变异
+
+**规则**：从现网 UA `CLI/unknown CodeBuddy/2.136.0` 出发，**单字符替换**第一个版本数字为任意 ASCII 字母（如 `CodeBuddy/x.136.0`）即触发 12403；没有任何单字符删除能触发（`2.136.0` 删首字符得 `.136.0` 仍合法，删一个点仍有另一个点）。校验器唯一检查的字段是 UA 中的 `codebuddy/<非字母非空格且含点>` token；`CLI/unknown` 前缀、`X-IDE-*`、`X-Product`、`X-Requested-With` 均不参与校验（`no-xproduct` 200；`ide-other`、`case-cli-lower`、`suffix-added` 全 200）。
+
+拒绝面：`HTTP 400` + `{"code":12403,"msg":"check ua, get coding copilot version error"}`。
+
+### R-C：端点作用域 —— 咒语的作用域是错的
+
+- **`/v3/config`：有 UA 门**（本规则全部证据所在）。
+- **`/v2/chat/completions`：无 UA 门**。真实字节证据：`docs/probes/bridge-flash-ab-2026-08-18.jsonl` 中线上桥以 `user-agent: deepseek-harness/0.1.0-rc.6` 成功；探测补证 `Garbage/0.0` + `stream:true` → 200 SSE 流（`predict-chat-stream-garbage-ua` HIT）。
+- **`/agenttool/v1/search`：当前无 UA 门**（api-key 认证下）。咒语称 `CodeBuddyCode/1.0` 在此被 12403，实测 `CodeBuddyCode/1.0`、`Garbage/0.0`、`CodeBuddy/ab` **全部 200 并返回搜索结果**（`predict-agenttool-*` 三条）。咒语描述的是历史行为或 OAuth 路径行为——本插件使用的 api-key 直调路径上该门不存在。
+
+## 3. 对 CLIENT_HEADERS 的裁判（重构依据）
+
+| 字段 | 判定 | 依据 |
+|---|---|---|
+| `User-Agent: CLI/unknown CodeBuddy/2.136.0` | **部分是规则**：仅需含 `codebuddy/` + 含点的非字母版本段；`CLI/unknown` 前缀与具体版本号**是迷信** | R-A 全部证据 |
+| `X-IDE-Type/Name/Version`、`X-Product-Version` | **对校验是迷信**（是否参与遥测/路由 = 课题 3 待查） | `no-xproduct`、矩阵伴随头组 |
+| `X-Product: SaaS` | 同上，/v3/config 不查 | `no-xproduct` 200 |
+| `X-Requested-With` | /v3/config、/agenttool 均不查 | 矩阵未携带仍 200（探测脚本只发了 Accept/Auth/x-api-key/UA） |
+
+## 4. 红线条目核对
+
+- 咒语未入库：每条结论上方附验证链；"宽松路径"问不动 → §6 标未解。
+- 真实字节基准：/v2 无 UA 门的结论以 `bridge-flash-ab-2026-08-18.jsonl` 抓包为基准；探测变异本身是受控实验而非对照基准。
+- 低速率：74 次请求，间隔 1.5–2s，单账号，全部只读（chat 臂 `max_tokens=1`，search 臂 `max_results:1`）。
+
+## 5. 现象 → 规则的可复跑路径
+
+```bash
+node scripts/probe-ua.mjs --set matrix      # 17 变异 + 2 chat 臂
+node scripts/probe-ua.mjs --set predictN    # N=1..12，逐轮预注册预测
+```
+
+## 6. 未解
+
+- **宽松路径（flapping）**：严格规则之外，少数请求间歇放行非标版本（`CLI/unknown CodeBuddy/abc`、`CodeBuddy/a.1`、`CodeBuddy/abc` 各通过一次；`a.1` 复测 4/4 拒、`abc` 复测 2 拒 1 放）。放行条件（节点哈希 / 灰度 / 时间窗）未能从黑盒确定。工程结论：**按严格规则构造 UA，不把宽松路径当能力依赖**。
+- 字母打头版本中 `a.1` 曾通过一次：若未来复现稳定，需重开本课题（脚本预测集可直接扩展）。

package/host-config.js

@@ -0,0 +1,282 @@
+/**
+ * host-config.js — dsh 宿主配置层的读写通道（按宿主能力选路）。
+ *
+ * 为什么需要这一层（dsh 0.1.7-alpha.2 实测，2026-09-23）：
+ * 上游把「用户配置文档」整体换成了「profile 的 volatile 配置表单」——
+ *   - `@deepseek-ai/dsh-settings-file` 被删除（npm 上 0.1.7-alpha.2 已 404），
+ *     `settings` 服务改由 `@deepseek-ai/dsh-settings` 提供；
+ *   - `~/.dsh/settings.yaml` 降级为 legacy：Loader 稳定后**一次性导入** profile
+ *     patch，随即改名 `settings.yaml.imported`（实测真实 web profile 下
+ *     `llm-pi-ai` 段导入成功，profile patch 1.6KB → 12KB）；
+ *   - `ctx.settings.register(ns, schema)` **已不存在**（调用即 TypeError），
+ *     取而代之的是 `configure({auto}, fiber)`（页面策略）+
+ *     `describe/update/replace/mutate(ns=profile entry id, …, expectedRevision)`；
+ *   - 写入由 `dsh-config-editor` 落到 profile 的 `cordis.patch.yml`，立即生效；
+ *   - 只有 `.volatile()` 字段可表单编辑——`llm-pi-ai` 的 `providers` 在 0.1.7
+ *     正是 volatile，所以本插件的模型镜像/路由存在性管理能平移过去。
+ *
+ * 本模块把两代宿主的差异收在一处：上层只产出 ops（set/unset 一条路径），
+ * 由这里决定走新 seam 还是旧的 settings.yaml 文档编辑。写入**永不 reject**
+ * （踩坑 #33：fire-and-forget 必须落地）——失败记在 lastError 并回传结果对象。
+ */
+
+import { readFileSync } from 'node:fs'
+import YAML from 'yaml'
+import { writeTextAtomic } from './core/json-store.js'
+
+/** llm-pi-ai 在 profile 里的 entry id（也是新 seam 的命名空间）。 */
+const NS = 'llm-pi-ai'
+
+/** 按路径取值；任一段缺失返回 undefined（用于"该路径当前有没有东西"的判定）。 */
+function getPath(root, path) {
+  let cur = root
+  for (const seg of path) {
+    if (cur == null || typeof cur !== 'object') return undefined
+    cur = cur[seg]
+  }
+  return cur
+}
+
+/** 稳定序列化：键排序后 JSON，用于同值比对（避免每次重铺都判为"变了"）。 */
+function stable(value) {
+  try {
+    return JSON.stringify(value, (_k, v) => (v && typeof v === 'object' && !Array.isArray(v)
+      ? Object.keys(v).sort().reduce((o, k) => { o[k] = v[k]; return o }, {})
+      : v)) ?? 'null'
+  } catch {
+    return String(value)
+  }
+}
+
+export function createHostConfigLayer({ settingsPath, schema, legacyNamespace = 'dsh-tap', log = () => {} }) {
+  let settingsCtx = null
+  let service = null
+  let fiber = null
+  let disposeConfigure = null
+  let revision = null
+  let lastError = null
+  let attachError = null
+
+  /**
+   * 活取 settings 服务。宿主每次写入都会重载 profile patch，Settings 服务实例
+   * **可能被替换**（上游 README：a late-loading or replaced Settings service
+   * picks the policy up）——缓存的实例引用会带着陈旧 revision，写必撞
+   * SETTINGS_CONFLICT 且重试无效（实测：expected revision 5, now 6，三次全败）。
+   * cordis 的 ctx.<service> 是实时 getter，故一律经子上下文现取。
+   */
+  function svc() {
+    const live = settingsCtx ? settingsCtx.settings : null
+    return live ?? service
+  }
+
+  /** 旧宿主路径：注释保留的 settings.yaml 文档编辑。 */
+  function legacyDoc() {
+    try {
+      return YAML.parseDocument(readFileSync(settingsPath, 'utf8'))
+    } catch {
+      return new YAML.Document()
+    }
+  }
+
+  function legacyApply(ops) {
+    const doc = legacyDoc()
+    let changed = false
+    for (const op of ops) {
+      const path = [NS, ...op.path]
+      if (op.op === 'unset') {
+        if (doc.getIn(path)) { doc.deleteIn(path); changed = true }
+      } else {
+        const next = YAML.parse(YAML.stringify(op.value ?? null))
+        if (YAML.stringify(doc.getIn(path) ?? null) !== YAML.stringify(next)) {
+          doc.setIn(path, next)
+          changed = true
+        }
+      }
+    }
+    if (changed) writeTextAtomic(settingsPath, String(doc))
+    return { ok: true, mode: 'legacy', changed }
+  }
+
+  /** 新宿主路径：Settings forms seam（写落 profile patch，立即生效）。 */
+  function formsAvailable() {
+    const s = svc()
+    return !!s && typeof s.mutate === 'function'
+  }
+
+  function describeEntry() {
+    const s = svc()
+    if (!s || typeof s.describe !== 'function') return null
+    try {
+      const list = s.describe() ?? []
+      const hit = list.find((d) => d && d.ns === NS) ?? null
+      if (hit) revision = hit.revision
+      return hit
+    } catch (err) {
+      attachError = `describe failed: ${err?.message ?? err}`
+      return null
+    }
+  }
+
+  async function formsApply(ops) {
+    const s0 = svc()
+    if (s0 && s0.writable === false) {
+      return { ok: false, mode: 'forms', error: 'SETTINGS_NOT_WRITABLE（当前 profile 不接受表单写入）' }
+    }
+    for (let attempt = 0; attempt < 4; attempt++) {
+      // 每轮都重新活取服务 + 重读 revision：宿主可能在我们两次调用之间
+      // 重载 profile 并替换 Settings 实例（见 svc() 注释）。
+      const s = svc()
+      if (!s || typeof s.mutate !== 'function') {
+        return { ok: false, mode: 'forms', error: 'SETTINGS_SERVICE_GONE（宿主重载后 settings 服务不可用）' }
+      }
+      const entry = describeEntry()
+      const expected = entry?.revision ?? revision ?? undefined
+      // 写前比对：同值不写。重复写会白涨 revision 并触发一次 profile 重载，
+      // 目录轮询/启动重铺这类高频路径上会抖成 reload 风暴。
+      const pending = ops.filter((op) => {
+        const cur = getPath(entry?.value, op.path)
+        if (op.op === 'unset') return cur !== undefined
+        return stable(cur) !== stable(op.value ?? null)
+      })
+      if (pending.length === 0) return { ok: true, mode: 'forms', changed: false, revision: entry?.revision ?? null }
+      try {
+        await s.mutate(NS, pending, expected)
+        const after = describeEntry()
+        return { ok: true, mode: 'forms', changed: true, revision: after?.revision ?? null }
+      } catch (err) {
+        const code = err?.code
+        if (code === 'SETTINGS_CONFLICT' && attempt < 3) continue // revision 过期 → 重取服务重读重试
+        return { ok: false, mode: 'forms', error: `${code ?? 'ERR'}: ${err?.message ?? err}` }
+      }
+    }
+    return { ok: false, mode: 'forms', error: 'SETTINGS_CONFLICT: 四次重试仍未拿到最新 revision' }
+  }
+
+  return {
+    /**
+     * 挂到宿主：注入 settings 服务，并按能力声明页面策略。
+     * 0.1.7+：configure({auto:false}) —— 本插件自带设置卡，不要让宿主按
+     *          Config schema 自动生成一个页面（pi-ai 自己也这么做）。
+     * ≤0.1.6：register(ns, schema) —— 旧 `settings.plugin.item` 卡片派发靠这个
+     *          命名空间声明（宿主 api-proxy `settings.describe` 出清单）。
+     */
+    attach(ctx) {
+      ctx.inject(['settings'], (sctx) => {
+        settingsCtx = sctx ?? null
+        service = sctx?.settings ?? null
+        fiber = ctx.fiber ?? null
+        const s = svc()
+        if (!s) { attachError = 'settings service unavailable'; return }
+        if (typeof s.configure === 'function') {
+          try {
+            disposeConfigure = s.configure({ auto: false }, fiber) ?? null
+          } catch (err) {
+            attachError = `configure failed: ${err?.message ?? err}`
+            log(`[dsh-tap] settings configure(auto:false) failed: ${err?.message ?? err}`)
+          }
+        } else if (typeof s.register === 'function' && schema) {
+          try {
+            s.register(legacyNamespace, schema)
+          } catch (err) {
+            attachError = `register failed: ${err?.message ?? err}`
+            log(`[dsh-tap] settings namespace register failed: ${err?.message ?? err}`)
+          }
+        } else {
+          attachError = 'settings service exposes neither configure() nor register()'
+        }
+      })
+    },
+
+    dispose() {
+      if (disposeConfigure) { try { disposeConfigure() } catch {} disposeConfigure = null }
+      settingsCtx = null
+      service = null
+    },
+
+    /** 当前选路：'forms'（dsh 0.1.7+）/ 'legacy'（≤0.1.6 或无 settings 服务）。 */
+    mode() {
+      return formsAvailable() ? 'forms' : 'legacy'
+    },
+
+    /** 宿主 settings 服务是否挂上（与 mode 分开报：无服务时仍走 legacy 文件层）。 */
+    servicePresent() {
+      return !!svc()
+    },
+
+    get lastError() { return lastError },
+    get attachError() { return attachError },
+
+    /** 诊断：新 seam 到底给了什么（升级排查用，经设置路由 ?probe=host-config 暴露）。 */
+    probe() {
+      const s = svc()
+      const entry = describeEntry()
+      const api = s ? Object.getOwnPropertyNames(Object.getPrototypeOf(s)) : []
+      return {
+        mode: this.mode(),
+        servicePresent: !!s,
+        formsWritable: formsAvailable(),
+        api: api.filter((n) => !n.startsWith('_') && n !== 'constructor'),
+        writable: s?.writable ?? null,
+        documentPath: (() => { try { return s?.documentPath ?? null } catch { return null } })(),
+        entryFound: !!entry,
+        entryNs: entry?.ns ?? null,
+        entryRevision: entry?.revision ?? null,
+        autoGenerate: entry?.autoGenerate ?? null,
+        applies: entry?.applies ?? null,
+        valueKeys: entry && entry.value && typeof entry.value === 'object' ? Object.keys(entry.value) : null,
+        providerIds: entry?.value?.providers && typeof entry.value.providers === 'object'
+          ? Object.keys(entry.value.providers)
+          : null,
+        schemaKeys: entry?.schema && typeof entry.schema === 'object' ? Object.keys(entry.schema).slice(0, 12) : null,
+        describeCount: (() => { try { return (s?.describe?.() ?? []).length } catch { return null } })(),
+        allNamespaces: (() => {
+          try { return (s?.describe?.() ?? []).map((d) => d?.ns).filter(Boolean) } catch { return null }
+        })(),
+        attachError,
+        lastError,
+        legacySettingsPath: settingsPath,
+        legacyExists: (() => { try { readFileSync(settingsPath, 'utf8'); return true } catch { return false } })(),
+      }
+    },
+
+    /**
+     * 有效 providers 视图（对账/去重判定用）。
+     * forms：读 describe 的 live value（含 patch 层与 profile 覆盖的合成结果）；
+     * legacy：解析 settings.yaml 的 llm-pi-ai.providers。
+     */
+    readProviders() {
+      if (formsAvailable()) {
+        const entry = describeEntry()
+        const p = entry?.value?.providers
+        if (p && typeof p === 'object') return p
+        return {}
+      }
+      try {
+        return YAML.parse(readFileSync(settingsPath, 'utf8'))?.[NS]?.providers ?? {}
+      } catch {
+        return {}
+      }
+    },
+
+    /**
+     * 应用一组 ops（path 相对 llm-pi-ai 配置根，例如 ['providers','trae']）。
+     * 永不 reject：失败落 lastError 并在结果对象里带 error。
+     */
+    async applyOps(ops) {
+      if (!Array.isArray(ops) || ops.length === 0) return { ok: true, mode: this.mode(), changed: false }
+      let res
+      try {
+        res = formsAvailable() ? await formsApply(ops) : legacyApply(ops)
+      } catch (err) {
+        res = { ok: false, mode: this.mode(), error: `${err?.message ?? err}` }
+      }
+      if (!res.ok) {
+        lastError = res.error
+        log(`[dsh-tap] host config write failed (${res.mode}): ${res.error}`)
+      } else if (lastError) {
+        lastError = null
+      }
+      return res
+    },
+  }
+}