# 第一版规划

更新日期：2026-09-12。本轮根据用户提供的真实 ERP、deepseek-flash 和 Read only 约束，交付 `0.1.0-alpha.2` SCM/USA 只读预览版。新增固定查询适配、菜单导入、学习任务持久化与商品链复用。原完整愿景仍保留，未完成项不通过改名视作完成；具体 M1–M5 处置见 [本版验收](assessments/2026-09-12-v1-acceptance.md)，操作说明见 [只读版](scm-readonly.md)。

目标宿主：**dsh 0.1.5 rc2**，官方标签 [`dsh-v0.1.5-rc.2`](https://github.com/deepseek-ai/deepseek-harness/tree/dsh-v0.1.5-rc.2)。运行时基线：**Node.js 24 LTS**。

本文定义产品成果、交付范围、验收及技术基线。[学习模型](learning-model.md) 是模型、状态与探索协议的唯一详细定义；[ADR 0001](adr/0001-local-first-ai-erp.md) 记录本地技术决策，[ADR 0002](adr/0002-menu-first-domain-learning.md) 记录菜单认知先行的学习决策。

## 1. 产品目标与原则

**先形成基于菜单的全局认知，再根据页面证据形成业务域认知，建立双向关联，最后在选定领域积累可执行能力。**

用户本机启动 dsh、安装插件并登录 ERP 后，可以查看系统结构、理解业务概念、追溯依据、纠正知识，并由 AI 辅助查询和受控操作。

- **效果第一**：实际认知正确性、任务完成质量和恢复能力优先于语言统一、依赖数量与成本。
- **信任 AI**：自主探索、解释、关联、纠错和生成方法，不预写每个 ERP 流程，不逐条询问所有字段。
- **单机易用**：允许包体较大，依赖由插件准备；用户不部署数据库、容器或浏览器服务。
- **写入固定确认**：对每次具体 ERP 业务变更确认，AI 自主完成批准范围内的步骤；内部学习自动积累。

全局探索是首次接入的默认起点，任务驱动决定后续纵深优先级。全局指当前企业、账号、角色可见范围，不等于 ERP 所有权限和数据状态的功能全集。

## 2. 第一版范围与第一步成果

首版范围为：**一个 ERP、一个角色，全局广度探索＋一个业务域深度验证**。

- 全局完成 L1 一级入口和 L2 功能结构的本轮扫描，阻塞和未覆盖范围明确保留。
- 基于页面证据形成初步业务域框架，并与菜单、页面建立多对多映射。
- 选择采购或库存等一个业务域完成 L3 页面细节和指定 L4 行为验证，跨域发现回填全局框架。
- 本次交付可复用只读查询；测试环境业务写入延期，维持未来每次具体变更固定确认的原则。

**第一个产品里程碑**：安装并登录后，用户能看到当前角色的全局菜单地图和初步业务域框架，从业务概念返回菜单入口、页面及证据，并明确知道哪些部分尚未验证。

这一步不以完成写入自动化或探索所有按钮为条件。用户随时查看部分成果、暂停或插入任务；未完成的全局轮次保持可恢复，不因局部查询成功而标记全局学习完成。

不承诺全角色自动探索、完整枚举和状态机推导、任意 ERP 的可靠写入。真实支付和外部交易不纳入验证，写入使用测试环境与测试数据。

## 3. 用户流程与学习成果

`安装 → 登录并确认观察范围 → 全局菜单探索 → 综合业务域认知与关联 → 选择领域深入 → 复用能力并持续更新`

菜单认知回答功能在哪里、界面呈现什么；业务域认知回答对象、关系与规则；能力定义回答如何执行与核验。三者保持独立身份，以证据和版本关联，模型细节统一见 [学习模型](learning-model.md)。

用户首先得到菜单地图、业务域视图、双向入口、证据与缺口清单。后续得到字段说明、操作目录和能力目录。它们来自同一批结构化记录，可阅读、纠正和导出，不是分别维护的文档副本。

探索分四层：全局入口、功能结构、页面细节、业务行为。先广后深，每轮先记录结构和页面证据，再更新业务理解。达到预算、用户接管或出现未知副作用时暂停；停止条件、去重和状态定义见学习协议。

## 4. 交付阶段

| 阶段 | 交付 | 完成条件 |
| --- | --- | --- |
| M0 技术可行性 | 目标宿主插件加载、模型与审批接入、本机浏览器、存储和执行器对照 | Node 24 与真实接口验证通过，保留失败记录并确定主执行方式 |
| M1 全局认知 | L1/L2 菜单地图、初步业务域框架、双向关联、证据和缺口 | 各已发现分支完成本轮观察或明确阻塞；可以回答系统结构与跨菜单关联问题 |
| M2 领域深入 | 一个业务域的 L3 字段、Tab、按钮、子窗口与业务解释 | 证据可追溯、未知与冲突可见；深度探索能修订全局映射 |
| M3 查询能力 | 参数化查询契约、执行方法、结果核验与复用记录 | 重复任务利用已有知识；页面变化后发现失效并修复，未把一次偶然成功当成稳定能力 |
| M4 测试写入（本次延期） | 只读版不注册业务写入能力 | 真实写入与回读未执行；原验收保留为后续任务，不标通过 |
| M5 单机发布 | 支持平台的安装与升级路径 | 干净环境安装、启动、登录、重启、升级、失败恢复和卸载数据选择通过 |

从 M0 开始验证安装和生命周期，不将它们全部推迟到发布末尾。M1 是首个产品价值节点，M2 至 M4 是首版深度能力范围。

首个贯穿案例：安装 → 登录 → 全局菜单元数据地图 → 业务域及入口关联 → 商品/库存/采购/销售查询与知识修订 → 重复及空查询 → 中断恢复；测试写入另行验收。

## 5. 验收与效果评估

### 认知成果

| 验收问题 | 需要观察的结果 |
| --- | --- |
| 系统有哪些主要功能，入口在哪里？ | 返回当前角色菜单结构与真实入口，注明范围、缺口和阻塞 |
| 采购相关功能分散在哪些菜单？ | 根据证据指出跨菜单关联，不把一级菜单直接等同于业务域 |
| 为什么认为这个字段表示某个业务含义？ | 返回页面观察或其他依据，区分推断、确认和冲突 |
| 哪些业务关系尚未确认？ | 显示具体命题、缺少的证据与下一步探索方向 |
| 菜单移动后知识是否仍可使用？ | 保留有效业务理解，更新入口，相关能力需复核且能修复 |
| 找到按钮后是否宣称学会操作？ | 明确区分发现、观察、解释和指定条件下的验证 |

结构覆盖采用当前发现范围，配合人工维护的独立菜单清单抽查漏项。语义与行为覆盖分别报告，不能用一个总体百分比掩盖未验证关系。具体状态及统计口径引用学习模型，不在此重复定义。

### 对照实验

用相同角色、业务数据、后续任务集和模型配置，比较“菜单全局探索后执行”与“仅按局部任务探索”的结果。前者是产品默认策略，后者是评估对照，不作为并行生产产品。重点记录遗漏、错误关联、首次和重复任务正确率、恢复、人工介入，以及首次建图和后续调用的总时间与成本。

浏览器选型同样基于重复任务比较 Node 方案和 browser-use。先固定模型比较执行方案，再测试模型变化；无法对齐的条件明确披露。不得只报告成功案例或用上游通用基准替代目标 ERP。

测试覆盖导航别名、复杂筛选、分页、弹窗、表格、跨页面关联、中文语义召回、菜单移动、字段变化、权限变化、暂停和恢复。总体门槛按首批测试建立基线后确定；未授权业务写入属于发布阻断问题。

### 安装与恢复

支持平台的干净环境仅预装 Node 24 和目标 dsh，不安装 Python、PostgreSQL、Docker 或编译工具。插件自动准备资源、给出可恢复的错误和必要配置入口。升级保留知识与浏览器配置，重启重新检查登录和未完成业务动作，卸载明确选择是否删除数据。

## 6. 技术基线与实现边界

已核对目标标签的官方架构、模型服务、工具管线及 Schema 文档。存在接口依据不等于实际插件已兼容、审批已覆盖或任务可跨进程恢复；M0 必须验证。

| 部分 | 决定 |
| --- | --- |
| 宿主 | dsh 原生插件，复用模型配置、代理循环、工具执行管线、审批和会话；首版不另套 MCP 或 LangGraph |
| 运行时与语言 | Node 24 LTS、TypeScript；发布 JavaScript，固定经验证版本并跟进安全更新 |
| 执行进程 | 插件托管本地 Node 工作进程，IPC 或 stdio 通信；无需额外 HTTP 服务和固定端口 |
| 浏览器 | Playwright 1.63.0 已实现专用会话和被动观察基础；固定 SCM 只读 API 适配已实现；通用浏览器动作仍关闭。见 [当前浏览器边界](browser-observation.md) |
| 数据 | SQLite 已选定 node:sqlite，由独立存储线程拥有；观察/检查点基础已实现，后续保存菜单、领域、映射、能力、版本和业务核验状态；不修改 dsh 内部数据库 |
| 文档与证据 | 本地文件；结构化记录为权威来源，生成视图和可重建检索 |
| 契约 | 固定工具优先原生 Schema，动态知识用可序列化定义；Zod 为按需内部校验，不重复维护两份工具契约 |
| 界面 | dsh 中展示知识与确认，本机 Chromium 窗口用于登录和接管；内嵌画面后续增强 |

dsh 管理主代理与对话历史，插件仅管理自己的学习和业务状态。模型与审批留在宿主侧，工作进程提交观察与执行结果，不复制凭据。浏览器适配只统一观察、受控操作、会话、接管和核验，不复制所有上游 API。

### 效果优先的执行器选择

Node 是唯一主开发路线，browser-use 是效果对照。Playwright 不等于完整浏览器智能；browser-harness 提供连接与经验复用参考；browser-harness-js 当前使用 Bun 且以 CDP 为主；Stagehand 为候选，其本地运行、模型适配和授权控制需按所选版本验证。

若实测证明成熟 Python 方案在关键任务持续明显领先，而补齐差距需要重建复杂能力，可以随插件管理 Python 执行器；记录证据、审批覆盖、安装和维护成本，不让用户管理运行时，不同时建设两套生产执行器。例外规则见 ADR 0001。

### 本地存储与发布

- SQLite 由单一存储线程协调，短事务，已验证并启用 WAL；连接排他锁阻止第二个所有者。等待浏览器、模型或用户时不持有应用事务，执行进程取消不终止存储线程，详见 [存储实现与验证](storage.md)。
- 使用一致性备份接口或受控关闭后的备份，不能遗漏活动 WAL；数据库不放网络共享或同步目录。
- 截图等存文件，数据库保存引用；升级前备份和验证迁移，失败保留原数据，不承诺任意降级可读。
- 本次查阅的 Node 24 文档将 node:sqlite 标记为 Release candidate，验证具体版本的事务、全文、备份和迁移；耗时查询离开宿主交互路径。
- 初期用别名、全文和关系检索，中文召回不足时增加本地语义索引，不增加独立图谱或向量服务；索引关联知识及模型版本。
- 发布锁定依赖与预构建代码，浏览器资源随包或自动准备，提供进度、完整性校验和重试；确定支持的平台与架构。
- 安装和启动检查实际 Node 版本，不只依赖 engines；桌面宿主内嵌运行时需单独验证，不声称所有发行方式兼容。
- 安装目录与用户数据分离，退出或禁用停止任务并清理工作进程，升级保留数据。

## 7. 登录、授权与真实结果

创建专用本机浏览器配置后暂停代理，由用户完成账号或扫码登录，核对企业和角色再开启全局探索。扫码依赖 ERP 自身支持，人工与代理互斥控制。首版不要求 iframe 或云浏览器，企业代理与证书环境在支持范围内验证。

登录态不进入知识文档，证据按需脱敏，不默认全量录制；检索与会话遵守企业、角色和权限范围。本地存储不等于离线模型，使用远程模型时说明页面内容的使用范围。

写入流程保持：**具体变更计划 → 用户确认 → 重新校验 → 执行必要步骤 → 回读核验 → 记录结果**。

确认卡展示企业、对象、操作、前后值、影响范围和已知副作用。批准针对业务变更而非每次点击；新增对象、改变值、扩大范围或授权过期需要重新确认。模型不能自行批准，重启不能仅凭历史聊天中的同意恢复授权。

观察按钮不等于执行按钮。自动保存或打开即创建对象需在首次可能写入前确认，HTTP 方法不能代替业务读写判断。所有允许的代码、网络和浏览器操作路径必须经过授权检查；未知且可能有副作用的动作暂停，不为覆盖率冒险执行。初次探索优先只读权限。

恢复后核对浏览器、登录、企业、对象和关键数据；提交超时进入结果待核验，回查 ERP 后再决定后续动作，不盲目重试。会话持久化不保证 ERP 业务 exactly-once；利用业务唯一标识或幂等机制，仍不明确时交由用户处理。生成能力和通过 Schema 校验都不等于获得写入授权。

## 8. 待验证事项与资料

M0 需明确实际插件打包、模型与审批接口、Node 24 兼容性、浏览器方案和执行路径；M1 前确定首个 ERP、可见角色及独立菜单抽查清单；M2 至 M4 确定深度业务域、期望结果和测试数据；M5 验证平台、分发、存储迁移、网络环境和依赖许可证。

这些是实施关口，不重新开放已确认技术基线为多套并行方案。各阶段记录已验证、未验证和阻塞事项，不提前声称实现完成。

资料随上游版本变化，实际实施按锁定版本复核：

- [dsh 架构](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.5-rc.2/docs/architecture.md)、[工具管线](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.5-rc.2/docs/tool-execution-pipeline.md)、[模型服务](https://github.com/deepseek-ai/deepseek-harness/blob/dsh-v0.1.5-rc.2/packages/llm/llm/README.md)
- [Node 版本状态](https://nodejs.org/en/about/previous-releases)、[Node 24 SQLite](https://nodejs.org/download/release/latest-v24.x/docs/api/sqlite.html)
- [SQLite 适用场景](https://www.sqlite.org/whentouse.html)、[WAL](https://www.sqlite.org/wal.html)、[FTS5](https://www.sqlite.org/fts5.html)
- [Playwright Library](https://playwright.dev/docs/library)、[浏览器分发](https://playwright.dev/docs/browsers)
- [browser-use](https://github.com/browser-use/browser-use)、[browser-harness](https://github.com/browser-use/browser-harness)、[browser-harness-js](https://github.com/browser-use/browser-harness-js)、[Stagehand](https://github.com/browserbase/stagehand)
- [MDN 同源策略](https://developer.mozilla.org/en-US/docs/Web/Security/Defenses/Same-origin_policy)
- Schema 与能力生成的方法参考统一见 [学习模型](learning-model.md)。