@dsh-ft/dsh-fft-settings 0.0.0-stage → 0.5.1

package/docs/ftshare-settings-results-er.svg

@@ -0,0 +1,122 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg viewBox="0 0 1280 720" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="ftshare-settings-results-er-title ftshare-settings-results-er-desc" id="ftshare-settings-results-er-root">
+  <defs>
+      <style>@import url('https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&amp;family=Geist:wght@400;500;600&amp;family=Geist+Mono:wght@400;500;600&amp;family=Noto+Serif:ital@0;1&amp;family=Noto+Sans+KR:wght@400;500;600&amp;family=Noto+Serif+KR:wght@400&amp;family=Noto+Sans+TC:wght@400;500;600&amp;family=Noto+Serif+TC:wght@400&amp;display=swap');
+      #ftshare-settings-results-er-root { font-family: 'Geist', 'PingFang SC', 'Noto Sans SC', system-ui, sans-serif; color: #2d3142; }
+      #ftshare-settings-results-er-root .lede { max-width: 74ch; color: #4f5d75; font-size: 0.95rem; line-height: 1.6; margin-bottom: 2rem; }
+      #ftshare-settings-results-er-root .diagram-container { width: 100%; overflow-x: auto; }
+      #ftshare-settings-results-er-root .diagram-container { overflow-x: visible; }
+      #ftshare-settings-results-er-root .note { max-width: 78ch; color: #4f5d75; font-size: 0.8rem; line-height: 1.6; margin-top: 1.25rem; }
+      #ftshare-settings-results-er-root .colophon { font-family: 'Geist Mono', monospace; font-size: 0.7rem; letter-spacing: 0.08em; color: #7a8399;
+                border-top: 1px solid rgba(45,49,66,0.10); padding-top: 0.85rem; margin-top: 2rem; }</style>
+  </defs>
+  <title id="ftshare-settings-results-er-title">设置状态、保存结果与检测结果的值对象</title>
+  <desc id="ftshare-settings-results-er-desc">ER 图：API Key 状态继承凭据状态，配置结果分别携带本次保存结果与验证结果，验证结果由远端服务和 Key 两个探测结果组成。</desc>
+  <rect width="100%" height="100%" fill="#f5f5f5"/>
+  <rect x="60" y="180" width="300" height="188" rx="6" fill="#f5f5f5"/>
+  <rect x="60" y="180" width="300" height="188" rx="6" fill="#eb6c36" fill-opacity="0.08" stroke="#eb6c36" stroke-width="1"/>
+  <rect x="68" y="188" width="34" height="12" rx="2" fill="none" stroke="#eb6c36" stroke-width="0.8"/>
+  <text x="85" y="197" fill="#eb6c36" font-size="7" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">ENTITY</text>
+  <text x="110" y="197" fill="#2d3142" font-size="12" font-weight="600" font-family="'Geist', 'PingFang SC', 'Noto Sans SC', sans-serif">ApiKeyStatus</text>
+  <text x="72" y="216" fill="#7a8399" font-size="8" font-family="'Geist Mono', monospace">features/api-key/contract.ts</text>
+  <line x1="72" y1="232" x2="348" y2="232" stroke="#2d3142" stroke-opacity="0.12" stroke-width="0.8"/>
+  <text x="72" y="254" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">configured: boolean</text>
+  <text x="72" y="274" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">writable: boolean</text>
+  <text x="72" y="294" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">source?: string</text>
+  <text x="72" y="314" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">maskedValue?: string（仅展示）</text>
+  <text x="72" y="334" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">revision: number（进程内）</text>
+  <text x="72" y="354" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">validation: ValidationResult</text>
+  <rect x="460" y="180" width="320" height="148" rx="6" fill="#f5f5f5"/>
+  <rect x="460" y="180" width="320" height="148" rx="6" fill="#2d3142" fill-opacity="0.03" stroke="#2d3142" stroke-opacity="0.30" stroke-width="1"/>
+  <rect x="468" y="188" width="34" height="12" rx="2" fill="none" stroke="#2d3142" stroke-opacity="0.30" stroke-width="0.8"/>
+  <text x="485" y="197" fill="#7a8399" font-size="7" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">ENTITY</text>
+  <text x="510" y="197" fill="#2d3142" font-size="12" font-weight="600" font-family="'Geist', 'PingFang SC', 'Noto Sans SC', sans-serif">ValidationResult</text>
+  <text x="472" y="216" fill="#7a8399" font-size="8" font-family="'Geist Mono', monospace">features/api-key/contract.ts</text>
+  <line x1="472" y1="232" x2="768" y2="232" stroke="#2d3142" stroke-opacity="0.12" stroke-width="0.8"/>
+  <text x="472" y="254" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">status: not_tested | passed | …</text>
+  <text x="472" y="274" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">remote: ProbeResult</text>
+  <text x="472" y="294" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">apiKey: ProbeResult</text>
+  <text x="472" y="314" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">testedAt?: string</text>
+  <rect x="860" y="180" width="320" height="108" rx="6" fill="#f5f5f5"/>
+  <rect x="860" y="180" width="320" height="108" rx="6" fill="#2d3142" fill-opacity="0.03" stroke="#2d3142" stroke-opacity="0.30" stroke-width="1"/>
+  <rect x="868" y="188" width="34" height="12" rx="2" fill="none" stroke="#2d3142" stroke-opacity="0.30" stroke-width="0.8"/>
+  <text x="885" y="197" fill="#7a8399" font-size="7" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">ENTITY</text>
+  <text x="910" y="197" fill="#2d3142" font-size="12" font-weight="600" font-family="'Geist', 'PingFang SC', 'Noto Sans SC', sans-serif">ProbeResult</text>
+  <text x="872" y="216" fill="#7a8399" font-size="8" font-family="'Geist Mono', monospace">features/api-key/contract.ts</text>
+  <line x1="872" y1="232" x2="1168" y2="232" stroke="#2d3142" stroke-opacity="0.12" stroke-width="0.8"/>
+  <text x="872" y="254" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">status: ProbeState（11 项）</text>
+  <text x="872" y="274" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">message: string</text>
+  <rect x="60" y="440" width="300" height="128" rx="6" fill="#f5f5f5"/>
+  <rect x="60" y="440" width="300" height="128" rx="6" fill="#2d3142" fill-opacity="0.03" stroke="#2d3142" stroke-opacity="0.30" stroke-width="1"/>
+  <rect x="68" y="448" width="34" height="12" rx="2" fill="none" stroke="#2d3142" stroke-opacity="0.30" stroke-width="0.8"/>
+  <text x="85" y="457" fill="#7a8399" font-size="7" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">ENTITY</text>
+  <text x="110" y="457" fill="#2d3142" font-size="12" font-weight="600" font-family="'Geist', 'PingFang SC', 'Noto Sans SC', sans-serif">CredentialStatus</text>
+  <text x="72" y="476" fill="#7a8399" font-size="8" font-family="'Geist Mono', monospace">features/api-key/contract.ts</text>
+  <line x1="72" y1="492" x2="348" y2="492" stroke="#2d3142" stroke-opacity="0.12" stroke-width="0.8"/>
+  <text x="72" y="514" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">configured: boolean</text>
+  <text x="72" y="534" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">writable: boolean</text>
+  <text x="72" y="554" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">source?: string</text>
+  <rect x="460" y="440" width="320" height="128" rx="6" fill="#f5f5f5"/>
+  <rect x="460" y="440" width="320" height="128" rx="6" fill="#2d3142" fill-opacity="0.03" stroke="#2d3142" stroke-opacity="0.30" stroke-width="1"/>
+  <rect x="468" y="448" width="34" height="12" rx="2" fill="none" stroke="#2d3142" stroke-opacity="0.30" stroke-width="0.8"/>
+  <text x="485" y="457" fill="#7a8399" font-size="7" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">ENTITY</text>
+  <text x="510" y="457" fill="#2d3142" font-size="12" font-weight="600" font-family="'Geist', 'PingFang SC', 'Noto Sans SC', sans-serif">ConfigureResult</text>
+  <text x="472" y="476" fill="#7a8399" font-size="8" font-family="'Geist Mono', monospace">features/api-key/contract.ts</text>
+  <line x1="472" y1="492" x2="768" y2="492" stroke="#2d3142" stroke-opacity="0.12" stroke-width="0.8"/>
+  <text x="472" y="514" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">save: SaveOutcome</text>
+  <text x="472" y="534" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">validation: ValidationResult</text>
+  <text x="472" y="554" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">保存失败不回滚验证结果</text>
+  <rect x="860" y="440" width="320" height="128" rx="6" fill="#f5f5f5"/>
+  <rect x="860" y="440" width="320" height="128" rx="6" fill="#2d3142" fill-opacity="0.03" stroke="#2d3142" stroke-opacity="0.30" stroke-width="1"/>
+  <rect x="868" y="448" width="34" height="12" rx="2" fill="none" stroke="#2d3142" stroke-opacity="0.30" stroke-width="0.8"/>
+  <text x="885" y="457" fill="#7a8399" font-size="7" font-family="'Geist Mono', monospace" text-anchor="middle" letter-spacing="0.08em">ENTITY</text>
+  <text x="910" y="457" fill="#2d3142" font-size="12" font-weight="600" font-family="'Geist', 'PingFang SC', 'Noto Sans SC', sans-serif">SaveOutcome</text>
+  <text x="872" y="476" fill="#7a8399" font-size="8" font-family="'Geist Mono', monospace">features/api-key/contract.ts</text>
+  <line x1="872" y1="492" x2="1168" y2="492" stroke="#2d3142" stroke-opacity="0.12" stroke-width="0.8"/>
+  <text x="872" y="514" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">status: saved | failed</text>
+  <text x="872" y="534" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">code?: invalid_input | read_only</text>
+  <text x="872" y="554" fill="#4f5d75" font-size="9" font-family="'Geist Mono', 'Noto Sans Mono CJK SC', monospace">message: string</text>
+  <line x1="360" y1="254" x2="460" y2="254" stroke="#4f5d75" stroke-width="1.2"/>
+  <rect x="376" y="228" width="16" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="384" y="237" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">1</text>
+  <rect x="428" y="228" width="16" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="436" y="237" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">1</text>
+  <rect x="381.5" y="268" width="57" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="410" y="277" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">validation</text>
+  <line x1="210" y1="368" x2="210" y2="440" stroke="#4f5d75" stroke-width="1.2"/>
+  <rect x="186" y="382" width="16" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="194" y="391" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">1</text>
+  <rect x="186" y="414" width="16" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="194" y="423" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">1</text>
+  <rect x="218.36" y="398.0" width="42" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="239.36" y="407.0" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">extends</text>
+  <line x1="620" y1="328" x2="620" y2="440" stroke="#4f5d75" stroke-width="1.2"/>
+  <rect x="596" y="342" width="16" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="604" y="351" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">1</text>
+  <rect x="596" y="414" width="16" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="604" y="423" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">1</text>
+  <rect x="628.3" y="378.0" width="57" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="656.8" y="387.0" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">validation</text>
+  <line x1="780" y1="240" x2="860" y2="240" stroke="#4f5d75" stroke-width="1.2"/>
+  <rect x="796" y="214" width="16" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="804" y="223" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">1</text>
+  <rect x="822.5" y="214" width="27" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="836" y="223" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">1..2</text>
+  <rect x="794" y="254" width="52" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="820" y="263" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">two roles</text>
+  <line x1="780" y1="504" x2="860" y2="504" stroke="#4f5d75" stroke-width="1.2"/>
+  <rect x="796" y="478" width="16" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="804" y="487" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">1</text>
+  <rect x="828" y="478" width="16" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="836" y="487" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">1</text>
+  <rect x="806.5" y="518" width="27" height="12" rx="2" fill="#f5f5f5"/>
+  <text x="820" y="527" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" text-anchor="middle">save</text>
+  <line x1="40" y1="640" x2="1240" y2="640" stroke="#2d3142" stroke-opacity="0.10" stroke-width="0.8"/>
+  <text x="40" y="656" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace" letter-spacing="0.18em">LEGEND</text>
+  <text x="40" y="684" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace">1</text>
+  <line x1="50" y1="681" x2="86" y2="681" stroke="#4f5d75" stroke-width="1.2"/>
+  <text x="94" y="684" fill="#4f5d75" font-size="8" font-family="'Geist Mono', monospace">N</text>
+  <text x="114" y="684" fill="#4f5d75" font-size="8.5" font-family="'Geist', 'PingFang SC', 'Noto Sans SC', sans-serif">关系基数</text>
+  <rect x="192" y="674" width="14" height="10" rx="2" fill="#eb6c36" fill-opacity="0.08" stroke="#eb6c36" stroke-width="1"/>
+  <text x="216" y="684" fill="#4f5d75" font-size="8.5" font-family="'Geist', 'PingFang SC', 'Noto Sans SC', sans-serif">聚合根</text>
+</svg>

package/docs/kline-integration.md

@@ -0,0 +1,258 @@
+# dsh_kline：实际代码与接入后代码对照
+
+核对时间：2026-09-17。基线：`dsh_kline@d6253f07c90ebbeb25a31dd3a76565c242558d36`。
+
+本文的“当前”摘自工作区真实源码，省略部分用注释标记。“接入后”是待 kline 实现的示例，不代表本包已修改 kline。FTShare Settings 不提供 Python 明文凭据 HTTP 服务；下面的 `privateBridge` / `settings_bridge` 是 kline 需要实现的私有 IPC 适配层。
+
+## 0. 落地状态（2026-10-14 更新）
+
+kline 侧已实现**凭据这一段**，但不是本文设想的私有 IPC，而是更小的文件契约：`FTShare-Lab/dsh_kline` PR #10（分支 `feat/ftshare-settings-bridge`，提交 `21539cd`，基线 `v0.3.5`）。该实现已随上游 `v0.4.0` 发布（上游未合 PR，而是本地整合并加了校验修正），本包现在钉的是这个上游版本，不再跟 `-ft` 补丁 tag。
+
+- 已实现：`src/ftshare-settings-bridge.ts` 用 `apiKey.resolve()` + `subscribe()` 把当前 Key 发布到 `<runtime>/credentials/ftshare-<hostPid>.json`（`0600`/目录 `0700`、原子替换、宿主退出即删、启动时清理已死宿主的残留）；`src/index.ts` 以 `ctx.inject(['ftshareSettings'], …)` 起桥，`inject` 仍是 `['webServer']`，没有该服务的宿主行为不变；启动器仅在拿到 `DSH_KLINE_HOST_PID` 时注入 `DSH_KLINE_SETTINGS_KEY_FILE`；`tools/fetch.py` 在**每次**建 FTShare 客户端前重读该文件，来源标记为 `settings_bridge` 且 `can_clear=false`（该 Key 归设置页所有）。
+- 取代 IPC 的理由：两侧本就共享运行时目录（`services/<hostPid>.json` 已是同一约定），文件无需握手、实例认证与 Python 重连，跨 MCP 重启依然成立；`createEnvironment()` 仍未使用（它只是启动快照，本文档对它的判断不变）。
+- 尚未实现：§2／§3 的工具委托——`configure_ftshare` / `test_ftshare_connection` / `data_source_status` 仍走 kline 自己的本地实现，因此“保存与测试结果不混淆”的适配层、Python 侧 IPC 客户端与 `persist=false` 的语义统一都还缺。
+- 与 §4 的差异：当前实现**保留**了环境变量与插件自有 JSON 回退，只是把顺序固定为 显式 `FTSHARE_API_KEY_FILE` → 设置桥文件 → 插件自有存储；并非本文设想的“DSH 模式停用旧回退”。这一条要继续推进还是就此定型，取决于是否要让设置页成为唯一凭据来源。
+
+## 1. Host：现在只向 Python 转发
+
+当前 `dsh_kline/src/index.ts`：
+
+```ts
+export const name = 'dsh-kline-sidebar'
+export const inject = ['webServer']
+
+export function apply(ctx: WebServerContext): void {
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix',
+    path: '/dsh-kline',
+    handler: serveRuntimeSession,
+  }), 'dsh-kline: chart session route')
+}
+```
+
+同一文件的 `serveRuntimeSession` 当前分支（包括 `configure_ftshare` 和 `test_ftshare_connection`）：
+
+```ts
+const body = await readRequestBody(request)
+await proxyJson(response, `${serviceOrigin(session)}/api/tools/${encodeURIComponent(action)}`, {
+  method: 'POST',
+  headers: { ...chartServiceHeaders(session), 'Content-Type': 'application/json' },
+  body: body.toString('utf8'),
+})
+```
+
+因此只改 Host 页面的代理分支，仍覆盖不了 MCP 直接调用 Python 的入口。建议保留行情代理，让两种入口最终都从 Python 私有桥调用同一个 Host 适配器。
+
+接入后 kline 仓库 `src/index.ts` 的关键变化（本节与下文写作 `src/…`、`scripts/…` 的路径都相对 kline 仓库根，不是本包）：
+
+```ts
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@ft/dsh-fft-settings'
+import { createKlineFtshareAdapter } from './ftshare-adapter.js'
+// 由 kline 新增，不是 FTShare Settings 已有导出：
+import { startPrivateSettingsBridge } from './private-settings-bridge.js'
+
+export const inject = ['webServer', 'ftshareSettings']
+export function apply(ctx: Context): void {
+  const adapter = createKlineFtshareAdapter(ctx.ftshareSettings.apiKey)
+  // 保留原 /dsh-kline 行情路由注册。
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'prefix', path: '/dsh-kline', handler: serveRuntimeSession,
+  }), 'dsh-kline: chart session route')
+
+  // 私有 IPC 必须仅允许当前实例的 Python 访问，不能注册为浏览器公开路由。
+  const bridge = startPrivateSettingsBridge(adapter)
+  ctx.effect(() => () => bridge.dispose(), 'kline: private settings bridge')
+  ctx.effect(() => ctx.ftshareSettings.apiKey.subscribe(() => {
+    bridge.notifyCredentialChanged() // 只发失效事件，不带 Key
+  }), 'kline: credential invalidation')
+}
+```
+
+`startPrivateSettingsBridge` 的实现、实例认证、启动信息交接和 Python 重连均属于 kline 后续工作；此处没有伪装成可直接运行的完整桥。创建桥后，需要在现有 `cordis.patch.yml` → `scripts/start-mcp.mjs` → `server.py` 启动链传递其连接参数，并保证 Python 连接到同一个 Host 实例。`createEnvironment()` 只提供启动快照，不能替代动态凭据桥。
+
+> 2026-10-14：凭据这一段已按 §0 的文件契约落地（PR #10），未采用本节的 `startPrivateSettingsBridge`／适配器注入路径；本节其余内容仍是未完成的设想。
+
+## 2. 新增 Host 适配器：保存与测试结果不混淆（未落地）
+
+建议新增 `dsh_kline/src/ftshare-adapter.ts`：
+
+```ts
+import type { ApiKeySettings, ValidationResult } from '@ft/dsh-fft-settings/contract'
+
+const failure = (message: string) => ({ ok: false, message })
+const tested = (validation: ValidationResult) => ({
+  ok: validation.status === 'passed',
+  connection_ok: validation.remote.status === 'available',
+  key_ok: validation.apiKey.status === 'available',
+  validation,
+  message: `${validation.remote.message}；${validation.apiKey.message}`,
+})
+
+export function createKlineFtshareAdapter(apiKey: ApiKeySettings) {
+  return {
+    async configure(args: {
+      api_key?: string | null
+      test_connection?: boolean
+      persist?: boolean
+    }) {
+      if (args.persist === false) return failure('DSH 模式不支持临时 Key，请使用持久化配置')
+      const value = (args.api_key ?? '').trim()
+      const shouldTest = args.test_connection !== false
+      try {
+        if (!value) {
+          await apiKey.clear()
+          const status = await apiKey.describe() // 清除可能露出 .env 回退值
+          const validation = shouldTest ? await apiKey.testConnection() : undefined
+          return {
+            ...(validation ? tested(validation) : { ok: true }),
+            key_saved: false,
+            configured: status.configured,
+            source: status.source,
+            cleared: true,
+            message: validation
+              ? `已清除 DSH 保存值；${validation.remote.message}；${validation.apiKey.message}`
+              : '已清除 DSH 保存值',
+          }
+        }
+        if (!shouldTest) {
+          await apiKey.set(value)
+          return { ok: true, key_saved: true, message: '已保存，未测试' }
+        }
+        const result = await apiKey.configureAndTest(value)
+        return {
+          ...tested(result.validation),
+          ok: result.save.status === 'saved' && result.validation.status === 'passed',
+          key_saved: result.save.status === 'saved',
+          save: result.save,
+          message: `${result.save.message}；${result.validation.remote.message}；${result.validation.apiKey.message}`,
+        }
+      } catch {
+        return failure('配置请求未完成，请重新读取状态；不能据此断言未保存')
+      }
+    },
+    async test() { return tested(await apiKey.testConnection()) },
+    async status() {
+      const { configured, source, writable, validation } = await apiKey.describe()
+      return { configured, source, writable, validation }
+    },
+    // 只供认证后的私有 Python IPC；禁止进入浏览器 RPC 或模型工具返回值。
+    async resolveForPython() { return { value: (await apiKey.resolve()) ?? null } },
+  }
+}
+```
+
+桥的输入层仍须校验 JSON 字段类型、未知字段、大小和操作白名单；TypeScript 类型不代替运行时校验。`resolveForPython` 只能供 Python 内部行情请求使用。不能把 `Object.keys(adapter)` 全部注册到公共 RPC。
+
+## 3. Python MCP：当前调用本地配置函数（未落地）
+
+当前 `dsh_kline/server.py` 的函数体：
+
+```python
+# configure_ftshare(...) 内
+data = configure_ftshare_api_key(api_key, test_connection=test_connection, persist=persist)
+if not data.get("ok"):
+    return _result(data, str(data.get("message") or data.get("error") or "FTShare 配置失败"), error=True)
+return _result(data, str(data.get("message") or "FTShare 配置已更新"))
+
+# test_ftshare_connection_tool() 内
+data = test_ftshare_connection()
+if not data.get("ok"):
+    return _result(data, str(data.get("message") or data.get("error") or "FTShare 连接失败"), error=True)
+return _result(data, str(data.get("message") or "FTShare 连接成功"))
+```
+
+当前 `tools/fetch.py::configure_ftshare_api_key` 的核心行为（摘录）：
+
+```python
+if persist:
+    if value:
+        _write_persisted_ftshare_key(value)
+    else:
+        _remove_persisted_ftshare_key()
+# 省略异常处理
+if value:
+    os.environ["FTSHARE_API_KEY"] = value
+else:
+    os.environ.pop("FTSHARE_API_KEY", None)
+clear_provider_caches()
+# ...
+connection = test_ftshare_connection()
+```
+
+接入后，DSH 模式在同名 helper 中委托 Host；这样 `server.py` 和 `chart_service.py` 的调用可复用一个适配点：
+
+```python
+# tools/fetch.py：建议替换 DSH 模式下的实现
+# settings_bridge 是由 kline 实现的同步、带超时且每实例认证的 IPC 客户端。
+from .settings_bridge import settings_bridge
+
+def configure_ftshare_api_key(api_key, *, test_connection=True, persist=True):
+    result = settings_bridge.call("configure", {
+        "api_key": api_key,
+        "test_connection": test_connection,
+        "persist": persist,
+    })
+    # 即使测试失败，保存也可能已成功，缓存必须失效。
+    clear_provider_caches()
+    return result
+
+def test_ftshare_connection():
+    return settings_bridge.call("test", {})
+```
+
+在 `server.py` 的 async MCP 函数中使用 `await asyncio.to_thread(configure_ftshare_api_key, ...)` 和 `await asyncio.to_thread(test_ftshare_connection)`，避免同步 IPC 阻塞事件循环。原 `_result(...)` 封装可以保留，`data` 中的 `key_saved`、`save`、`validation` 分别说明保存和测试结果。
+
+`data_source_status` 中，SDK 安装状态和版本仍由 kline 本地计算；`configured/source/validation` 改用 `settings_bridge.call("status", {})`。不要直接用 Host 的状态替换包含 SDK 信息的整个工具响应。
+
+## 4. Python 行情：每次操作读取当前 Key（已按文件契约落地，见 §0）
+
+当前 `tools/fetch.py::_ftshare_market_api`：
+
+```python
+def _ftshare_market_api(timeout: float) -> Any:
+    """Create an SDK client with the process key attached to every request."""
+    import ftshare as ft
+
+    key = _valid_ftshare_key(os.environ.get("FTSHARE_API_KEY"))
+    headers = {"FTSHARE_API_KEY": key} if key else None
+    return ft.market_api(timeout=timeout, headers=headers)
+```
+
+接入后（DSH 模式；这是本文设想的 IPC 版本，kline 实际改用 §0 的文件契约）：
+
+```python
+def _ftshare_market_api(timeout: float) -> Any:
+    import ftshare as ft
+
+    resolved = settings_bridge.call("resolveForPython", {})
+    key = _valid_ftshare_key(resolved.get("value"))
+    # 未配置就中止，避免 SDK 自动使用旧环境变量或本地文件作为隐藏回退。
+    if not key:
+        raise RuntimeError("请先在 FTShare 设置中配置 API Key")
+    return ft.market_api(timeout=timeout, headers={"FTSHARE_API_KEY": key})
+```
+
+一次行情操作使用同一客户端／Key 快照，不应在逐根 K 线处理时反复读取。DSH 模式要停用 `_load_persisted_ftshare_key()` 和旧凭据 JSON 回退，不能同时维护两份配置。独立运行模式可以保留现有本地策略，但必须明确分支。Host 通知用于失效 kline 缓存，不能替代请求时解析。
+
+## 验收边界
+
+- 两个入口都覆盖：浏览器图表 HTTP、Python MCP。
+- 设置页改 Key 后，已运行 Python 的下一次操作使用新值。
+- 清除后不继续使用旧 Key；存在 DSH 环境回退时使用实际生效值。
+- 保存成功、检测失败时仍保留 `key_saved=true`；不能只显示“保存失败”。
+- `persist=false` 不静默变为持久化。
+- 明文只流经 Host → 私有 Python IPC → FTShare，不出现在浏览器／MCP 工具结果／日志中。
+- `validation.remote` 和 `validation.apiKey` 分别表示服务与认证，不代表行情数据完整性或全部套餐权限。
+
+### 截至 2026-10-14 的达成情况
+
+| 边界 | 状态 |
+| --- | --- |
+| 两个入口都覆盖 | ✅ 文件契约对浏览器代理与 MCP 直调同时生效（同一份 `tools/fetch.py`） |
+| 设置页改 Key 后，下一次操作使用新值 | ✅ 每次建客户端前重读 |
+| 清除后不继续使用旧 Key | ⚠️ 该文件被清除后不再使用，但环境变量／插件自有存储的回退仍可提供另一个 Key（§4 未收敛项） |
+| 保存成功、检测失败仍保留 `key_saved=true` | ❌ 工具委托未做，仍由 kline 本地实现 |
+| `persist=false` 不静默变持久化 | ❌ 同上，既有行为未变 |
+| 明文只流经 Host → Python → FTShare | ✅ 改为 Host → `0600` 文件 → Python → FTShare，不入日志／工具结果 |
+| 两个 validation 字段的含义 | ✅ 不变（设置页自身语义） |

package/lib/agent.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Agent-plane entry for the FT prompt contract.
+ *
+ * Mounted by an agent preset so the contract exists only for that preset's
+ * agents; the package's host entry keeps providing the settings service and
+ * must not be mounted from a preset (a service row there needs an isolate
+ * realm). The texts and the registration both live in `./guidance.ts`, so this
+ * entry adds no second copy.
+ * @module @dsh-ft/dsh-fft-settings/agent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis plugin name. */
+export declare const name = "@dsh-ft/dsh-fft-settings/agent";
+/**
+ * The prompt registry this entry contributes to. `ftshareSettings` is optional
+ * and mounted in `installGuidance`, so a missing settings row costs only the
+ * credential fact instead of the whole contract.
+ */
+export declare const inject: string[];
+/**
+ * Register the FT prompt contract in the mounting scope.
+ * @param ctx - the preset subtree's context; the preset's agents are the scope.
+ */
+export declare function apply(ctx: Context): void;

package/lib/agent.js

@@ -0,0 +1,26 @@
+/**
+ * Agent-plane entry for the FT prompt contract.
+ *
+ * Mounted by an agent preset so the contract exists only for that preset's
+ * agents; the package's host entry keeps providing the settings service and
+ * must not be mounted from a preset (a service row there needs an isolate
+ * realm). The texts and the registration both live in `./guidance.ts`, so this
+ * entry adds no second copy.
+ * @module @dsh-ft/dsh-fft-settings/agent
+ */
+import { installGuidance } from './guidance.js';
+/** Cordis plugin name. */
+export const name = '@dsh-ft/dsh-fft-settings/agent';
+/**
+ * The prompt registry this entry contributes to. `ftshareSettings` is optional
+ * and mounted in `installGuidance`, so a missing settings row costs only the
+ * credential fact instead of the whole contract.
+ */
+export const inject = ['systemPrompt'];
+/**
+ * Register the FT prompt contract in the mounting scope.
+ * @param ctx - the preset subtree's context; the preset's agents are the scope.
+ */
+export function apply(ctx) {
+    installGuidance(ctx);
+}

package/lib/brand.d.ts

@@ -0,0 +1,53 @@
+/**
+ * FT brand tokens published as a host theme override layer.
+ *
+ * The layer only *adds* brand variables on `body`; it never overrides a
+ * `--dsw-alias-*` value, so host chrome keeps its own palette and any user
+ * theme keeps working underneath. Consumers read `var(--ft-*)` with the same
+ * value as their fallback: the layer is a convenience, not a dependency, so
+ * every sub-plugin keeps its brand colors when this plugin is absent (or when
+ * the host has no `theme` service at all). Scheme-invariant tokens repeat one
+ * value; palette-aware tokens spell both with `light-dark()`.
+ *
+ * Keep those fallbacks equal to {@link FT_BRAND_TOKENS}; `tests/brand.test.mjs`
+ * scans every package for the pairing and fails on a drift.
+ */
+/** One token value per palette mode; the host rejects a bare string. */
+export interface BrandTokenModes {
+    readonly light: string;
+    readonly dark: string;
+}
+/** Layer identity reported to `ctx.theme.overrideTokens` (one layer per source). */
+export declare const FT_BRAND_SOURCE = "@dsh-ft/dsh-fft-settings";
+/**
+ * The published brand colors.
+ *
+ * `accent` is the FT yellow used by this plugin's primary action and eyebrow;
+ * `accent-warm` is the orange trading accent shared by market and trade
+ * surfaces (it is the only palette-aware group); `wechat` is the enterprise-
+ * WeChat green the SSO card keeps as its identity. Inks are the text colors on
+ * those fills, and `-soft` is the tinted surface behind the accent.
+ */
+export declare const FT_BRAND_TOKENS: Readonly<Record<string, BrandTokenModes>>;
+/** The slice of the host theme service this layer uses. */
+export interface BrandThemeService {
+    overrideTokens(source: string, tokens: Readonly<Record<string, BrandTokenModes>>): () => void;
+}
+/** Scoped context delivered once the `theme` service is available. */
+export interface BrandThemeScope {
+    readonly theme: BrandThemeService;
+    effect(callback: () => () => void, label: string): void;
+}
+/** The slice of the client context this layer needs: a deferred service inject. */
+export interface BrandThemeContext {
+    inject(deps: readonly string[], callback: (scope: BrandThemeScope) => void): void;
+}
+/**
+ * Stack the brand layer once the host theme service exists.
+ *
+ * The deferred `inject` is deliberate: this plugin's declared client context
+ * names only the services its cards read, and a host without `theme` must
+ * still load the settings page — the CSS fallbacks then carry the colors.
+ * @param ctx - client context carrying the host theme service.
+ */
+export declare function applyBrandTokens(ctx: BrandThemeContext): void;

package/lib/brand.js

@@ -0,0 +1,50 @@
+/**
+ * FT brand tokens published as a host theme override layer.
+ *
+ * The layer only *adds* brand variables on `body`; it never overrides a
+ * `--dsw-alias-*` value, so host chrome keeps its own palette and any user
+ * theme keeps working underneath. Consumers read `var(--ft-*)` with the same
+ * value as their fallback: the layer is a convenience, not a dependency, so
+ * every sub-plugin keeps its brand colors when this plugin is absent (or when
+ * the host has no `theme` service at all). Scheme-invariant tokens repeat one
+ * value; palette-aware tokens spell both with `light-dark()`.
+ *
+ * Keep those fallbacks equal to {@link FT_BRAND_TOKENS}; `tests/brand.test.mjs`
+ * scans every package for the pairing and fails on a drift.
+ */
+/** One value for both palettes: brand fills are scheme-invariant. */
+const invariant = (value) => ({ light: value, dark: value });
+/** Layer identity reported to `ctx.theme.overrideTokens` (one layer per source). */
+export const FT_BRAND_SOURCE = '@dsh-ft/dsh-fft-settings';
+/**
+ * The published brand colors.
+ *
+ * `accent` is the FT yellow used by this plugin's primary action and eyebrow;
+ * `accent-warm` is the orange trading accent shared by market and trade
+ * surfaces (it is the only palette-aware group); `wechat` is the enterprise-
+ * WeChat green the SSO card keeps as its identity. Inks are the text colors on
+ * those fills, and `-soft` is the tinted surface behind the accent.
+ */
+export const FT_BRAND_TOKENS = Object.freeze({
+    '--ft-accent': invariant('#f0c433'),
+    '--ft-accent-ink': invariant('#171717'),
+    '--ft-accent-warm': { light: '#cf5623', dark: '#ff8352' },
+    '--ft-accent-warm-hover': { light: '#b8481b', dark: '#ff9a72' },
+    '--ft-accent-warm-ink': { light: '#ffffff', dark: '#1a120e' },
+    '--ft-accent-warm-soft': { light: '#fbeee8', dark: '#2b1d16' },
+    '--ft-wechat': invariant('#2ebd68'),
+    '--ft-wechat-ink': invariant('#102419'),
+});
+/**
+ * Stack the brand layer once the host theme service exists.
+ *
+ * The deferred `inject` is deliberate: this plugin's declared client context
+ * names only the services its cards read, and a host without `theme` must
+ * still load the settings page — the CSS fallbacks then carry the colors.
+ * @param ctx - client context carrying the host theme service.
+ */
+export function applyBrandTokens(ctx) {
+    ctx.inject(['theme'], (scope) => {
+        scope.effect(() => scope.theme.overrideTokens(FT_BRAND_SOURCE, FT_BRAND_TOKENS), 'ft-settings: FT brand tokens');
+    });
+}

package/lib/client.d.ts

@@ -0,0 +1,8 @@
+import { type ApiKeyCardContext } from './features/api-key/card.js';
+export * from './core/shell.js';
+/** Browser context this plugin's own client half requires. */
+export type FtshareSettingsClientContext = ApiKeyCardContext;
+export declare const inject: string[];
+export declare function apply(ctx: FtshareSettingsClientContext): void;
+/** Contribute the section shell, then the built-in cards through the slot it declares. */
+export declare function registerFtshareSettings(ctx: FtshareSettingsClientContext): void;