init

2026-08-29 16:20:33 +08:00
commit cba31428dc
52 changed files with 6553 additions and 0 deletions
@@ -0,0 +1,171 @@
+# 迭代 01 实施步骤规划（分步执行）
+
+> 2026-08-27 ｜ 按步骤分批推进，每步有独立产出与验证点
+> 关联：技术实现方案.md、程序结构设计.md
+
+## 总览
+
+| 步骤 | 内容 | 产出 | 验证点 | 依赖 |
+|---|---|---|---|---|
+| S1 | 插件骨架 | package.json + 目录 + 空 apply | 包可被识别 | - |
+| S2 | 数据源适配 | qmt-bridge-rest.js（REST 直连） | fetch QMT 返回真实数据 | S1 |
+| S3 | 设置管理 | settings.js（策略注册） | 设置中出现策略配置 | S1 |
+| S4 | 本地存储 | storage.js（allocations.json） | 读写持久化 | S1 |
+| S5 | 分仓逻辑 | manager.js（份额分配/聚合） | 单元验证分仓计算 | S2+S4 |
+| S6 | 服务端 RPC API | api.js（connection.rpc） | RPC 端点可调用 | S2+S3+S5 |
+| S7 | 客户端 tab | client/（conversation.view 注册） | tab 出现在对话/轨迹/上下文后 | S3+S6 |
+| S8 | 宿主挂载+联调 | cordis.patch.yml + 安装 | 全链路可用 + 验收 | S1-S7 |
+
+## 分步细节
+
+### S1：插件骨架
+- package.json：name/version/main/files + `dsh.client` 声明（web 平台）
+- 目录：src/、lib/、src/data-source/、src/position/、src/client/
+- src/index.js：apply(ctx) 空实现 + name/inject/apply 导出
+- **验证**：node 语法检查 + 包结构完整
+
+### S2：数据源适配（qmt-bridge-rest.js）
+- src/data-source/types.js：统一数据模型（Position/AssetSummary/DataSource 接口）
+- src/data-source/qmt-bridge-rest.js：
+  - baseUrl 配置（默认 http://192.168.3.43:8610）
+  - getPositions() / getAsset() / health()
+  - 字段映射（语义字段优先，m_ 回退）
+- **验证**：独立脚本调用，返回真实持仓/资金数据（对齐快照）
+
+### S3：设置管理（settings.js）
+- ctx.settings.register('one-divine-lot', schema)
+- 策略 schema：strategies: [{id, name, visible, order}]
+- 预置：网格超市、手动做T
+- **验证**：settings 可读取默认策略；更新后值变化
+
+### S4：本地存储（storage.js）
+- 路径：~/.dsh/one-divine-lot/allocations.json
+- load()/save()/get()/set()
+- 原子写（临时文件+rename）
+- **验证**：写入后文件存在，重启读回一致
+
+### S5：分仓逻辑（position/manager.js）
+- getAllPositions()：全量持仓
+- getStrategyPositions(strategyId)：按分配份额过滤
+- getSummary()：各策略份额/市值/盈亏 + 未分配
+- allocate()：份额分配（校验和 ≤ 总持仓）
+- **验证**：单元测试分仓计算（如 1000 股 → 网格 600 + 做T 400）
+
+### S6：服务端 RPC API（api.js）
+- ctx.connection.rpc.intercept('/api', matcher, handler)
+- 端点：strategies/positions/allocations/summary/strategy/:id/positions
+- **验证**：通过 DSH RPC 调用端点返回正确数据
+
+### S7：客户端 tab（client/）
+- client/index.js：读策略设置 → 注册 conversation.view entries
+- client/views/StrategyTab.jsx：渲染策略持仓（调 RPC API）
+- **验证**：tab 出现在对话/轨迹/上下文后，点击加载数据
+
+### S8：宿主挂载 + 联调验收
+- cordis.patch.yml insert 插件行
+- 插件安装到 profile（pnpm link 等）
+- 全链路验收（对照验收标准.md）
+
+## 建议执行批次
+
+- **批次 1（S1-S2）**：骨架 + 数据源 —— 打通「插件→QMT REST」数据读取（纯服务端，可独立验证）
+- **批次 2（S3-S5）**：设置 + 存储 + 分仓逻辑 —— 核心业务逻辑
+- **批次 3（S6）**：RPC API —— 打通「服务端能力 → DSH 通道」
+- **批次 4（S7-S8）**：客户端 tab + 宿主挂载 —— 全链路 UI 呈现
+
+## 前置技术确认（编码前）
+
+1. conversation.view 注册签名（读 dsh-client-ui-conversation slots.d.ts）
+2. 插件安装到 profile 的方式（pnpm link / 本地路径）
+3. settings 注册在 host plane 的注入方式（ctx.settings 是否对插件可用）
+
+## 执行进度（2026-08-27）
+
+### ✅ 批次 1-2（S1-S4）已完成
+
+| 步骤 | 状态 | 验证结果 |
+|---|---|---|
+| S1 插件骨架 | ✅ 完成 | package.json（dsh.client 声明）+ src/index.js 空入口，语法通过 |
+| S2 数据源适配 | ✅ 完成 | qmt-bridge-rest.js 真实调通 QMT REST：可用性✅、资金✅（总资产129,412.25）、持仓✅（12只，市值85,948） |
+| S3 设置管理 | ✅ 完成 | settings.js：默认策略（网格超市/手动做T）、可见过滤、排序，逻辑验证通过 |
+| S4 本地存储 | ✅ 完成 | storage.js：读写/持久化/覆盖/删除验证通过（1000股→网格600+做T400 校验通过） |
+
+### 产出文件
+- src/index.js（接入 S2-S4）
+- src/settings.js
+- src/storage.js
+- src/data-source/types.js
+- src/data-source/qmt-bridge-rest.js
+
+### 下一步（批次 2 剩余 / 批次 3）
+- S5 分仓逻辑（position/manager.js）
+- S6 服务端 RPC API（connection.rpc）
+- S7-S8 客户端 + 宿主挂载
+
+### ✅ S5 已完成（2026-08-27）
+
+| 项 | 结果 |
+|---|---|
+| S5 分仓逻辑 | ✅ 完成 position/manager.js：全量持仓/策略持仓/未分配/添加/移出/摘要 |
+| 验证 | ✅ 真实 QMT 数据：添加（600+400）、超限拦截（>1800拒绝）、移出（400→200）、移出超限拦截、摘要（份额汇总+未分配=1000）全部通过 |
+| 设计依据 | S5 讨论定稿（Q1股数/Q2允许未分配/Q3人为分组/Q4无统计/Q5策略tab内编辑） |
+
+### 待办（批次 3-4）
+- S6 服务端 RPC API（connection.rpc）
+- S7 客户端 tab（全部持仓/网格策略持仓/做T持仓）
+- S8 宿主挂载 + 联调验收
+
+### ✅ S6 已完成（2026-08-27）
+
+| 项 | 结果 |
+|---|---|
+| S6 服务端 RPC API | ✅ 完成 src/api.js：connection.rpc.intercept('/api') 暴露 8 个端点 |
+| 端点 | positions / strategies / strategy-positions / unallocated / summary / add-shares / remove-shares（+ 未知端点错误） |
+| 验证 | ✅ 全部端点回归通过；错误码精确（share-limit / share-exceed / unknown-endpoint） |
+| 模式 | 参照 dsh-api-gateway：intercept('/api', matcher, handler, {authority:'trusted-host'})，RpcResult 格式 {ok, value}/{ok:false, error} |
+
+### 待办（批次 4）
+- S7 客户端 tab（全部持仓/网格策略持仓/做T持仓）
+- S8 宿主挂载 + 联调验收
+
+### 🔄 S7 客户端 tab（部分完成，2026-08-27）
+
+**已完成**：
+- src/client/index.js：客户端插件入口（inject slots/connection，注册 3 个 conversation.view tab：全部持仓/网格策略持仓/做T持仓）
+- src/client/views/AllPositionsTab.jsx：全部持仓组件（全量+份额标注）
+- src/client/views/StrategyTab.jsx：策略持仓组件（添加/移出交互）
+- src/client/views/connection.js：RPC 调用 hook
+
+**待完成**：
+- 构建配置（tsdown/tsconfig + 客户端依赖安装）
+- 客户端 bundle 构建 + 语法/类型验证
+- 与宿主集成测试（S8 时统一）
+
+**关键约束**（S7 现实情况）：
+- 客户端插件需要 react/slots/runtime 等依赖（peerDependencies），需安装；
+- JSX 需要构建工具（tsdown）处理成浏览器 bundle；
+- 构建环境与宿主挂载（S8）联动，建议 S7+S8 一起验收；
+- 客户端代码的完整运行验证依赖 DSH web 宿主重启加载。
+
+### ✅ S7-S8 已完成（2026-08-28）
+
+| 项 | 状态 |
+|---|---|
+| S7 客户端 tab | ✅ 完成：全部持仓/网格策略持仓/做T持仓 三个 conversation.view tab |
+| S7 设置菜单 | ✅ 完成：settings.section「神之一手」（策略列表 + 显示开关） |
+| S8 宿主挂载 | ✅ 完成：插件 link 到 web profile + bundles 加入 + bundle patch 挂载 |
+| 客户端 bundle | ✅ __ModuleLoader__.load 包装（scripts/wrap-client.mjs） |
+| 服务端 API | ✅ webServer /odl/api/* 路由（8 端点）—— 修正：不用 RPC（与 api-gateway 冲突） |
+
+### 已解决的问题（实现过程中的关键坑）
+1. **RPC 冲突**：/api 通道只能一个 interceptor（api-gateway 占用）→ 改用 webServer 自开路由
+2. **slots.register 签名**：component 必须是第二参数 → React #130 崩溃
+3. **客户端 bundle 格式**：必须 __ModuleLoader__.load 包装
+4. **settings schema**：必须 schemastery z.object（函数式 schema）
+5. **endpoint 前缀**：客户端传 one-divine-lot/* 需剥离
+
+### 验证结果（2026-08-28，真实 QMT 数据）
+- positions/summary/strategies/add-shares/remove-shares 全部 HTTP 200
+- 12 只真实持仓显示正常（老师确认）
+- 份额添加/移除/持久化工作正常
+- 分仓存储文件 allocations.json 已创建
@@ -0,0 +1,116 @@
+# 技术实现方案：01-分仓管理工具（迭代设计 v2）
+
+## 一、技术选型
+
+| 项 | 选型 | 依据 |
+|---|---|---|
+| 数据源 | QMT Bridge **RESTful 接口**（http://192.168.3.43:8610，OpenAPI v3） | 技术约束-003（插件直连 REST，非 MCP） |
+| HTTP 客户端 | Node 内置 fetch（Node 22+） | 零依赖 |
+| 设置管理 | ctx.settings 注册 namespace | DSH 内置 settings 服务 |
+| 本地存储 | JSON 文件（~/.dsh/one-divine-lot/） | 分仓数据本地化 |
+| 客户端 UI | dsh.client 平台 + React 组件 | conversation.view 插槽扩展 tab 栏 |
+| 宿主集成 | cordis.patch.yml insert（web profile patch 层） | 外部插件挂载 |
+
+## 二、架构分层
+
+```
+[DSH 主窗口 conversation 区域]
+   └─ view tabs：对话 │ 轨迹 │ 上下文 │ ➕ 策略标签（网格超市 / 手动做T ...）
+        └─ 每个策略 tab = 一个 conversation.view 插槽 entry（ViewTab: id + label）
+             └─ 渲染组件：加载该策略下的持仓数据
+                    │  API 请求
+[DSH 宿主] ◀── cordis.patch.yml insert 挂载插件行
+   │
+[插件核心（apply ctx）]
+   ├─ settings：策略 CRUD + 显示开关（ctx.settings.register）
+   ├─ storage：策略配置 + 分仓数据 JSON 持久化
+   ├─ api：connection.rpc /api 通道端点（持仓、策略、分仓查询）
+   ├─ data-source：QmtBridgeRestDataSource（fetch REST）
+   └─ position：分仓逻辑（持仓 ↔ 策略份额分配）
+```
+
+## 三、模块详细设计
+
+### 模块 1：数据源适配器（QmtBridgeRestDataSource）
+- 基础地址：http://192.168.3.43:8610（插件配置项，可改）
+- 端点封装：
+  - getAsset() → GET /trade/asset（资金摘要）
+  - getPositions() → GET /trade/positions（全量持仓，含语义字段 stock_code/volume/available/avg_price/price/market_value/profit/profit_pct）
+  - getOrders() → GET /trade/orders（预留）
+  - getTrades() → GET /trade/trades（预留）
+  - health() → GET /health
+- 字段映射：优先语义字段（stock_code 等），回退 m_ 原始字段
+- 统一返回 Position[] / AssetSummary（技术约束-001）
+
+### 模块 2：设置管理（策略=标签）
+- ctx.settings.register('one-divine-lot', schema)
+- schema 字段：
+  - strategies: array of { id, name, visible(默认true), order }
+  - 初始预置：网格超市、手动做T（老师可改）
+- 用户经 DSH 设置界面维护：增/删/改策略、显示隐藏开关、排序
+
+### 模块 3：分仓数据存储（本地）
+- 文件：~/.dsh/one-divine-lot/allocations.json
+- 结构：{ [positionCode]: { [strategyId]: shares } }
+  - 示例：{ "600719.SH": { "grid-supermarket": 1000, "manual-t": 800 } }
+- 约束：各策略份额之和 ≤ 总持仓（允许未分配余量）
+- API：读/写分仓分配（服务端存储，QMT 只提供全量持仓）
+
+### 模块 4：客户端 tab 栏（conversation.view 扩展）
+- package.json 声明 dsh.client（web 平台）
+- 客户端插件注册 conversation.view entries：
+  - 读取设置中 visible=true 的策略，每个策略注册一个 ViewTab
+  - 注册在既有 tab（对话/轨迹/上下文）之后
+- 每个策略 tab 渲染：
+  - 该策略下持仓列表（从服务端 API 获取）
+  - 展示：代码/名称/份额/市值/盈亏
+  - 未分配持仓展示在「未分配」区域
+- 显示/隐藏：设置变更 → 重新注册/注销 view entry（或按 visible 过滤渲染）
+
+### 模块 5：服务端 API（供客户端，RPC 通道）
+
+> 修正：使用 DSH 原生 RPC（connection.rpc），不自开 HTTP 路由。
+
+- `ctx.connection.rpc.intercept('/api', matcher, handler, {authority:'trusted-host'})`
+- 端点：
+  - `one-divine-lot/strategies` → 策略列表（含 visible）
+  - `one-divine-lot/positions` → 全量持仓（QMT）
+  - `one-divine-lot/allocations` → 分仓分配
+  - `one-divine-lot/allocations/update` → 更新分仓分配（份额设置，二期）
+  - `one-divine-lot/strategy/:id/positions` → 某策略下的持仓汇总
+
+## 四、宿主挂载
+
+- 修改 ~/.dsh/profiles/web/cordis.patch.yml，insert 插件行：
+```yaml
+- insert:
+    - id: one-divine-lot
+      name: "one-divine-lot"   # 插件包名（本地安装或 link）
+      config: { ... }
+```
+- 插件包需在 profile 的 node_modules 中可用（pnpm link / 本地安装）
+- 遵循 editing-cordis-compositions：不改 shipped preset，走用户 profile patch 层
+
+## 五、实现步骤
+
+1. **服务端骨架**：插件包结构 + package.json（dsh.client 声明）+ apply(ctx) 入口
+2. **数据源适配**：QmtBridgeRestDataSource（REST 直连，字段映射）
+3. **设置管理**：ctx.settings.register（策略 schema）
+4. **存储**：allocations.json 读写
+5. **服务端 API**：connection.rpc.intercept('/api') 端点（策略/持仓/分仓）
+6. **客户端插件**：conversation.view entries 注册 + 策略持仓渲染组件
+7. **宿主挂载**：cordis.patch.yml insert + 插件安装
+8. **验收**：设置→tab 显示→持仓加载→持久化
+
+## 六、涉及设计约束
+
+- 技术约束-001（统一数据源抽象）/ 003（REST 直连）
+- 产品约束-001（全量持仓）/ 002（标签体系）/ 003（标签自定义+显示开关）
+
+## 七、风险与开放项
+
+1. conversation.view 插槽注册的精确 API（register 签名）需在实现时读取 slots.d.ts 确认；
+2. ~~服务端 API 与客户端通信：走 DSH webServer 标准路由~~ → 已确认走 DSH 原生 RPC 通道（connection.rpc.intercept）；
+3. 策略 tab 的渲染组件挂载到 conversation.view 后，其数据刷新时机（实时/手动/切换时）；
+4. 分仓份额编辑入口：设置界面 or tab 内直接编辑（先做 tab 内只读展示，编辑入口二期）；
+5. 插件本地安装方式：pnpm link 到 profile node_modules（需确认 profile 的包管理方式）。
@@ -0,0 +1,42 @@
+# 数据快照：QMT 账户资金与持仓（验证用）
+
+> 生成时间：2026-08-27 ｜ 用途：验证 QMT Bridge MCP 数据连通（迭代 01）
+> 数据来源：QMT Bridge MCP（qmt_asset / qmt_positions）
+> 注意：此为验证时刻的快照，非实时数据；仅作迭代验收与复盘参照。
+
+## 账户资金摘要
+
+| 字段 | 值 |
+|---|---|
+| 账户 | 8882874667 |
+| 状态 | 登录成功 |
+| 交易日 | 20260827 |
+| 总资产 | 129,166.25 |
+| 可用资金 | 43,460.25 |
+| 股票市值 | 85,702.00 |
+| 持仓盈亏（浮动） | -10,057.60 |
+| 账户余额 | 129,166.25 |
+
+## 持仓明细（12 只）
+
+| 代码 | 名称 | 数量 | 可用 | 均价 | 现价 | 市值 | 盈亏 | 盈亏% |
+|---|---|---|---|---|---|---|---|---|
+| 600719.SH | 大连热电 | 1800 | 1800 | 7.233 | 7.07 | 12,726 | -54 | -0.41% |
+| 601117.SH | 中国化学 | 600 | 600 | 8.293 | 7.54 | 4,524 | -24 | -0.48% |
+| 603028.SH | 赛福天 | 800 | 800 | 8.233 | 7.01 | 5,608 | -72 | -1.09% |
+| 001330.SZ | 博纳影业 | 1200 | 1200 | 6.696 | 5.07 | 6,084 | -36 | -0.45% |
+| 002065.SZ | 东华软件 | 800 | 800 | 7.376 | 6.90 | 5,520 | +8 | +0.14% |
+| 002135.SZ | 东南网架 | 1000 | 1000 | 7.491 | 6.72 | 6,720 | +160 | +2.14% |
+| 002339.SZ | 积成电子 | 800 | 800 | 8.463 | 7.42 | 5,936 | 0 | 0.00% |
+| 002347.SZ | 泰尔股份 | 1000 | 1000 | 7.503 | 6.06 | 6,060 | +20 | +0.27% |
+| 002478.SZ | 常宝股份 | 800 | 800 | 7.892 | 6.82 | 5,456 | +8 | +0.13% |
+| 300008.SZ | 天海防务 | 1200 | 1200 | 7.481 | 6.19 | 7,428 | +12 | +0.13% |
+| 300057.SZ | 万顺新材 | 2000 | 2000 | 6.881 | 6.69 | 13,380 | +240 | +1.74% |
+| 300426.SZ | 华智数媒 | 1000 | 1000 | 6.424 | 6.26 | 6,260 | -120 | -1.87% |
+
+## 汇总
+
+- 持仓数：12 只
+- 总市值：85,702.00
+- 总盈亏（浮动）：+142.00（个股浮动盈亏合计）
+- 备注：账户持仓盈亏 -10,057.60 与个股合计存在口径差异（账户级含其他因素），验收时以账户级为准
@@ -0,0 +1,191 @@
+# 程序结构设计：01-分仓管理工具
+
+> 迭代设计 v2 的程序结构细化 ｜ 2026-08-27
+
+## 一、整体目录结构
+
+```
+one_divine_lot/
+├── package.json              # 插件元数据 + dsh.client 声明（web 平台）
+├── src/                       # 源码（服务端 + 客户端）
+│   ├── index.js               # 插件入口：apply(ctx)，组装各模块
+│   ├── settings.js            # 设置管理：ctx.settings.register（策略 CRUD + 开关）
+│   ├── storage.js             # 本地存储：分仓分配 JSON 读写
+│   ├── api.js                 # 服务端 RPC API：connection.rpc.intercept('/api') 端点
+│   ├── data-source/
+│   │   ├── types.js           # 统一数据模型（Position / AssetSummary / DataSource 接口）
+│   │   └── qmt-bridge-rest.js # QMT Bridge REST 适配器（fetch 直连）
+│   ├── position/
+│   │   └── manager.js         # 分仓逻辑：持仓↔策略份额分配、聚合视图
+│   └── client/
+│       ├── index.js           # 客户端插件入口：注册 conversation.view entries
+│       └── views/
+│           ├── StrategyTab.jsx  # 策略标签 tab 组件（渲染该策略持仓）
+│           └── PositionList.jsx # 持仓列表子组件
+├── lib/                        # 构建输出（与 src 结构对应）
+│   ├── index.js
+│   ├── settings.js
+│   ├── storage.js
+│   ├── api.js
+│   ├── data-source/
+│   ├── position/
+│   └── client/                 # 客户端 bundle（浏览器端加载）
+└── docs/                       # 神之一手框架文档（既有）
+```
+
+## 二、模块职责与依赖
+
+### 1. index.js（插件入口）
+```js
+const name = 'one-divine-lot';
+const inject = ['tools', 'settings', 'webServer'];  // 依赖 DSH 服务
+async function apply(ctx, config) {
+  const settings = registerSettings(ctx);          // 设置管理
+  const storage = new Storage(config);             // 本地存储
+  const dataSource = new QmtBridgeRestDataSource(config);  // REST 数据源
+  const manager = new PositionManager({ dataSource, storage });  // 分仓逻辑
+  registerApi(ctx, manager);                       // 服务端 API
+  registerClient(ctx);                             // 客户端插件（dsh.client）
+  ctx.effect(() => () => { /* 清理 */ });
+}
+export { name, inject, apply };
+```
+
+### 2. settings.js（设置管理）
+- `ctx.settings.register('one-divine-lot', schema)`
+- schema：strategies: array[{ id, name, visible, order }]
+- 预置：网格超市、手动做T
+- 提供 getStrategies() / watchStrategies()（客户端 API 读取）
+
+### 3. storage.js（本地存储）
+- 路径：`~/.dsh/one-divine-lot/allocations.json`
+- 结构：`{ [positionCode]: { [strategyId]: shares } }`
+- API：load() / save() / get(code) / set(code, strategyShares)
+
+### 4. data-source/qmt-bridge-rest.js（REST 数据源）
+- baseUrl：http://192.168.3.43:8610（config 可配）
+- getPositions() → GET /trade/positions → Position[]
+- getAsset() → GET /trade/asset → AssetSummary
+- 字段映射：语义字段优先，m_ 回退（技术约束-001/003）
+
+### 5. position/manager.js（分仓逻辑）
+
+> 2026-08-27 S5 讨论定稿：
+> - Q1 按股数分配；Q2 允许未分配余额（sum ≤ 总持仓）；Q3 策略仅为人为分组（无策略逻辑）；
+> - Q4 不做统计（无市值/盈亏/占比聚合）；Q5 UI = 策略 tab 内编辑（添加默认0起填 + 指定数量移出）。
+
+- getAllPositions()：全量持仓（QMT，真实数据）
+- getPosition(code)：单只持仓
+- getStrategyPositions(strategyId)：某策略下的持仓（读分配份额，过滤出份额>0的标的）
+- getUnallocated()：未分配持仓（总持仓 - 各策略份额之和 > 0 的标的）
+- addToStrategy(code, strategyId, shares)：添加到策略（**份额从0起填**，更新该策略份额，并刷新已分配）
+- removeFromStrategy(code, strategyId, shares)：从策略移出（**指定数量**，份额减少，回到未分配）
+- getSummary()：返回 { 全部持仓, 各策略份额, 已分配合计, 未分配 }（仅份额，无统计）
+- 校验：单策略份额 ≤ 总持仓；已分配合计 ≤ 总持仓（允许未分配余量）
+
+### 6. api.js（服务端 RPC API —— DSH 原生通道）
+
+> **修正（2026-08-27）**：使用 DSH 原生 RPC（connection.rpc.intercept('/api')），不自开 HTTP 路由。
+
+```js
+ctx.inject(['connection'], (connectionCtx) => {
+  connectionCtx.connection.rpc.intercept('/api', matcher, handler, { authority: 'trusted-host' })
+})
+```
+
+- 端点（endpoint 命名，channel 相对路径）：
+  - `one-divine-lot/strategies` → 策略列表（含 visible）
+  - `one-divine-lot/positions` → 全量持仓（QMT）
+  - `one-divine-lot/allocations` → 分仓分配
+  - `one-divine-lot/summary` → 分仓聚合视图
+  - `one-divine-lot/strategy/:id/positions` → 某策略持仓
+- 职责：接收 DSH RPC 请求 → 调 manager/data-source（统一接口）→ 返回数据
+- **不是请求本身**：真正发 HTTP 到 QMT 的是 data-source/qmt-bridge-rest.js
+
+### 7. client/index.js（客户端插件）
+- package.json dsh.client 声明（web 平台）→ DSH clientModules 自动加载
+- **tab 结构（2026-08-27 Q5 确认）**：
+  - 全部持仓：显示全量真实持仓，已分配部分标注（网格 X / 做T Y / 未分配 Z）
+  - 网格策略持仓：初始为空，可从全部持仓添加
+  - 做T持仓：初始为空，可从全部持仓添加
+- 注册 conversation.view entries（在对话/轨迹/上下文之后）：
+```js
+ctx.slots.register('conversation.view', {
+  id: 'all-positions',
+  label: '全部持仓',
+  component: AllPositionsTab,
+})
+ctx.slots.register('conversation.view', {
+  id: 'strategy-grid',
+  label: '网格策略持仓',
+  component: StrategyTab,
+})
+ctx.slots.register('conversation.view', {
+  id: 'strategy-manual-t',
+  label: '做T持仓',
+  component: StrategyTab,
+})
+```
+- 策略持仓 tab 内编辑：添加（默认0起填）+ 移出（指定数量）
+
+### 8. client/views/StrategyTab.jsx
+- 挂载后从服务端 API 拉取该策略持仓
+- 渲染：策略下持仓列表（代码/名称/份额/市值/盈亏）
+- 展示未分配持仓区域
+- 数据刷新：切换 tab 时拉取（本期）
+
+## 三、职责边界（api.js vs qmt-bridge-rest.js）
+
+> 2026-08-27 老师提问澄清，明确两层职责：
+
+| 层 | 文件 | 职责 | 交互对象 |
+|---|---|---|---|
+| RPC 封装层 | api.js | 接收 DSH 请求，转发给业务层 | 浏览器客户端（DSH RPC 通道） |
+| 业务逻辑层 | position/manager.js | 分仓逻辑（份额分配/聚合） | 上层（api.js） |
+| 数据源适配层 | data-source/qmt-bridge-rest.js | **真正发 HTTP 请求到 QMT** + 字段映射 + 统一接口 | QMT Bridge REST |
+
+**调用链**：api.js → manager.js → qmt-bridge-rest.js → fetch → QMT REST
+**换数据源**：只替换 qmt-bridge-rest.js（统一接口不变，上层无感）—— 技术约束-001
+
+## 四、数据流
+
+```
+用户点击「网格策略持仓」tab
+  → 客户端 StrategyTab 挂载
+  → call('/api', 'one-divine-lot/strategy/grid-supermarket/positions')   // RPC 通道
+  → api.js handler 调 manager.getStrategyPositions(id)
+      → storage 读分配份额 + dataSource 读全量持仓
+      → 过滤出该策略份额>0的持仓
+  → RpcResult 返回 → 客户端渲染持仓列表
+
+用户添加份额（在网格 tab 操作）
+  → call('/api', 'one-divine-lot/allocations/add', { code, strategyId, shares })
+  → manager.addToStrategy(code, strategyId, shares)
+      → storage.set 更新份额（校验 ≤ 总持仓）
+  → 返回更新后的分配 → 客户端刷新
+```
+
+## 五、关键接口签名（待实现时对照类型确认）
+
+- `ctx.settings.register(ns, schema)` → SettingsScope（get/watch/update）
+- `webServer.register({kind:'http'|'upgrade', path, handler})` → disposer
+- `ctx.slots.register('conversation.view', {id, label, component})`（客户端，具体签名实现时读 slots.d.ts）
+- `dsh.client` 声明：`{ "dsh": { "client": { "platform": "web", "inject": [...] } } }`
+
+## 六、开发顺序（编码）
+
+1. package.json + 骨架目录
+2. data-source（REST 适配 + 类型）
+3. settings（策略注册）
+4. storage（分仓 JSON）
+5. position/manager（分仓逻辑）
+6. api（服务端路由）
+7. client（tab 注册 + 组件）
+8. 宿主挂载 + 联调验收
+
+## 七、非目标（本期不做）
+
+- 不做份额编辑 UI（二期）
+- 不做策略参数的完整管理（网格区间等，后续迭代）
+- 不做做T 记录
+- 不做风控引擎
@@ -0,0 +1,40 @@
+# 迭代复盘：01-分仓管理工具
+
+> 复盘日期：2026-08-28 ｜ 迭代状态：已完成（R-002 验收通过）
+
+## 迭代总结
+
+实现了「分仓管理工具」第一个可用版本：DSH 插件（独立挂载）+ 三个策略 tab（全部持仓/网格策略持仓/做T持仓）+ 设置菜单（神之一手）+ 份额分配本地管理 + 服务端 HTTP API。
+
+## 事实记录（做了什么）
+
+1. S1-S8 全部完成：插件骨架、数据源适配（QMT REST 直连）、设置管理、本地存储、分仓逻辑、服务端 API、客户端 tab、宿主挂载；
+2. 客户端 UI：三个 conversation.view tab + settings.section 设置菜单；
+3. 响应式布局：添加持仓组件支持宽/中/窄三种布局；
+4. 构建链路：tsdown 构建 + __ModuleLoader__ 包装脚本。
+
+## 经验教训（复盘沉淀）
+
+### 1. DSH 插件开发的「坑」（重要）
+- **RPC 通道冲突**：DSH 的 /api RPC 通道**只能一个 interceptor**（api-gateway 占用）—— 插件不能直接 intercept('/api')，应改用 **webServer 自开路由**；
+- **slots.register 签名**：component 必须是**第二参数**（register({...}, Component)），写在 options 里会导致 React #130 崩溃；
+- **客户端 bundle 格式**：必须 **window.__ModuleLoader__.load({id, factory})** 包装（CJS 格式），裸 ESM 无法加载；
+- **settings schema**：必须是 **schemastery z.object()**（函数式 schema），普通对象会报 "schema is not a function"；
+- **ctx 属性赋值**：Cordis 不允许直接给 ctx 设属性（ctx.xxx = ...），会报 "cannot set property without provide"。
+
+### 2. 插件安装与宿主集成
+- 用 **dsh plugin add**（而非 pnpm add）—— 它会自动 reconcile bundles；
+- 插件的 dsh.bundle.patch（cordis.patch.yml）**顶层必须是 insert 操作**，不是裸插件行；
+- 客户端插件需要 **exports["./client"]** 指向 bundle，且 bundle 必须 __ModuleLoader__ 包装；
+- 修改宿主配置（bundles/cordis.patch.yml）在 session workspace 外，需要沙箱升级 + 用户批准。
+
+### 3. 需求讨论的价值
+- 需求从「交易管理插件」→「智能交易辅助系统」→「分仓管理工具」多轮收敛；
+- 老师的关键输入：分仓=按策略（网格超市/手动做T）、份额拆分（1000股→网格600+做T400）、策略 tab 内编辑（添加/移出）、步进100+手动输入。
+
+## 下一步建议
+
+1. **WebSocket 数据监控**（老师已提）：插件可开启 WebSocket（webServer.registerUpgrade + ws 库），实现持仓/行情实时推送；
+2. **策略配置完整管理**：网格参数（区间/格距/档位）等；
+3. **做T 记录**：交易过程记录与复盘；
+4. **设计约束补充**：本次沉淀的 DSH 插件开发规范（RPC 冲突、ModuleLoader、slots 签名等）应写入技术方案约束，供后续迭代参考。
@@ -0,0 +1,21 @@
+# 迭代目标：01-分仓管理工具
+
+## 目标
+实现「分仓管理工具」第一个可用版本：DSH 插件设置管理（策略标签 + 显示开关）+ 主窗口 tab 栏展示策略标签 + QMT 全量持仓读取 + 本地存储。
+
+## 目标描述
+- 范围：只读（不下单）；核心是「策略=标签」的设置管理、tab 栏展示、数据本地化；
+- 要解决的问题：让老师在 DSH 中按策略（网格超市/手动做T 等）查看持仓，策略与分仓数据本地管理；
+- 引用需求：**R-002（已定稿，2026-08-27）**；
+- 实现方式：独立插件，外部挂载到 DSH 宿主。
+
+## 目标讨论过程
+- 2026-08-27 老师指令启动分仓管理工具（先验证 MCP/资金/持仓）；
+- 2026-08-27 多轮讨论收敛：分仓=按策略；策略=标签；标签=分仓；持仓份额可拆分（1000股→网格600+做T400）；
+- 2026-08-27 第 5 轮明确完整产品形态：设置管理 + 会话标签旁展示 + 本地存储；
+- 2026-08-27 第 6 轮定稿：标签展示在 DSH 主窗口上方 tab 栏（对话/轨迹/上下文后），独立插件外部挂载。
+
+## 对老师的配合需求
+- 确认 DSH 宿主 composition 修改许可（加载 client 插件需要改宿主）；
+- 提供 QMT 账户用途说明（模拟/实盘）；
+- 确认标签初始配置（网格超市、手动做T 是否预置）。
@@ -0,0 +1,34 @@
+# 验收标准：01-分仓管理工具
+
+## 验收标准线
+1. **设置管理**：DSH 设置中出现「神之一手」设置管理项，可添加/编辑/删除策略（标签），配置显示/隐藏开关；
+2. **tab 栏展示**：DSH 主窗口上方 tab 栏在「对话/轨迹/上下文」后出现策略标签，按设置显示/隐藏；
+3. **持仓数据加载**：每个策略标签下加载对应持仓数据（来自 QMT 全量持仓按策略归属过滤）；
+4. **本地存储**：策略配置与分仓数据持久化，DSH 重启后不丢失；
+5. **QMT 连通**：全量持仓读取正常（真实数据，账户 8882874667）。
+
+## 验收方法
+1. 实际操作 DSH 设置界面，验证策略 CRUD 与显示开关；
+2. 观察主窗口 tab 栏，验证策略标签位置（对话/轨迹/上下文后）与显示/隐藏；
+3. 点击各策略标签，核对持仓数据与 QMT 真实持仓一致；
+4. 重启 DSH，验证配置与分仓数据保留；
+5. 检查本地存储文件内容（JSON）。
+
+## 验收目标
+- 老师能在 DSH 设置中管理策略标签（含显示开关）；
+- 老师能在主窗口 tab 栏按策略查看持仓；
+- 分仓数据本地化，QMT 只作为全量持仓数据源。
+
+## 最终验收结果（2026-08-28 · 老师确认完成）
+
+| 验收项 | 结果 |
+|---|---|
+| 全部持仓显示 | ✅ 12 只真实持仓（QMT REST）显示正常 |
+| 三个策略 tab | ✅ 全部持仓/网格策略持仓/做T持仓（对话/轨迹/上下文后） |
+| 设置菜单「神之一手」 | ✅ 策略列表 + 显示开关 |
+| 份额编辑 | ✅ 添加/移出（步进100 + 手动输入任意值） |
+| 添加持仓组件 | ✅ 响应式布局（一行→按钮换行右对齐→每行两端对齐） |
+| 本地存储 | ✅ allocations.json 持久化 |
+| 服务端 API | ✅ /odl/api/* 8 端点全部工作 |
+
+**验收结论：R-002 完成（老师 2026-08-28 确认）**