English | 简体中文
dsh-automation-suite
DeepSeek Harness 的自动化发行版:一份 profile 蓝图 + 两个插件,让
dsh里的模型 能直接读写 TIA Portal V17 的 PLC 程序块,并以结构化、默认安全的方式操作 Git。An unofficial DeepSeek Harness distribution: a profile blueprint plus two plugins that give the model verified TIA Portal V17 Openness block access and a structured, guard-railed Git tool family.
⚠️ 非官方项目:与 DeepSeek(DeepSeek Harness 的发行方)无关,与 Siemens 也无隶属关系。
dsh-tool-git是上游lxj808624/dsh-tool-git的 vendor 副本(MIT),出处与差异见 §15。
目录
1. 这是什么
在 DSH 里,一个"发行版"不是单个包,而是两样东西的组合:
| 组成 | 在本仓里的位置 | 作用 |
|---|---|---|
| profile 蓝图 | profile/dsh-automation-suite/ |
声明"一个 profile 目录应该长什么样":装哪些 bundle、按什么顺序叠加 |
| 插件(bundle) | packages/* |
真正提供能力的模块,运行在 DSH 宿主进程里 |
蓝图不是 bundle,它要物化成 ~/.dsh/profiles/<name>/ 之后才被 dsh 当作 profile 使用。
本仓没有把发行版做成"一个巨型插件",而是做成可拆的组合:
- 想要整套 → 按蓝图物化 profile,一次拿到全部能力(§6);
- 只想要其中一个 →
packages/下的每个包都是可独立安装的 bundle,dsh plugin --profile <p> add <包名或 tarball>即可。
本仓是 Monorepo:packages/* 放插件,profile/* 放蓝图,scripts/ 放 Monorepo 级工具,
docs/* 放发行版层面的文档。
当前状态:这套方案的雏形。 仓库今天跑得通的是价值链条的第一层(把内容从工程软件里 取出来、写回去)以及管理层的一件通用工具(git);语义层尚未开始。分层方案、 每层的职责与已实现/规划中的边界,见 §2、
docs/vision.md与docs/roadmap.md。
2. 它要解决的问题
工业控制领域的 PLC 项目文件无法被 LLM 很好地访问、理解与操作:TIA Portal 的 .ap17、
以及各家的专有工程格式,把程序结构、调用关系与工程要素锁在专用工程软件里。文本模型
既读不到、也读不懂(没有结构化语义),更不敢改(改完无法验证是否成立)。
于是它在工控领域能提供的帮助极其有限。
打通这条链路要分层做,每一层解锁下一层:
| 层 | 要做什么 | 交给下一层什么 | 现状 |
|---|---|---|---|
| ① 接入层 打通工具障碍 |
通过工控软件预留的接口(TIA Openness 等)把程序源文件取出来、改完写回去 | 程序源文件(Simatic ML / SCL / STL) | 🟡 部分实现:TIA V17 的块读写、工程数据、PLC 对象增删改、F 相关与在线会话、下载与 UI 会话接管接口已接通(39 个工具);其中 v0.2 新增的 20 个操作待真机验证 |
| ② 语义层 让模型读懂 |
解析源文件、还原工程信息与要素,转换成 LLM 擅长处理的格式 | 可推理的工程上下文 | ⬜ 未实现:目前把 XML 原样交给模型 |
| ③ 管理与协作层 补齐软件短板 |
在工程软件预留的项目级接口之上,做它本身没有的能力 | 项目级工作流与建议 | 🟡 只有通用 git 工具,尚未与 PLC 项目打通 |
本发行版就是这条链路的载体:它由多个插件组成,每个插件负责其中一个方面。
层的划分与设计原则见 docs/vision.md,插件的职责边界与契约见
docs/architecture.md,逐项进度见 docs/roadmap.md。
目标插件构成
| 名称 | 对应层 | 负责什么 | 现状 |
|---|---|---|---|
| 工控软件接口插件族 (以 TIA 为例即 tia-openness;按软件版本分成员:V17/V18…;能力不拆包、由 preset 装配,见 D31) |
① 接入层 | 与工控软件对接、读写工程对象;为后续分析提供素材与验证工具;并附带文档说清每个能力"何时调用 / 怎么调用 / 调用后的数据怎么用" | 🟡 已有 V17(定位是验证基础功能) |
| 工程上下文插件 | 作用域(横向) | 管住用户的多个 TIA 项目 × 多个分支 × 多个历史版本;对工程对象做优化适配(路径内容、变更识别与跟进);用**「待办清单」式工具承载工程变更上下文**,在合适的时候交给 LLM 辅助判断用户意图;版本间变更明确易读、工程对象可交叉关联 | 🟡 部分实现(6 个工具:create_engineering_project / project_status / project_sync / project_commit + 只读的 workspace_describe(不打开 TIA 描述任意 workspace)与 import_preflight(导入前预检语言/依赖/同名);TIA → SOURCE 的 checksum+指纹同步已通,同步与提交分两步,151 项单测;DRAFT/REMOTE 与变更台账未做;已登记进蓝图,见 packages/dsh-engineering-context/docs/) |
| 工程知识图谱插件 | ② 语义层 | 准确翻译 XML 中的 PLC 语法(兼容性强):解析工程源文件 → 建立图数据库 → 暴露接口给出工程细节 | 🟡 部分实现(引擎 + 协议 + 8 个工具 + knowledgeGraph 服务,104 项单测;已登记进蓝图,并被族 2 的工作流调用) |
插件不再编号:只有接口插件族是"一族多成员"(成员 = 软件版本;能力不拆包,见 D31),工程上下文插件与
工程知识图谱插件都是单一插件。编号只保留给 docs/vision.md §3 的层
(① 接入层 / ② 语义层 / ③ 管理与协作层)。依赖关系与建议顺序见 docs/roadmap.md §5。
各插件的定位、期望与边界见 docs/architecture.md §4。
① 接入层:先打通工具层面的障碍
工控程序的一切都在专用软件里,所以第一步只能是用它自己预留的接口把内容取出来。 本仓已实现的一段是 TIA Portal V17 Openness:工程生命周期与工程数据、PLC 块/类型/标签表读写、 PLC 对象增删改、监视表与软件单元、F 相关服务、编译与关闭项目,且写入走白名单 + 事务 + 写后读回验证(细节见 §4.2)。 这一层的关键不是"能调通 API",而是把不可能暴露给模型的任意代码执行,压缩成一组数据化操作。
② 语义层:把工程信息还给它
导出物只是文件(XML、SCL、STL),不是工程语义。要让它对模型有用,还需要解析这些源文件、 还原出工程信息与要素 —— 块、块的调用关系、数据类型(UDT)、标签表、I/O、组层级 —— 再把它们转换成 LLM 擅长处理的格式(结构化、可导航、按需展开),而不是把几十 MB 的 XML 整个塞进上下文。这一层做完,模型才谈得上给出程序诊断、分析与编写方面的建议。
③ 管理与协作层:补齐软件短板,管好"在谈哪一版"
工程软件本身往往缺项目级能力,最典型的就是版本管理:TIA Portal 没有项目级 VCS,
而 .ap17 是二进制工程文件,直接丢进 git 只能得到"变了 / 没变"。可行的路子是
"导出为文本源 → 交给外部工具(git)做版本管理 → 需要时再导回",并让模型帮忙生成
有意义的差异说明与提交。
这一层还要回答一个更容易被忽略的问题:现在谈的是哪个项目的哪个分支的哪个版本。 一个用户的资产通常是"多项目 × 多分支 × 多版本",没有作用域,答案可能对、却对不上版本。 这条链路每一环都依赖前两层:没有①取不出文本、也写不回去;没有②得到的只是文本 diff 而不是工程变更(改了哪个块、影响了谁)。
今天已经能做什么
上面两层还在路上,但接入层这一段已经可用,配合管理层里的通用 git 工具, 今天就能完成下面两件事。
场景 A —— 用自然语言改 PLC 程序(TIA Portal V17)
工程师的日常是"打开项目 → 找到某个块 → 改一行 → 编译验证",这些动作要么在 TIA 界面里点, 要么写 Openness 脚本。本发行版把这条链路交给模型:
- 模型读:导出项目里的 PLC 块(Simatic ML XML,保留用户组目录层级),或只看块清单与元数据;
- 模型写:改 XML / 写 SCL 外部源,再导入回去,覆盖前先预演;
- 模型验:写后读回项目块集合逐个确认,再编译并读编译结果。
核心约束:不给模型"任意代码执行"。模型能表达的只有路径、块名、枚举这些数据, 真正执行的是固定白名单里的 5 个操作。
注意这一段的边界:模型今天拿到的是导出的文件本身,工程语义(调用关系、影响面、 标签与 I/O 的对应)还没有被还原出来 —— 那正是②语义层要补的。
场景 B —— 让模型安全地用 Git
模型写代码时高频要用 git,而原版运行时只有裸 bash:命令靠字符串拼、输出是给人看的散文、
push --force 和 reset --hard 没有任何闸门。本发行版补上 12 个结构化 git 工具
(shell-free、返回 JSON),并加一道 tools/pre-execute 闸门 —— 破坏性 git 操作
无论经插件工具还是经 shell 工具发起,默认都被拒绝并给出解释。
这是③管理层要用的通用底座:它现在与 PLC 项目还没有任何耦合,把它接上去需要先完成②。
已经解决的技术难题
| 难题 | 本发行版的解法 |
|---|---|
| Openness 只能被 .NET Framework x64 进程调用,Node 进程调不了 | 插件持有 C# 控制器子进程,用 NDJSON over stdio 通信 |
| Openness 对象非线程安全,一次只能有一个客户端 | 一个宿主进程只有一个控制器;跨会话请求在控制器内排队串行 |
| 写入失败必须保证项目不被写坏 | ExclusiveAccess + Transaction,全部成功才 CommitOnDispose(),否则 dispose 即回滚 |
| 模型可能调用破坏性 git 命令 | tools/pre-execute 策略闸门:deny(默认)/ ask / allow |
| 长操作可能卡死 | 每请求硬超时;超时终止控制器(Openness 不可取消),下次调用自动重启 |
当前进度与路线图
| 插件 | 目标 | 状态 |
|---|---|---|
| 工控软件接口插件族 | 把工控软件暴露的能力整体变成 LLM 的能力范围(含配套文档) | 🟡 V17(块·UDT·标签表);在线/硬件组态等更多能力与 V18+ 待补(不拆包,由 preset 装配,D31)。多成员形态已定:一族多包、插件页 bundle 开关激活、同一时刻只激活一个、切换后重启客户端(D36,落地清单见 docs/tia-version-members.md) |
| 工程上下文插件 | 管住"现在谈的是哪个工程、它在 workspace 的哪里、它和 TIA 是否一致" | 🟡 部分实现:6 个工具(151 项单测)—— create_engineering_project 把 TIA 工程接进 workspace(按 source_project 的类型打开 .ap17 或取回 .zap17,解包到 tia/)、读源文件树、经【缝 B】逐设备触发知识图谱建库;project_status 只读账本/清单/git/锁并给出下一步;project_sync 用 PLC checksum 快路径 + 逐对象指纹/归一化哈希慢路径,只把差异提升进 SOURCE,不再提交;project_commit 用调用方给的信息把这次同步提交成历史(message 必填、默认只给计划、插件补 trailer,可选 reference 记跨项目出处);workspace_describe 不打开 TIA 就能描述任意 workspace(索引/清单/证据/图谱/git);import_preflight 在导入前报告语言 culture、依赖顺序、同名对象。同步与提交分两步是为了让"变了什么"先被读到、提交信息由人确认(D30);project_diff 走独立入口。图谱缺席/引擎未构建只报"图谱未建成",不让流程失败。DRAFT/REMOTE 与变更台账未做。P0 的工程注册表与 P1 的内部 git 版本层已删除(该包 D22;现行版本管理见 D26)。已登记进蓝图(--dump-config 行数见根 AGENTS.md §4,DSH 0.2.1-rc.2) |
| 工程知识图谱插件 | 准确翻译 XML 中的 PLC 语法,XML → 图数据库 → 按需给出工程细节 | 🟡 部分实现:Simatic ML → 图 → SQLite 已通(7 个真实 fixture 出 72 节点 / 153 边,覆盖 15 种节点种类),引擎协议 + 8 个工具 + knowledgeGraph 服务(111 项单测,含经真实引擎的端到端);被族 2 的 create_engineering_project 调用(该包 D25)。knowledge_workspace 让模型自己读到库路径、knowledge_query 的 db_path 因此可省略,四个下钻工具(search / block / network / variable usage,TS 侧固定 SQL,零 C# 改动)把程序逻辑读成有界答复(D24 两阶段)。新鲜度/增量、兼容层未做。已登记进蓝图 |
| TIA 操作可见性(Todo) | 让输入框上方的 Todo 面板在 TIA/版本操作期间总有内容、结束后不残留转圈 | ✅ 2026-11-07:leader/auditor persona 写死 TIA · <tool> · <object> 协议 + dsh-tia-todo-bridge 兜底(模型没写清单时补项并自动结束);见 D34 与 profile README「TIA 操作的 Todo 清单」 |
逐项进度、缺口与验收口径见 docs/roadmap.md;
已定的取舍见 docs/decisions.md,18 条待决策问题在
docs/open-questions.md(已答 20 条,可直接编辑填写答复)。
路线图是方向性说明,不是承诺;已实现与规划中的能力在本文档里始终分开陈述。
3. 交付内容一览
| 交付物 | 类型 | 版本 | 提供什么 |
|---|---|---|---|
@voltarenyah/dsh-tia-openness-v17-min |
插件 bundle | 0.1.0 | 三个 Loader 行:宿主行 = TIA 控制器子进程 + engineeringAccess 服务 + 随包 skill;/tools 行 = 39 个工具:工程生命周期与工程数据 8(create_project / save_project / archive_project / project_info / project_languages / project_texts / update_project / portal_settings)、PLC 设备数据 9(list_plc_objects / create_plc_objects / delete_plc_objects / write_tags / set_block_attributes / protect_blocks / generate_source / watch_and_force_tables / software_units)、F 相关 3(safety_status / set_safety_settings / safety_signatures)、在线会话 4(online_targets / online_connect / online_status / online_disconnect)、下载 1(download)、接管 UI 工程 1(adopt_open_project)、硬件组态 5(export_hardware_config / hardware_inventory / hardware_configuration / hardware_parameters / hardware_view)、块编辑器 1(show_blocks_in_editor:在 TIA 的块编辑器里批量打开块,需要带界面的 TIA Portal)、项目库 1(project_library:类型/版本/主副本的浏览、导出、发布、实例化与组织)、块读写主线 5 + controller_status;/commands 行 = 7 个 /tia-… 斜线指令(open / save / compile / close / info / find / status,绕过模型直接在对话框执行)。工具行由 preset 声明(leader 有、expert 没有);命令行独立于工具行,只 inject commands + tiaOpennessRuntime。v0.2 的 20 个新操作尚未在真实项目上验证(见该包 docs/VERIFICATION-PLAN.md);控制器白名单另有 2 个服务专用操作(PlcChecksum / SyncScan,供工程上下文插件做版本取证,不注册模型工具),操作总数 40。2026-10-22 真机验证:PlcChecksum 3.2 s;SyncScan 全量 1376 文件 / 121–231 s,同账本第二次 unchanged 1.6–3.0 s,1 块变化的慢路径 48.3 s(导出 1 块 + 7 标签表);可见窗口打开工程 68–197 s(headless 会挂) |
dsh-tool-git |
插件 bundle(vendor) | 0.1.3 | 12 个工具:git_status / git_diff / git_log / git_branch / git_stage / git_commit / git_stash / git_show / git_fetch / git_pull / git_remote / git_checkout;外加破坏性命令闸门与 gitContext 服务。模型面工具已拆到 dsh-tool-git/tools,只挂 leader;auditor / expert 看不到。服务按显式根目录解析,模型不再传 repoDir |
@voltarenyah/dsh-engineering-context |
插件 bundle | 0.1.0 | 6 个工具、三个 Loader 入口:.(create_engineering_project 按 source_project 的类型打开 .ap17 或取回 .zap17(解包目标同样是 <workspace>/tia/<workspace 名>/),再另存/重建到 <workspace>/tia/<workspace 名>/、把源文件树重建到 <workspace>/source/<device>/、再经【缝 B】逐设备调用图谱插件的 knowledgeGraph.ingestDevice;project_status 只读:哪个 PLC、账本/清单在不在、git 状态、锁、下一步动作;project_sync TIA → STAGE → SOURCE,不提交;project_commit 用调用方给的信息提交设备目录,message 必填、默认只给计划、可选 reference 追加 Reference: trailer;workspace_describe 不打开 TIA 描述任意 workspace;import_preflight 导入前预检)、/diff(project_diff:块级结构差异,支持 to: "WORKTREE")、/status(project_status + workspace_describe + import_preflight,只读)。同步的相等性来自 PLC 级 checksum(快路径)+ 逐对象指纹/归一化哈希(慢路径):账本 source/<device>/_evidence.json 是权威、_manifest.json 是派生清单,两份文档由同一次 SyncScan 调用写出;STAGE 与锁落在 <workspace>/.dsh/local/(不进 git),.gitignore 只追加 tia/、knowledge/**/*.db*、.dsh/local/ 三行。提交信息尾部由插件追加 Tia-Op / Tia-Checksum / Tia-State trailer(以及可选的 Reference:)。同步与提交分成两步(D30):project_sync 只写树并返回 pending.paths + pending.suggestedMessage,project_commit 才写历史。未实现:DRAFT/REMOTE 与逐块指纹锁(S3)、变更台账。已删除:P0 的工程注册表与 P1 的内部 git 版本层,以及 eng_status / eng_project / eng_scope / eng_version 四个工具(该包 D22)。没有宿主面资源:. 只挂 auditor,/diff 挂 auditor + expert,/status 挂 leader(三个工具都只读) |
@voltarenyah/dsh-engineering-graph |
插件 bundle | 0.1.0 | 两个 Loader 行:宿主行 = C# 引擎子进程 + knowledgeGraph 服务(供族 2 的 create_engineering_project 逐设备调用);/tools 行 = 9 个工具:5 个共享工具(knowledge_workspace / knowledge_schema / knowledge_ingest / knowledge_update / knowledge_query)+ 4 个下钻工具(knowledge_search / knowledge_block / knowledge_network / knowledge_variable_usage,TS 侧固定 SQL,零 C# 改动)。knowledge_update 是增量入口:按 source_components 替换变更组件并重扫一跳依赖闭包,整批一个事务;没有 provenance / 超上限 / 类型或标签表变化时由调用方回退全量。includeIngest: false 去掉两个写工具,includeDrilldown 三档(none / inspect / all):leader 用 inspect、expert 用 all—— Simatic ML XML → 属性图 → SQLite,引擎以 net10 子进程运行(engine/;发布包为 self-contained 单文件,不要求用户安装 .NET)。纯 SCL 块按 REGION 分段(D27)。knowledge_workspace 不碰引擎:它读会话工作目录,报出工程身份、每台设备的库路径/大小/mtime、device_dir 与 graphFreshness(sidecar checksum vs _evidence.json),所以 knowledge_query 的 db_path 可以省略(单库自动解析,零库/多库拒绝并给候选,D24)。未实现:按需下钻工具(某个变量用法)、兼容层。数据库位置与目录约定见 docs/roadmap.md §4 |
dsh-ui-plc-source |
插件 bundle(浏览器半侧 + 一个宿主 pre-step 监听) | 0.1.0 | 一个 Loader 行 + 一个右侧栏 tab 类型:在 dsh-web 右侧栏(Files / Terminal / Browser 之后)增加 PLC Blocks。读 <workspace>/source/<device>/_manifest.json,把每个对象平铺成一行(类型徽章 / 名称 / 编号 / 语言 / 大小 / 写后校验标记),可按 device 与 simaticType 筛选、按名称或编号搜索;TIA 拒绝导出的对象(failures[])同样列成一行(标「拒绝」、可悬停看原因)。单击是选中(选中态暂不触发动作),右键菜单里才打开源文件(走既有文档预览)或「在对话里提及」(把 @'块名' 插进输入框;宿主半侧在 agent/pre-step 把该块的 device/类型/编号/语言/文件路径补进 prompt)。筛选/搜索/选中/滚动位置与已读数据放在 slot store 里,切走再切回不丢、也不重读清单。界面文字跟随 DSH 的语言设置(设置 → 通用 → 语言,中/英),切换时不用刷新,已打开的 tab chip 也会变。宿主半侧只做这件事(agent/pre-step 监听,无工具、无子进程);清单不可读时该 device 退回目录列举。可行性与机制见 docs/ui-plugins.md,本插件的计划与验收见 docs/ui-plugins-plc-blocks-plan.md |
dsh-ui-tia-console |
插件 bundle(仅浏览器半侧) | 0.1.0 | 一个 Loader 行 + 输入框上方的 TIA 控制台:显示「无项目 / 正在打开 / 已打开 · 项目名 / 正在保存 / 正在编译(已用时长)/ 正在关闭 / 不可用」,并直接提供 打开 / 保存 / 编译 / 关闭 / 刷新 五个按钮。按钮 dispatch 现有 /tia-* 指令,状态从会话的 command/*、tool/* 事件折叠而来 —— 模型调用、斜线指令、按钮三种触发都实时反映;空会话也可见(它挂在 conversation.input.dock,不依赖时间线)。刷新用 /tia-info 与控制器对齐。带展开面板(项目路径、最近编译、最近错误、最近结果)。Step 1 边界:状态按会话折叠,其他会话或外部关闭 TIA 后需点刷新校准;全局状态服务是下一步。 |
@voltarenyah/dsh-tia-todo-bridge |
插件 bundle(宿主面兜底) | 0.1.0 | 一个 Loader 行,不注册工具、不注册服务:监听 tools/execute / tools/post-execute 与 session/event。模型没写 Todo 清单时,把 open_project / export_blocks / import_blocks / compile_plc / project_diff / create_engineering_project / knowledge_ingest 等 32 个 TIA 与版本操作补成 TIA · <tool> · <object> 的 in_progress 项,工具返回即改 completed(失败加 (失败));模型自己写了清单则完全不改。纯查询与 subagent 不自动建项。详见 包 README 与 profile README「TIA 操作的 Todo 清单」 |
dsh-ui-versions |
插件 bundle(仅浏览器半侧) | 0.1.0 | 一个 Loader 行 + 一个右侧栏 tab 类型:在 dsh-web 右侧栏增加 Versions(排在 PLC Blocks 之后)。读 <workspace>/.dsh/versions-view.json —— 这份派生视图由 @voltarenyah/dsh-engineering-context 在 project_version_reindex、提交、project_version_annotate 之后写出,插件本身不写它、不新增 HTTP 路由、也不在渲染进程里开 SQLite。上半部是 VERSION HISTORY:每行 10 位 sha / subject / 日期 / checksumPrev → checksum / N block(s) 或 Baseline;展开后列出该版本的变更事件(变更类型徽章、块 key 按钮、+added -removed、face 芯片、每个变更 face 一行 10 位指纹);点块 key 在下方 BLOCK TIMELINE 看该块的跨版本轨迹(seq / sha / 日期 / subject / face 芯片 / 指纹 / Reason / Problem)。可按提交号、标题、意图、块名、原因搜索,并按 face、problem 过滤;缺失的指纹显示 —。宽度自适应:面板 ≥ 760px 才分两栏,< 560px 逐行堆叠(CSS 容器查询,看的是面板宽度不是窗口宽度)。颜色只用宿主语义 token,唯一的彩色是 4px 圆点(warning = modified,error = removed)。状态:无工作区 / 无视图(可重试)/ 读取失败(带 code,可重试)/ 无匹配 / 加载中。界面文字跟随 DSH 的语言设置(设置 → 通用 → 语言,中/英),切换不用刷新。宿主半侧只有一行空 apply() 打 info 日志 |
dsh-ui-hardware |
插件 bundle(仅浏览器半侧) | 0.1.0 | 一个 Loader 行 + 一个右侧栏 tab 类型:在右侧栏增加 Hardware,把 .dsh/hardware-view.json 渲染成「工程机架」——设备按角色分组、槽位画成机位条、选中槽位看型号/订货号/地址窗口,另有网络与信号映射视图。数据由 TIA 插件的 hardware_view 工具写入 |
dsh-ui-changes |
插件 bundle(浏览器半侧 + 一条只读路由) | 0.1.0 | 一个 Loader 行 + 右侧栏 Changes tab:按会话 header.cwd 经 gitContext 读真实 git 状态,列出未提交文件与每文件 +N/−M,面板可见时每 5 s 刷新;宿主路由 GET /changes/api/status 只回路径/计数,不写工作区、不提交。P1 只读;提交区 P2 未实现 |
dsh-ui-project-dashboard |
插件 bundle(浏览器半侧 + 标签路由) | 0.1.0 | 一个 Loader 行 + 全局工作区面板:在 Plugins 上方提供 workspace 行、标签/搜索/归档,宿主半侧维护 <DSH_HOME>/storages/project-dashboard/tags.json 并提供 loopback-only 标签路由 |
dsh-ui-prompt-guide |
插件 bundle(浏览器半侧 + 宿主静态路由) | 0.1.0 | 一个 Loader 行 + 主栏整页帮助页:左侧栏「Plugins」下面增加 提示词引导(Prompt Guide),点开是 9 个分类、32 条可搜索的 Prompt(中英双语,每条带「什么时候用 / 会发生什么 / 由哪个工具或子 agent 执行」)。卡片可复制,或「在新会话中使用」把 Prompt 填进输入框(不自动发送)。内容在 src/guide.ts,宿主经 /prompt-guide/api/guide 发出;页面是静态 page/,改文案不用重建客户端半侧。宿主路由只发自带文案、不读用户数据,并带最小 trust fence(Sec-Fetch-Site: cross-site 或 Origin/Host 不一致直接 403)。机制与验收见该包 README |
dsh-ui-brandmark |
插件 bundle(仅浏览器半侧) | 0.1.0 | 一个 Loader 行 + 首页 hero 品牌:把 DSH 首页的「Into the Unknown / Preview / 鱼形图标」换成发行版自己的「dsh-automation-suite / TIA-V17 / 桌面壳 app 图标」。文案取自 conversation 命名空间的 hero.headline / hero.preview,官方没有配置项;插件在客户端 locale 服务的 translate 上只拦这两个 key,其余原样落回字典,装/卸各 publish 一次触发重渲染。图标占用单座 conversation.hero.brand.mark,注册 occupant 即替换默认鱼形 fallback。两个字符串在 src/model.ts。内部 API 不是官方扩展点,失效时只告警、保留原首页 |
profile/dsh-automation-suite |
profile 蓝图 | 0.1.0 | 把官方 Web 组合(dsh-base + dsh-web-app)与上面的本地插件叠成一个可直接启动的 profile;并声明三个 preset:leader(主 agent)、auditor(版本管理)与 expert(子 agent)。另外挂一行公共插件 dsh-opencode-go@0.1.24(npm 上的 OpenCode Go 提供方 + 设置页,与桌面 profile 同版本;钉死版本、pnpm-workspace.yaml 里为它写了 allowBuilds;0.1.24 起内置表里带 deepseek-v4.1-flash、并把 models.dev 元数据缓存到磁盘,理由见该目录 README 与 D32) |
scripts/start-env.ps1 |
启动器 | — | 一条命令完成"物化 profile + 装插件 + 起服务 + 带 token 开浏览器" |
scripts/clean-build.mjs |
工具 | — | 只清理 lib/、dist/,遇链接只 unlink、不递归下降 |
主 agent(leader)名下有本发行版自己的 46 个工具(TIA 26 + git 12 + 工程上下文 3
(project_status / workspace_describe / import_preflight,都只读)+ 图谱 5,includeDrilldown: inspect 且
includeIngest: false),全部在同一个会话里可用 ——
例如"改完这个块,编译一下";另有内置 standard 自带的那批(fs / 检索 / skills / todo / web / present / subagent …)。
它不再持有 create_engineering_project / project_sync / project_commit / project_diff /
knowledge_ingest:这五个是分钟级的版本任务,只在 auditor 名下(D30)。
版本管理子 agent(auditor)声明 20 个工具:工程上下文 6(create_engineering_project /
project_status / project_sync / project_commit / workspace_describe / import_preflight)、project_diff 1、图谱 5(includeIngest: true、
includeDrilldown: none:knowledge_workspace / knowledge_schema / knowledge_query /
knowledge_ingest / knowledge_update)、只读文件 4(read / read_image / glob / grep)、
ask_user_question、todo_write、通信 2(send_message / interrupt_agent)。
它没有 pwsh、TIA 原子工具、git、图谱下钻、subagent。
⚠️ 子 agent 调 ask_user_question 拿不到 answerer(宿主只为 root agent 提供),
所以"提交前问用户"由它把方案 send_message 给 leader、leader 去问、再把答复发回。
子 agent(expert)自己的 preset 只声明 15 个(图谱 7:knowledge_workspace / knowledge_schema /
knowledge_query + 四个下钻工具;project_diff;只读文件 2:read / read_image;检索 2:glob / grep;
通信 2:send_message / interrupt_agent;再加审批 1:ask_user_question(读源码前必须用它拿用户批准,D29)),
加上宿主面仍是全局行的 1 个(working_directory)= 16 个。
git 的 12 个模型工具已从宿主行拆到 dsh-tool-git/tools,只挂 leader,所以 expert 与 auditor
都看不到它们。
两层 agent 的形态与理由见 §8.1 与
docs/decisions.md D23。
4. 功能是怎么实现的
4.1 组合机制:bundle → layer → profile
DSH 的加载分两条独立路径,两者都靠包名:
- profile 清单
dsh.profile.bundles里的名字 → 用于解析 bundle 目录; - 每个 bundle 的
cordis.patch.yml里insert[].name→ 被当作模块标识符交给 cordis Loader import。
因此 package.json 的 name 与 cordis.patch.yml 的 insert[].name 必须逐字一致
(带 @ 的 YAML scalar 还得加引号)。本发行版里这一点长这样:
# packages/dsh-tool-git/cordis.patch.yml (无 scope,不需要引号)
- insert:
- id: tool-git
name: dsh-tool-git
# packages/dsh-tia-openness-v17-min/cordis.patch.yml
- insert:
- id: tia-openness-v17-min
name: '@voltarenyah/dsh-tia-openness-v17-min'
蓝图的 dsh.profile.bundles 决定叠加顺序(后面的层可以覆盖前面的层),
profile 自己的 cordis.patch.yml 是用户层,在所有 bundle 层之后应用:
dsh-base → dsh-web-app → tia-openness-v17-min → dsh-tool-git → profile/cordis.patch.yml
(基础层) (Web 应用层) (插件层,只插自己的行) (插件层) (环境相关设置写这里)
两个插件的 bundle patch 只插入自己的行、不带任何环境相关配置,所以同一份 bundle
可以装在任意 profile 里;opennessDir、超时、destructivePolicy 这些归 profile 的用户层管。
4.2 TIA 插件:两层架构 + 白名单控制器
Openness 不能直接从 Node 调用,所以插件分成两层,中间是一行一帧的 NDJSON 协议:
┌─ DSH 宿主进程 (Node) ─────────────────────────────┐
│ dsh-tia-openness-v17-min (TypeScript) │
│ • 注册 6 个模型可见工具 │
│ • ctx.effect() 拥有 C# 控制器子进程 │
│ • 请求串行化 / 排队上限 / 硬超时终止与自动重启 │
│ • 传输层错误 → 结构化 ToolFailure │
└──────────────────┬────────────────────────────────┘
│ NDJSON over stdin/stdout
┌──────────────────▼────────────────────────────────┐
│ TiaOpennessV17Min.Controller.exe (C#, x64, │
│ .NET Framework 4.8) │
│ • 先注册 Siemens 官方程序集解析器,再惰性加载 │
│ Siemens.Engineering.dll(V17) │
│ • 只执行 5 个白名单操作 │
│ • 写入 = ExclusiveAccess + Transaction + 读回验证│
│ • 任何异常 → 结构化 JSON {code, message, details}│
└───────────────────────────────────────────────────┘
工具与它们的默认策略(26 个,统一返回 ok / summary / data / changes / diagnostics / error 信封;
完整清单与参数见该包 README.md §4 与
docs/EXTENDED-SURFACE.md):
| 工具组 | 工具 | 写入 | 默认 dry-run |
|---|---|---|---|
| 工程生命周期 | open_project |
仅当 allow_upgrade=true |
否(升级单独把关) |
| 块读写主线 | export_blocks / compile_plc / close_project / import_blocks |
导出只写文件;其余是 | 导入/编译/关闭 是,导出否 |
| 工程数据(v0.2) | create_project / save_project / archive_project / project_info / project_languages / project_texts / update_project / portal_settings |
除 project_info 外都可写 |
写类除创建/保存/归档/导出文本外均 是 |
| PLC 设备数据(v0.2) | list_plc_objects / create_plc_objects / delete_plc_objects / write_tags / set_block_attributes / protect_blocks / generate_source / watch_and_force_tables / software_units |
除列表与生成源文件外是 | 除生成源外均 是 |
| F 相关(v0.2) | safety_status / set_safety_settings / safety_signatures |
仅 set_safety_settings |
该工具 是 |
| 诊断 | controller_status |
否(不启动控制器) | — |
写入链路的四道保险:
- dry-run 默认开:写入类操作的
dry_run默认true,必须显式传dry_run: false; - 事务:
TiaPortal.ExclusiveAccess()→Transaction(project, …),只有全部文件成功后 才CommitOnDispose(),否则 dispose 即回滚; - 写后验证:导出逐文件读回校验
<Name>并记 SHA-256 + 写 manifest; 导入事务提交后重新读项目块集合,逐块确认存在并对比ModifiedDate/Number/ProgrammingLanguage; - 白名单:控制器只接受
controller/Protocol.cs的OperationCatalog里的 25 个操作名, 插件侧src/protocol.ts的OPERATIONS是同一份列表(双重校验,互不信任;npm run matrix:check逐条比对)。没有任何eval/Invoke/ 反射入口。
编译报错不是工具错误:state / errorCount / warningCount / messages 作为数据返回,让模型据此修正。
4.3 Git 插件:shell-free 执行 + 策略闸门
- 无 shell 注入:每条命令走
execFile+ 显式参数数组,模型给的路径与提交信息永不做字符串插值; - 机器输出:porcelain v2、
--numstat、--format记录被解析成结构化 JSON,而不是散文; - 闸门:
tools/pre-execute监听器检查每一次工具调用 —— 既包括插件自己的工具 (如git_commit带amend: true),也包括 shell 类工具的命令文本 (bash/pwsh/terminal等),匹配push --force、reset --hard、clean -f、branch -D、rebase、commit --amend、checkout --、update-ref -d等模式。 匹配按命令切分,不会跨|、;、换行,所以git add . && git push --force照样被拦, 而无辜的复合命令不会被误判。
这是一道策略护栏,不是沙箱。能跑任意代码的 agent 总能用别名、
-c改写或脚本绕开字符串匹配。 闸门的目的是让误触的破坏性命令大声失败并给出解释;有意为之的破坏性操作应当通过 配置策略(ask/allow)授权,而不是绕过闸门。
4.4 开发期的运行时解析(为什么仓库里不装 @deepseek-ai/*)
插件在运行期从 profile 的运行时解析拿到 @deepseek-ai/*,仓库里刻意不把它们声明为依赖:
公开 registry 上这条线止于 0.1.0-rc.6,而本仓对标的宿主是 0.2.1-rc.2 ——
拿旧副本做类型检查或跑测试 = 对着错误的 API 面验收。
于是两个包各有一个 link:runtime 脚本,从已安装 app 自己的 resources/app.asar
按 dependencies + peerDependencies 求闭包(约 32–33 个包 / 8 MB / < 1 s),
解包到 <DSH_HOME>/plugin-runtime,再 junction 进各自的 node_modules/@deepseek-ai/。
runtime.json 记下宿主版本,宿主升级后自动重抽。抽取出来的运行时不含 .d.ts
(app 的生产构建剥掉了),所以两个包各自手写了一份 src/dsh-runtime.d.ts 喂 tsc。
5. 环境要求
| 项目 | 要求 |
|---|---|
| 操作系统 | Windows(TIA 插件仅限;在其它平台能加载,但工具调用返回 controller_not_found)。Git 插件跨平台 |
| Node.js | ≥ 22.19(两个包 engines 都这么写);pnpm 与 dsh 本机可不在 PATH 上 |
| DSH | 任何能加载 bundle 的版本 |
| TIA Portal | 当前成员绑定 V17(dsh-tia-openness-v17-min 严格绑定,不兼容 V16/V18)。V18 是另一个族成员(@voltarenyah/dsh-tia-openness-v18,尚未实现)——两个成员同一时刻只能激活一个,在插件页拨 bundle 开关并重启客户端,见 docs/tia-version-members.md / D36 |
| Openness DLL | C:\Program Files\Siemens\Automation\Portal V17\PublicAPI\V17\Siemens.Engineering.dll(V18 成员对应 Portal V18\PublicAPI\V18) |
| .NET Framework | 4.6.1+(控制器以 4.8 为目标框架构建);进程位数必须 x64 |
| Windows 用户组 | 当前用户必须属于本地组 Siemens TIA Openness(net localgroup "Siemens TIA Openness") |
| 只有重建 C# 控制器才需要 | .NET SDK + .NET Framework 4.8 targeting pack + 能访问 NuGet 源 |
| 只有重建 TS 才需要 | pnpm install(只装 typescript / tsdown / vitest / @types/node) |
仓库已包含两个插件的已构建产物(lib/、controller/bin/*.exe),安装前无需编译。
6. 快速开始
6.1 一条命令起独立环境(推荐)
scripts/start-env.ps1 把"按蓝图物化 profile + 装插件 + 起服务 + 带 token 开浏览器"收成一条命令,
并且不碰你日常的 ~/.dsh(默认用自己的 DSH_HOME=%USERPROFILE%\dsh-suite-env,
删掉该目录即完全回退):
pwsh -NoProfile -File scripts\start-env.ps1
它做四件事:pnpm -r build → 按蓝图物化 profile 目录 → 把本地插件按名字链进 profile
(默认 -Mode link,验的是当前工作树;-Mode pack 改为 pnpm pack 出 tarball,验真实交付物)
→ 启动 dsh --profile dsh-automation-suite --port 3092。
要部署哪些插件不写死在脚本里:它读蓝图的 dsh.profile.bundles,
凡是能在 packages/ 下按 package.json 的 name 匹配到的条目都算本地插件
(带 scope 与不带 scope 同一套逻辑),所以新增插件只要建目录 + 把包名写进蓝图即可,脚本无需改动。
常用开关:
pwsh -NoProfile -File scripts\start-env.ps1 -Restart # 端口上有旧实例就先停掉再起(开发循环)
pwsh -NoProfile -File scripts\start-env.ps1 -Port 0 # 随机端口
pwsh -NoProfile -File scripts\start-env.ps1 -Mode pack # 验真实交付物
pwsh -NoProfile -File scripts\start-env.ps1 -DshHome C:\temp\e2e # 换一个独立 home
pwsh -NoProfile -File scripts\start-env.ps1 -Reset -NoOpen # 先删掉重建,且不开浏览器
| 参数 | 默认 | 说明 |
|---|---|---|
-DshHome |
%USERPROFILE%\dsh-suite-env |
独立 DSH_HOME;删掉即回退 |
-Profile |
dsh-automation-suite |
profile 名,同时决定用哪个蓝图 |
-Port |
3092 |
0 = 系统挑空闲端口 |
-Mode |
link |
link 验工作树 / pack 验 tarball |
-SkipBuild |
关 | 跳过 pnpm -r build |
-Reset |
关 | 先删 profile 目录再重建(会先请你确认) |
-Restart |
关 | 端口上已有 DeepSeek Harness 就先停掉它;占用者是别的进程则报错退出,不误杀 |
-NoOpen |
关 | 不自动打开浏览器 |
本机
pnpm与dsh都不在 PATH 上,脚本自己从 DSH 安装目录解析 ($env:DSH_APP_ROOT可覆盖,默认%LOCALAPPDATA%\Programs\DeepSeek Harness)。
6.2 装进日常的 ~/.dsh
把仓库里的蓝图目录直接挂成 profile(junction,随改随生效):
pnpm install # 在 Monorepo 根:workspace:^ 把插件链进蓝图的 node_modules
cmd /c mklink /J "$env:USERPROFILE\.dsh\profiles\dsh-automation-suite" `
"<repo>\profile\dsh-automation-suite"
dsh --profile dsh-automation-suite --dump-config # 应看到两个插件的行
用完要拆,必须用 cmd /c rmdir(只删链接本身):
cmd /c rmdir "$env:USERPROFILE\.dsh\profiles\dsh-automation-suite"
6.3 装发布物(Monorepo 之外)
从 Releases 下载
dsh-automation-suite-<version>.zip,解压后双击 install.cmd(推荐;直接双击 .ps1
会被 Windows 的下载标记 + RemoteSigned 策略拦截并闪退),或在终端运行:
pwsh -NoProfile -File install.ps1
它把 profile 的三件套(package.json / cordis.patch.yml / pnpm-workspace.yaml)复制到
专用 home %USERPROFILE%\dsh-automation-suite-home\profiles\dsh-automation-suite-v<version>\
(不是日常 ~/.dsh),再用 DSH 自带的 pnpm 安装十四个本地插件的 tarball(Release 资产,profile 里是
**直接 URL 依赖**,不需要 npm 账号)。同时在解压目录写下 install.json,记录这次用的 home 与 profile。
双击 start.cmd 启动:它读取 install.json、设置 DSH_HOME、从 3093 起自动挑一个空闲端口并打开浏览器,
不需要记 --profile / --port。可选:start.cmd -NoOpen、start.cmd -Port 3093。
为什么用专用 home:左侧 workspace 列表来自 <DSH_HOME>\storages\workspace.json 这份注册表,
会话、设置、模型凭据也都在 DSH_HOME 下。与 desktop 共用 ~/.dsh 会让发布版显示 desktop 打开过的项目,
并互相回写同一份注册表;独立 home 后,发布版的 workspace 列表从空开始,只包含你在这个 App 里添加的工程。
开发版与发布版并存:开发版用 dsh-automation-suite(scripts/start-env.ps1 默认在隔离的
%USERPROFILE%\dsh-suite-env 里物化),发布版用带版本号的 profile(默认落在
%USERPROFILE%\dsh-automation-suite-home);两者在 workspace、会话、设置、凭据上完全隔离,
可以同时启动(start.cmd 会自动错开端口)。想用一个固定名字原地升级,可显式传
-Profile dsh-automation-suite-release -Force——覆盖前会先备份该 profile 的 package.json 与
cordis.patch.yml。安装器拒绝写入 junction/symlink(避免顺链接改到别处)。
维护者生成发布目录(tarball + profile + install.cmd / start.cmd + sha256 清单):
node scripts/build-distribution.mjs
为什么不能直接 dsh plugin add 装整份发行版:命令只接受带 dsh.bundle.patch 的 bundle,
而蓝图声明的是 dsh.profile.bundles,会被拒为 not-a-bundle。方案对比、ERR_PNPM_* 两个坑、
发布与本地验收步骤见 docs/distribution.md。十四个插件本身是标准 bundle,
仍可单独 dsh plugin --profile web add <包名或 tarball>。
桌面图标、独立窗口与安装器属于下一阶段;设计、产物、失败处理与分阶段工作量见
docs/desktop-packaging.md。Phase 1 壳、Phase 2 安装器与
Phase 2c DSH/WebView2 bootstrap 已可运行:node scripts/build-app-layer.mjs --version 0.2.0
物化离线 app layer;pwsh desktop/build-shell.ps1 -Version 0.2.0 -SmokeTest 构建自包含壳并跑
隐藏冒烟测试;pwsh desktop/build-installer.ps1 -Version 0.2.0 生成 Inno 安装器。安装器会在
DSH/WebView2 缺失时下载并校验官方安装包,然后复制固定 profile、备份并三方合并旧覆盖项、跑
doctor、写 install.json。已在干净 Windows 11 LTSC VM 上分别覆盖“无 DSH”和“无 WebView2”两条路径并验收通过。
见 desktop/README.md。
6.4 首次进入必须自己配模型
启动后 dsh 会打印带 token 的 URL 并自动用默认浏览器打开(token 每次启动都换、不落盘,
裸地址会 401)。首次进入要去 设置 → Models 填 API key(或首次运行弹窗 "Add an API key to get started");
凭据落在该 home 的 .credentials.yaml,与日常 home 无关。
7. 交互使用
7.1 三个交互面
| 交互面 | 在哪 | 用来做什么 |
|---|---|---|
| 对话 | Web GUI 的会话输入框 | 主用法:用自然语言描述任务,模型自己选 39 个工具去执行 |
| 设置 / 插件页 | 侧边栏 Settings、Plugins | 配 API key、看已加载插件、启用/禁用插件、调配置 |
| 命令行 | scripts/start-env.ps1、dsh … |
起停环境、部署、验收(--dump-config) |
在 Creator 模式下还可以让模型自己调 plugin_manager 装插件:
plugin_manager(action: "install_bundle", target: "C:\\Users\\Ansel\\dsh-automation-suite\\packages\\dsh-tia-openness-v17-min")
7.2 对话示例
TIA(导出 → 改 → 导入 → 编译) —— 用户侧只需要说:
"打开
C:\Projects\Line1\Line1.ap17,把所有块导出到C:\Projects\Line1\export。"
"把
FB_Motor的<HeaderVersion>从 0.1 改成 0.2,导回它原来的组,然后编译验证。"
模型侧展开成的调用链(每一步都是 TIA 插件的工具之一):
{ "project_path": "C:\\Projects\\Line1\\Line1.ap17" } // open_project
{ "output_dir": "C:\\Projects\\Line1\\export", "block_names": ["FB_Motor"] } // export_blocks
{ "import_paths": ["…\\FB_Motor.xml"] } // import_blocks:默认 dry_run
{ "import_paths": ["…\\FB_Motor.xml"], "import_options": "override",
"target_group": "999_Kautex", "dry_run": false } // 真导入 + 写后验证
{ "dry_run": false } // compile_plc:真编译
{ "save": true, "dry_run": false } // close_project
Git —— 用户说"看看现在什么状态,把改动提交了",模型调 git_status → git_diff → git_stage → git_commit,
拿到的是结构化 JSON 而不是散文。若它试图 git push --force,闸门会直接拒绝并说明理由与放行方式。
7.3 dry-run 与审批:写操作不会悄悄发生
- TIA 写入默认预演:
import_blocks/compile_plc/close_project不加dry_run: false时 只返回计划(data.ready/data.plan/data.conflicts),项目一个字节都不动。 - Git 破坏性操作默认拒绝:
destructivePolicy: deny。改成ask后走运行时的审批缝 (ctx.approval),由你在界面上批准;没有挂审批服务的环境会降级回deny。 - 每个工具的
description里都写明了这些策略,模型直接读得到,不需要你教它。
7.4 随包出货的知识库:tia-openness skill
插件把 Siemens 官方的 Openness skill 集
(siemens/tia-portal-ai-extensions,MIT)
逐字打进包里,注册成模型可见的一个 skill tia-openness:
- 它是一张「症状 / 任务 → 该读哪个文件」的路由表(独占访问、事务、Simatic ML 往返、 块组层级、编译、licensing/防火墙、线程、崩溃定位、性能……);
- 31 个上游文件作为资源放在
skills/<name>/SKILL.md,模型按需read分段读取, 所以知识库不占常驻上下文,只在真正用到时付费; - 每个工具的 description 末尾都带一句
Troubleshooting: load the bundled `tia-openness` skill …, 会话目录里也有同名条目,模型一定会看到它。
想要模型去查这些资料,直接说"编译报错了,查一下 Openness 的排查手册"即可。
7.5 触发约定、停止与回退
- 说「启动 App」(或"起一下环境")= 在仓库根执行
pwsh -NoProfile -File scripts\start-env.ps1 -Restart。-Restart让这条命令永远可用: 端口被占就先停掉旧的DeepSeek Harness再起,所以"改完代码 → 启动 App"是一步。 - 停止:在该实例的窗口里
Ctrl+C;窗口丢了就Stop-Process -Id <harness pid> -Force, 控制器会读到 stdin EOF 自行退出(用Get-Process TiaOpennessV17Min.Controller确认无残留)。 - 完全回退:删掉独立
DSH_HOME目录即可 —— 但必须用cmd /c rmdir /s /q(见 §14)。
7.6 启动成功的判断标准
- 控制台出现
dsh web: http://127.0.0.1:<port>/?token=…,且浏览器自动打开; - 该端口有监听(
Get-NetTCPConnection -State Listen -LocalPort 3092→DeepSeek Harness); - 插件真的加载了的硬证据:出现
TiaOpennessV17Min.Controller子进程 (Get-Process TiaOpennessV17Min.Controller)—— 说明apply()执行过、ctx.effect持有子进程。 没看到它,就是插件没加载,别急着怀疑 TIA。
8. 配置
所有环境相关的设置都写在 profile 的用户层 ~/.dsh/profiles/dsh-automation-suite/cordis.patch.yml。
顶层是 loader patch 条目数组:按 id 覆盖 config、disable 某行,或 insert 新行。
蓝图里那份不是空数组了:它同时承载下面的发行版政策层,物化 profile 时会被拷进去。
8.1 发行版政策层(注入系统提示词)与两层 agent
profile/dsh-automation-suite/cordis.patch.yml 最前面那几块,把发行版规矩注入到 system 角色的
提示词里。纯配置、无插件代码,改文字不需要重新构建:
| 条目 | 作用 |
|---|---|
- id: system-prompt |
覆盖全局 persona(管非 preset 的 agent) |
- id: agent-preset-registry |
把新会话的默认 preset 指到 leader |
- insert: - id: preset-leader |
主 agent:内置 standard 的工具清单原样 + 编辑与检查面(TIA / git / project_status / 图谱检查面)+ 政策文本;不含版本工作流 |
- insert: - id: preset-auditor |
版本管理(leader 派它跑慢活):工程上下文 4(含 project_commit)+ project_diff + 图谱 5(含 ingest)+ 只读文件 + ask_user/send_message/todo;无 shell、无 TIA 原子工具、无 git |
- insert: - id: preset-expert |
子 agent:只读的工程知识专家(图谱发现 + 查询 + 四个下钻工具 + 只读文件检索 + send_message) |
- id: preset-standard … preset-cordis |
四个内置模式默认 disabled: true;它们不声明工程工具行,切过去会静默丢工具,所以选择器只保留发行版的三个 preset |
要改政策文字,只改四处 block scalar(全局 personaPrefix/personaSuffix、preset-leader
的 persona、preset-auditor 的 persona、preset-expert 的 persona)。想换成中文,写法在文件头注释里;
四个内置 preset 的禁用条目默认已生效(要恢复原生模式,删掉那四条,不推荐)。
Todo 清单是这套 policy 的一部分:leader 与 auditor 的 persona 里各有一段 “Todo protocol”—— 第一次 TIA 操作前用
todo_write写出TIA · <tool_name> · <object>的完整计划,操作前标in_progress、结果一到立刻标completed;派发给 auditor 的版本操作在subagent前标in_progress、结果消息到达才结束。模型漏写时由@voltarenyah/dsh-tia-todo-bridge兜底补一行并 自动结束,模型自己写了清单则完全不改。机制、覆盖范围与验收见 profile README 的 「TIA 操作的 Todo 清单」。
目录选择器固定为应用内浏览:蓝图里关掉了上游的
directory-picker(默认行@deepseek-ai/dsh-host-directory-picker-auto—— Windows 回环启动会解析成native, 也就是系统文件夹对话框),插入directory-picker-browse后端与它的浏览器半边@deepseek-ai/dsh-client-ui-directory-picker-browse。于是 "Add workspace" 弹的是应用内的 "Select Workspace Directory"(Home / 两列 / New folder / Show hidden files / Open), 远端与 SSH 访问也一样,壳是 WebView2 还是浏览器都不影响。三条踩坑(改name会被 patch 跳过、 两个面必须成对、只能靠界面验收)见 profile README 与docs/decisions.mdD35。
两层 agent 为什么这样切
目的只有一个:拆上下文与拆时长。主 agent 管对话和编辑环(开工程、导入/导出、改块、编译),
auditor 管版本流水线(创建、同步、差异、提交、图谱刷新)这些分钟级的活,expert 钻进具体代码问题,
各自在自己的窗口里推理,只有结论回流。
- 派发:主 agent 用
subagent工具派给expert或auditor(allowedAgentPresets就是这两个 id)。 工具立刻返回started subagent <id>,不等待;子 agent 结束时宿主把它的收尾文本作为一条 notice 写回主会话。 - 用户插话:父会话 header 的「后代数」触发器 → 目录树 → 点一行在主区打开、或点行尾箭头 在右侧栏分栏打开。continuable 子会话有完整 composer,可以继续追问;追问也会回流给主 agent。 (左侧会话列表刻意不含子会话,这是宿主的设计。)
- 工具面:
expert看不到任何 TIA 操作工具、git、pwsh、工程上下文工作流,也拿不到knowledge_ingest。它的"只读"只由工具面保证——子 agent 继承父会话的显式沙箱覆盖, 审批策略被宿主钉死never,所以别指望沙箱拦它。 - 深度:
subagent.maxDepth默认 1,expert不能再派孙代。
实测效果(一次真实请求落盘的 system/message):identity 之后紧接着就是 personaPrefix,
personaSuffix 落在提示词最末尾。
⚠️ persona 文本里的
{{...}}是严格插值,只有provider与model两个变量存在 (dsh-agent-loop注册的)。写别的名字(例如{{cwd}})会让整个回合失败:unknown prompt variable "{{cwd}}" in section "deployment:persona-suffix"; registered variables: provider, model。 工作目录本来就在 runtime context 里,persona 不必再写一遍 —— 本蓝图早期版本踩过这个坑, 全局与两个 preset 的 persona 现已统一改成一句话引用 runtime context。
⚠️ 别把这段"简化"成只留一行
- id: system-prompt。web 组合的 agent 一律走 preset, preset 内的dsh-persona行按作用域遮蔽全局 persona——已实测:给全局 persona 打标记, 该标记不会出现在 preset 会话的提示词里;而dsh-base的全局工具行全是disabled: true, 真正生效的工具面就在 preset 的plugins里。机理与升级时的重生成办法见 profile/dsh-automation-suite/README.md。⚠️ 工程工具按 preset 分发:宿主面只留控制器/引擎子进程与服务,模型面工具行写在 preset 里。 四个内置 preset 默认已禁用;若手动恢复并切过去,TIA、工程上下文、图谱工具都不存在—— 这是有意的。详见
docs/decisions.mdD23。
8.2 插件配置
# ~/.dsh/profiles/dsh-automation-suite/cordis.patch.yml
- id: tia-openness-v17-min
config:
opennessDir: 'C:\Program Files\Siemens\Automation\Portal V17\PublicAPI\V17'
requestTimeoutMs: 600000 # 大项目导入/编译实测常需 10 分钟以上,默认 300000 会超时
- id: tool-git
config:
destructivePolicy: ask # deny(默认)| ask | allow
workDir: 'C:\work\my-repo'
TIA 插件(全部有默认值,整块 config 可以省略):
| 字段 | 默认 | 说明 |
|---|---|---|
controllerPath |
'' |
控制器 exe 绝对路径;空 = 用包内 controller/bin/…。也可用环境变量 TIA_OPENNESS_V17_MIN_CONTROLLER |
opennessDir |
'' |
传给控制器的 --openness-dir;空 = 控制器默认路径。控制器侧还认环境变量 TIA_OPENNESS_V17_DIR |
requestTimeoutMs |
300000 |
单次操作硬超时;超时会终止控制器(Openness 无法取消),下次调用自动重启 |
startupTimeoutMs |
30000 |
启动握手超时 |
shutdownGraceMs |
5000 |
卸载时先关 stdin 优雅退出,超时后强杀 |
maxQueue |
8 |
排队上限,超出返回 controller_busy |
logControllerOutput |
false |
把控制器 stdout/stderr 转发到 DSH 日志 |
verboseResults |
false |
工具结果里附带完整控制器 payload |
Git 插件:
| 字段 | 默认 | 说明 |
|---|---|---|
workDir |
'' |
仓库发现起始目录(默认 process cwd) |
gitPath |
git |
git 可执行文件 |
destructivePolicy |
deny |
deny / ask / allow |
extraDestructivePatterns |
[] |
追加给闸门的额外大小写不敏感正则 |
logMaxCommits |
20 |
git_log 默认条数(上限 100) |
diffContextLines |
3 |
git_diff / git_show 的 patch 上下文行数 |
每个工具都接受可选的 repoDir,并在结果里报告解析出的仓库根。
profile 的
patchReload不是live时,改完配置要重启 DSH 才生效。
9. 仓库结构
packages/
dsh-tia-openness-v17-min/ TIA Portal V17 Openness 插件(MIT)
src/ 插件与协议实现(index/config/controller/protocol/tools/skills/errors)
controller/ C# 控制器(x64 / .NET Framework 4.8)
bin/ 已构建产物 TiaOpennessV17Min.Controller.exe(+ .exe.config)
skills/ 随包出货的 Openness 知识库:31 个上游 SKILL.md(逐字)+ 路由 skill
test/ node:test 套件(62 项:61 通过 / 1 跳过)
docs/ 协议、决策记录、真实项目实测、覆盖矩阵、功能测试指南
test-profile/ 试跑材料:三层验证指南 + 脚本,不改默认 profile
dsh-tool-git/ vendor 副本(上游 lxj808624/dsh-tool-git v0.1.3,MIT)
src/tools/ 12 个 git 工具
src/safety.ts tools/pre-execute 破坏性命令闸门
tests/ vitest 套件(33 项)
README.md / README.zh.md 上游 README(英/中)
dsh-engineering-context/ 工程上下文插件:**已登记进蓝图;6 个工具(D22 + S2 + 跨 workspace 的 workspace_describe / import_preflight)+ 缝 B 的图谱建库(D25)+ 归档取回(D27)**
src/ 作用域解析、缝 A/B、证据账本、锁、shell-free git、4 个工作流工具(tsc → lib/)
test/ node:test 套件(151 项,假 TIA/图谱服务 + 真实运行时 schema 校验 + 真实 git 仓库)
scripts/ link-dsh-runtime.mjs / tsc.mjs / run-tests.mjs
docs/ ARCHITECTURE.md / PATH-RULES.md / decisions.md
dsh-engineering-graph/ 工程知识图谱插件:**引擎 + 协议 + 8 个工具 + knowledgeGraph 服务,已登记进蓝图**
src/ NDJSON 协议客户端、4 个知识工具(含本地发现工具)、knowledgeGraph 服务(tsc → lib/)
test/ node:test 套件(128 项,含经真实引擎的端到端与传输层故障注入)
engine/ C# 引擎(net10 + Microsoft.Data.Sqlite 10;发布时自包含):Simatic ML → 图 → SQLite
Graph/ Parsing/ Import/ 为 vendored(命名空间拍平,见 D17);
build.ps1 构建到 engine/bin(**进 git**:引擎缺席时插件仍加载但每次调用报
engine_not_found,所以随包出货才是"checkout 开箱可用"),fixtures/ 是 7 个真实 V17 导出物
scripts/ link-dsh-runtime.mjs / tsc.mjs / run-tests.mjs
dsh-ui-plc-source/ 右侧栏「PLC Blocks」标签页 + 宿主 pre-step 监听(提及注入),已登记进蓝图
src/index.ts 宿主半侧:agent/pre-step 把 @'块名' 解析成引用信息(tsc → lib/)
src/model.ts 纯模型:清单解析/平铺/筛选/排序/资源地址/文案/提及语法(tsc → lib/)
src/client/ apply(ctx) + 面板组件 + 样式(esbuild → lib/client.js,宿主认的 loader 包装)
test/ node:test 套件(47 项,纯模型)
scripts/ tsc.mjs / build.mjs / run-tests.mjs
dsh-ui-tia-console/ 输入框上方「TIA 控制台」:状态 + 打开/保存/编译/关闭/刷新(仅浏览器半侧)
src/index.ts 宿主半侧:空 apply(),只为让包在 Loader 里有一行
src/client/model.js 纯事件折叠:command/tool 事件 → 控制台状态(可单测)
src/client/TiaBar.jsx 控制台组件(状态、按钮、展开详情、秒表)
src/client/index.jsx 注册 conversation.input.dock 占位
test/ node:test 套件(22 项,纯折叠 + 字典)
scripts/ tsc.mjs / build.mjs / run-tests.mjs
dsh-tia-todo-bridge/ Todo 兜底:模型没写清单时把 TIA/版本操作补进会话 todos(宿主面一行)
src/bridge.ts 纯状态机:所有权、任务命名、开始/结束计划、日志重建(tsc → lib/)
src/index.ts 接线:session/event + tools/execute + tools/post-execute
test/ node:test 套件(18 项:纯状态机 16 + manifest 2)
dsh-ui-versions/ 右侧栏「Versions」标签页:版本历史 + 块级轨迹(仅浏览器半侧)
src/index.ts 宿主半侧:空 apply(),只为让包在 Loader 里有一行
src/model.ts 纯模型:视图解析/筛选/时间线/短 sha 与日期格式化(tsc → lib/)
src/client/ apply(ctx) + 面板组件 + 样式(esbuild → lib/client.js,宿主认的 loader 包装)
test/ node:test 套件(15 项,纯模型 10 + 字典 5)
scripts/ tsc.mjs / build.mjs / run-tests.mjs
dsh-ui-prompt-guide/ 主栏「提示词引导」整页:9 分类 / 32 条 Prompt,可搜索、复制、开新会话
src/guide.ts 内容数据(分类、条目、工具白名单;中英双语)
src/page.ts 纯函数:路径安全、MIME、trust fence、answer()
src/index.ts 宿主半侧:/prompt-guide 前缀路由(静态页 + /api/guide)
src/client/index.jsx sidebar.panellist + main 座位、主题转发、startSession 桥
page/ 静态页 index.html / app.js / style.css(不经构建,改文案刷新即生效)
test/ node:test 套件(25 项:数据 / 路由 / 产物 / 字典)
scripts/ tsc.mjs / build.mjs / run-tests.mjs
dsh-ui-brandmark/ 首页 hero 品牌:标题 / 徽标 / 桌面图标(仅浏览器半侧)
src/model.ts 纯模型:conversation 命名空间两个 key 的文案映射(tsc → lib/)
src/index.ts 宿主半侧:空 apply(),只为让包在 Loader 里有一行
src/client/ locale.translate 包装 + 单座 brand.mark(esbuild → lib/client.js)
assets/brandmark.png 桌面壳 app.ico 的 128px PNG(构建期内联成 data URL)
test/ node:test 套件(5 项:文案 / 回落 / 图标 / manifest)
scripts/ tsc.mjs / build.mjs / run-tests.mjs
profile/
dsh-automation-suite/ 发行版的 profile 蓝图
package.json dsh.profile.bundles = 组合顺序
cordis.patch.yml 用户 patch 层(空数组,环境设置归这里)
pnpm-workspace.yaml 与 DSH initProfile() 模板逐字一致(nodeLinker: hoisted)
scripts/
start-env.ps1 独立 DSH_HOME 的环境启动器
clean-build.mjs 只清理 lib/ dist/ 的构建产物清理器
docs/
vision.md 愿景:问题、三层方案、每层职责与设计原则
architecture.md 目标架构:接口插件族与两个工程插件的职责、边界、契约与数据流
decisions.md 发行版级决策记录(已定的取舍 + 待验证项)
open-questions.md 开放问题(34 条,可直接编辑填写答复)
roadmap.md 路线图与现状:逐项进度、缺口、验收口径
tool-surface.md 工具面重设计(调研 + 提案):现状体检、工作流清单、目标工具面与返回契约
AGENTS.md 仓库级约定(结构与命名、危险操作红线、验收口径)
LICENSE 本仓 MIT 许可证(原创部分)
pnpm-workspace.yaml workspaces: packages/* + profile/*
10. 开发
pnpm install # 全仓安装
pnpm -r build # 全仓构建
pnpm -r typecheck # 全仓类型检查
pnpm test # 全仓测试
pnpm run clean:build # 清构建产物(只碰 lib/ dist/)
本地十四个插件加 vendor 的 dsh-tool-git 用两种测试运行器,pnpm -r test 会把十五者都跑到:
| 包 | 运行器 | 测试规模 |
|---|---|---|
dsh-tia-openness-v17-min |
node:test(node --test test/*.test.mjs) |
112 项:111 通过 / 1 跳过(跳过项是"控制器未构建"的降级路径) |
dsh-tool-git |
vitest(vitest run) |
51 项全通过 |
@voltarenyah/dsh-engineering-context |
node:test(node scripts/run-tests.mjs,先构建再跑) |
151 项全通过(含经假 engineeringAccess / 假 knowledgeGraph 服务的契约用例) |
@voltarenyah/dsh-engineering-graph |
node:test(node scripts/run-tests.mjs,先构建再跑) |
128 项全通过(含经真实引擎的端到端;引擎没构建时该项 skip 并打印构建命令) |
@voltarenyah/dsh-drawing |
node:test(node scripts/run-tests.mjs,先构建再跑) |
23 项全通过(PDF 索引/检索模型 + 字典;浏览器半侧靠真实图纸验收) |
@voltarenyah/dsh-plcsim-advanced |
node:test(node --test --test-reporter=spec) |
18 项全通过(纯协议与工具面:转发、工作区存档根、证书规则、渲染事实行) |
dsh-ui-plc-source |
node:test(node scripts/run-tests.mjs,先构建再跑;浏览器半侧 .jsx 不进 tsc) |
47 项全通过(纯模型 33 + 宿主 9 + 字典 5) |
dsh-ui-tia-console |
node:test(node scripts/run-tests.mjs,先构建再跑) |
22 项全通过(纯事件折叠 + 字典) |
@voltarenyah/dsh-tia-todo-bridge |
node:test(node --test test/*.test.mjs) |
18 项全通过(纯状态机 16 + manifest 2;不依赖真实 TIA) |
dsh-ui-versions |
node:test(node scripts/run-tests.mjs,先构建再跑) |
15 项全通过(纯模型 10 + 字典 5;浏览器半侧靠真实 dev-env 验收) |
dsh-ui-hardware |
node:test(node scripts/run-tests.mjs,先构建再跑) |
9 项全通过(视图解析/筛选/槽位/机位面/格式化;浏览器半侧靠真实 .dsh/hardware-view.json 验收) |
dsh-ui-prompt-guide |
node:test(node scripts/run-tests.mjs,先构建再跑) |
25 项全通过(数据完整性/工具白名单 7 + 路由与 fence 10 + 产物与座位 6 + 字典 2;浏览器半侧靠真实 dev-env 验收) |
dsh-ui-brandmark |
node:test(node scripts/run-tests.mjs,先构建再跑) |
5 项全通过(文案映射与字典落回 + 128px 图标 + manifest/行一致性;浏览器半侧靠真实 dev-env 验收) |
单测都需要真实的 @deepseek-ai/* 运行时(不是 stub)。裸 checkout 首次运行时,
两个包的测试自举会各自自动触发抽取;也可以手动:
pnpm --filter @voltarenyah/dsh-tia-openness-v17-min run link:runtime
pnpm --filter dsh-tool-git run link:runtime
包内另有针对性的命令(在包目录里跑):
npm run check # TIA:build + test + matrix:check + skills:check
npm run build:controller # TIA:重建 C# 控制器(需要本机 TIA V17 + NuGet 源)
npm run test:controller # TIA:控制器自检 14 项(无需 TIA Portal)
npm run matrix:build # TIA:重新生成 docs/coverage-matrix.html
npm run skills:build # TIA:按 pinned commit 重新取上游知识库
几个必须知道的约定
- 不要手改生成物:TIA 包的
docs/coverage-matrix.html、skills/<上游名>/SKILL.md、skills/UPSTREAM.json都是生成物,改src/或控制器后要跑对应的:build,否则:check会失败。 tsdown会把能解析到的包打进产物,所以dsh-tool-git的两个 tsdown 配置里deps: { neverBundle: true }不能删:否则链接过运行时之后,产物会把整个宿主运行时内联进去 (57.78 kB → 391.40 kB),插件会拿到一份私有的dsh-tools。验收口径:lib/index.mjs应约 57.78 kB。clean这个名字不能用:pnpm 11 有内置子命令会遮蔽脚本,本仓叫clean:build。- 在 JS 块注释里写 glob 会截断注释(
profiles/*/node_modules的*/会提前结束/** … */), 写路径用profiles/<profile>/node_modules或转义。
11. 验收
profile 组合的端到端验收:
dsh --profile dsh-automation-suite --dump-config
预期结尾出现(每个插件 3 行:"# ==" 注释 + id + name,15 个插件行 = 14 个本地插件 + 公共的 dsh-opencode-go):
# == @voltarenyah/dsh-tia-openness-v17-min
- id: tia-openness-v17-min
name: '@voltarenyah/dsh-tia-openness-v17-min'
# == @voltarenyah/dsh-plcsim-advanced
- id: plcsim-advanced
name: '@voltarenyah/dsh-plcsim-advanced'
# == @voltarenyah/dsh-engineering-context
- id: engineering-context
name: '@voltarenyah/dsh-engineering-context'
# == @voltarenyah/dsh-engineering-graph
- id: engineering-graph
name: '@voltarenyah/dsh-engineering-graph'
# == @voltarenyah/dsh-drawing
- id: drawing
name: '@voltarenyah/dsh-drawing'
# == dsh-tool-git
- id: tool-git
name: dsh-tool-git
# == dsh-ui-plc-source
- id: ui-plc-source
name: dsh-ui-plc-source
# == dsh-ui-tia-console
- id: ui-tia-console
name: dsh-ui-tia-console
# == @voltarenyah/dsh-tia-todo-bridge
- id: tia-todo-bridge
name: '@voltarenyah/dsh-tia-todo-bridge'
# == dsh-ui-versions
- id: ui-versions
name: dsh-ui-versions
# == dsh-ui-changes
- id: ui-changes
name: dsh-ui-changes
# == dsh-ui-hardware
- id: ui-hardware
name: dsh-ui-hardware
# == dsh-ui-prompt-guide
- id: ui-prompt-guide
name: dsh-ui-prompt-guide
# == dsh-ui-project-dashboard
- id: project-dashboard
name: dsh-ui-project-dashboard
# == dsh-opencode-go
- id: opencode-go
name: dsh-opencode-go
带上 §8.1 的政策层后,行数见根 AGENTS.md §4 的权威基线表(本蓝图改成三个 preset、加上
dsh-opencode-go 后重测)。比官方 web 组合多出的部分包括全局 system-prompt 覆盖行、
agent-preset-registry 覆盖行、preset-leader 那一整块工具清单、preset-auditor 与
preset-expert 的小清单,并且多出:
- id: agent-preset-registry
config:
default: leader
- id: preset-leader
name: '@deepseek-ai/dsh-agent-preset'
- id: preset-auditor
name: '@deepseek-ai/dsh-agent-preset'
- id: preset-expert
name: '@deepseek-ai/dsh-agent-preset'
- id: engineering-context
disabled: true
# 目录选择器:关掉 auto 行,换成 browse 的一对(见 §8.1 的说明)
- id: directory-picker
name: '@deepseek-ai/dsh-host-directory-picker-auto'
disabled: true
- id: directory-picker-browse
name: '@deepseek-ai/dsh-host-directory-picker-browse'
- id: directory-picker-browse-surface
name: '@deepseek-ai/dsh-client-ui-directory-picker-browse'
想在不改动任何环境的前提下预览政策层,用 --patch 叠加(--dump-config 不会挂载插件):
dsh --profile web --patch .\profile\dsh-automation-suite\cordis.patch.yml --dump-config
更强的一条是 dsh --profile <p> --dump-config-schema:输出里出现该插件的 Config 字段
(如 opennessDir、destructivePolicy),说明模块被真实 import 并读取了 schema。
注意
--dump-config-schema在未装任何插件的官方webprofile 上也返回 exit 1 —— 那 4 条unrecognized Loader tree carrier错误落在官方dsh-agent-preset的行上 (/179–/182),与插件无关,不要当成插件问题去查。
装 tarball 的验收链路:
cd packages/<pkg>; pnpm pack
dsh plugin --profile <临时 profile> add <tarball>
dsh --profile <临时 profile> --dump-config # 含你的插件行 = 通过了
启动后的运行期验收:见 §7.6(token URL、端口监听、
TiaOpennessV17Min.Controller 子进程)。
12. 故障排查
TIA 排障第一步永远是让模型调:
{ "include_controller_output": true } // controller_status:进程状态、exe 路径、Openness 探测、用户组、最后错误
| 症状 / 错误码 | 含义与处理 |
|---|---|
openness_unavailable |
找不到 Siemens.Engineering.dll:确认 TIA Portal V17 已装,或用 opennessDir 指定 |
openness_load_failed |
DLL 存在但不可用(位数不符/依赖缺失):确认 x64 与安装完整性 |
project_not_open / project_already_open |
需要先 open_project / 先 close_project |
project_open_failed |
打开失败(多为旧版本项目):需要 allow_upgrade |
plc_software_not_found / plc_software_ambiguous |
传 device_name / software_name 指定 |
block_not_found |
块不存在,details.available 给出项目里的块清单 |
verification_failed |
写后读回验证未通过(data 仍含已发生的写入与验证报告)—— 不要盲目重试 |
transaction_failed |
拿不到独占访问(可能有另一个 Openness 客户端在改项目) |
controller_not_found |
找不到控制器 exe:npm run build:controller 或配 controllerPath |
controller_timeout |
超过 requestTimeoutMs,控制器已被终止,TIA 会话丢失,下次调用自动重启;先把超时调大 |
controller_busy |
排队超过 maxQueue:有长操作在跑,等它结束 |
controller_protocol_mismatch |
exe 与插件版本不匹配:用同一份仓库重新构建 |
| 端口被占用 | 换 -Port,或加 -Restart 停掉旧实例(占用者不是 DeepSeek Harness 时不会动它) |
| 裸地址 401 | 必须用 dsh 打印的带 token 的 URL;token 每次启动都换、不落盘 |
| 会话里看不到 TIA/git 工具 | 插件没加载:查 --dump-config 是否有对应行;patchReload 不是 live 时要重启 |
13. 已知边界
- TIA 插件只做块、PLC 数据类型(UDT)与标签表:
export_blocks/import_blocks用categories选择blocks(默认)/types/tag_tables。硬件组态、在线下载/上传、比较、库、 多用户、HMI 等未实现;逐条覆盖情况见packages/dsh-tia-openness-v17-min/docs/coverage-matrix.html(391 条能力条目,随代码自动重新生成)。 - 真实项目里的块不一定都能导出:ProDiag 语言块与 Safety(F-) 块被 TIA 直接拒绝,
控制器逐块报告(
data.failures[])并继续。 - 导入必须指定块原来所在的组(
target_group),且"导入后重新导出"要放在编译之后; 见docs/FUNCTIONAL-TEST.md§8.5。 - 一次一个宿主进程一个 TIA Portal 会话:不同 DSH 会话共用同一个控制器并排队。
- 超时即丢失会话:Openness 不可取消,超时的唯一可靠处理是终止控制器;
被强杀时由控制器启动的 TIA Portal 进程可能仍然驻留(它是独立进程,插件绝不杀它),
请用
close_project(close_portal: true)正常收尾。 - 待人工验证的两项(需要人在界面/真实环境操作):运行中实例里的 HMR disposer 路径
(界面里禁用/启用插件,看子进程被停掉并重启),以及 V18+ 的 Openness 应用白名单策略
(本机 V17 未触发拦截)。详见
docs/verification.md§B。 - Git 闸门是策略护栏,不是沙箱:见 §4.3。
14. 安全红线
以下每一条都有真实事故记录(见 packages/dsh-tia-openness-v17-min/docs/ECOSYSTEM-COMPAT.md):
- ❌ 禁止用
rm -rf/Remove-Item -Recurse/ .NETDirectory.Delete等会跟进 junction/symlink 目标的递归删除去清node_modules或 profile 目录。这类删除毁过源仓库的.git元数据。 - ❌ 禁止在根
package.json里声明@deepseek-ai/*(或任何 DSH 运行时包)为依赖 —— 它们由 profile 的运行时解析提供。 - ❌ 禁止去掉根
package.json的private。 - ✅ 拆 junction 只用
cmd /c rmdir "<路径>"(只删链接本身)或Remove-Item -Force(不加-Recurse)。 - ✅ 清构建产物用
pnpm run clean:build:它只检查lib/、dist/,遇链接只 unlink、不下降。 - ✅ 用
-Reset或手删独立DSH_HOME时必须用cmd /c rmdir /s /q:里面link:与 pnpm 的 junction 指向仓库和 pnpm store,跟进式递归删除会毁掉目标。 - ✅ 重新链接运行时用
pnpm --filter <pkg> run link:runtime -- --force:目标若是链接只 unlink,不下降。
15. 许可证与第三方
本仓整体以 MIT 授权(仓库根 LICENSE),覆盖本仓原创的部分:
profile/ 蓝图、scripts/ 工具与本文档。随包出货的第三方内容保留各自条款:
| 组件 | 许可证 | 说明 |
|---|---|---|
dsh-automation-suite(本仓) |
MIT(根 LICENSE) |
蓝图、Monorepo 脚本、文档;根 package.json 已声明 "license": "MIT" |
@voltarenyah/dsh-tia-openness-v17-min |
MIT(包内 LICENSE) |
本仓原创代码 |
dsh-tool-git |
MIT(包内 LICENSE) |
上游 lxj808624/dsh-tool-git v0.1.3(commit 2347e3d)的压平 vendor 副本;包名刻意保持上游的 dsh-tool-git(不加 scope),因此不能以同名发布到 npm |
| Siemens Openness skill 集 | MIT | 上游 siemens/tia-portal-ai-extensions commit b5c7041 的逐字文档副本(31 个文件,已改代码一行未取),附上游许可证全文与逐文件 sha256 |
| Siemens NuGet 运行库 | Siemens 自有条款 | controller/bin/ 随插件分发 Siemens 解析器及其 5 个依赖(约 889 KB,未做任何修改);Siemens.Engineering.dll 从不被本仓分发(引用包 CopyLocal=false),始终来自用户自己的 TIA Portal 安装。完整清单与合规姿态见 packages/dsh-tia-openness-v17-min/THIRD_PARTY_NOTICES.md |
dsh-tool-git 与本仓的差异(包名策略、运行期链接方式、neverBundle、新增脚本)记录在
packages/dsh-tool-git/AGENTS.md,与上游同步时的"四处保留差异"也在那里。
16. 文档索引
| 文档 | 内容 |
|---|---|
docs/vision.md |
愿景:PLC 项目为何对 LLM 不可达、三层方案(接入 / 语义 / 管理)各自的职责与接口、贯穿各层的设计原则、术语与非目标 |
docs/architecture.md |
目标架构:接口插件族与两个工程插件的职责、期望与边界,三条正交轴,数据流,插件间契约与依赖顺序 |
docs/decisions.md |
决策记录(发行版级):已定的 12 条取舍(能力分层、workspace 模型、指纹变更识别、对象身份、图底座、工程上下文插件的状态落点…)与 5 项待验证 |
docs/open-questions.md |
开放问题(38 条):A 部分 20 条会阻塞动手(含 A14–A20 工具面与参考项目问题),B 部分 18 条影响细节与验收口径;已答 20 条 |
docs/roadmap.md |
路线图与现状:按插件逐项记录进度、缺口、验收口径 |
docs/tia-version-members.md |
接口插件族的多成员形态(V17 / V18 如何共存与替换):为什么同一时刻只能激活一个、为什么激活单位是 bundle 开关而不是逐行开关、先到先占互斥、内部缝的 version 比对、工具行「认错就空转」、跨版本契约清单、重启原因、doctor 三条检查、V18 落地清单与待实测项(D36) |
docs/tool-surface.md |
工具面重设计(调研 + 提案):现状体检(26 工具 1:1、20 行渲染上限、~14k tokens 常驻目录)、用户工作流清单、目标工具面与返回契约、从哪一步开始 |
docs/ui-plugins.md |
Web GUI UI 插件:客户端插件加载机制(含端到端实测)、基座模块表、座位目录、source/ 数据面、以「工程块树」为例的落地设计与客户端打包配方 |
docs/ui-plugins-plc-blocks-plan.md |
dsh-ui-plc-source 的实施计划与验收记录:规格、数据面(清单平铺 + device/类型筛选)、降级、构建、接线、实测结果 |
docs/ui-changes-panel-plan.md |
Changes 面板(P1 已落地:真实 git 状态,提交区未做):右侧栏未提交变更视图 + 提交工作流;数据路线对比(只读路由 / 派生快照 / 新 Remote)、git 解析边界、提示词模板、安全红线、分阶段验收与 P0/P1 实测记录 |
packages/dsh-ui-changes/README.md |
右侧栏 Changes 标签页:状态、只读路由与 trust fence、数据链路(会话 → cwd → gitContext)、构建与接线 |
packages/dsh-ui-plc-source/README.md |
右侧栏 PLC Blocks 标签页的用法、构建(tsc + esbuild)与安装位置 |
packages/dsh-ui-versions/README.md |
右侧栏 Versions 标签页:它读的那份派生视图、面板结构、宽度与主题、构建与接线 |
packages/dsh-ui-prompt-guide/README.md |
主栏 Prompt Guide 整页:sidebar.panellist + main 的注入方式、内容怎么改、宿主静态路由与 trust fence 的边界 |
packages/dsh-engineering-context/README.md |
工程上下文插件的用法、配置与开发命令(S2 已实现:创建 + 状态 + 同步) |
packages/dsh-engineering-context/docs/ |
该插件的设计与取舍:ARCHITECTURE.md(核心架构、作用域模型、版本管理、工具面)、PATH-RULES.md(workspace 内路径规则与账本/清单)、decisions.md(编号决策 D1–D26) |
docs/distribution.md |
公开发行与安装:DSH 的安装面实测(dsh plugin 的 spec 形式、bundle 对账、patch 语义、pnpm 11 的两个错误)、三种打包方案对比、Release 发布步骤与验收记录 |
docs/releases.md |
发布台账与流程:已发布版本表(0.1.0–0.1.5)、tag 偏移的已知问题、版本规则、发布检查清单与常见错误 |
CHANGELOG.md |
发行版版本摘要:0.1.0–0.1.5 的能力变化;插件版本与 DSH 版本独立 |
docs/desktop-packaging.md |
桌面壳与打包方案(Phase 1 壳、Phase 2c 安装器/DSH/WebView2 bootstrap 已实现并在干净 Win11 LTSC VM 验收通过):WebView2 独立窗口、预装或安装时联网下载 DSH、Inno 安装器、固定 profile、无签名策略、产物/目录/失败处理/验收清单与分阶段工作量 |
profile/dsh-automation-suite/README.md |
蓝图的组成、三种部署方式、验收方式 |
packages/dsh-tia-openness-v17-min/README.md |
TIA 插件的完整说明(验证状态、协议、工具、错误码、V17 API 要点) |
packages/dsh-tia-openness-v17-min/docs/ |
PROTOCOL.md(线路协议权威描述)、decisions.md(技术取舍)、REAL-RUN.md(真实项目实测)、FUNCTIONAL-TEST.md、verification.md(验证清单)、ECOSYSTEM-COMPAT.md(生态兼容与事故记录) |
packages/dsh-tool-git/README.md · README.zh.md |
git 插件的工具表、安全闸门、安装与配置 |
packages/dsh-tool-git/AGENTS.md |
这个 vendor 副本与上游的差异、运行期链接、neverBundle |
packages/dsh-tia-openness-v17-min/AGENTS.md |
覆盖矩阵与知识库的同步规则 |
AGENTS.md |
仓库级约定:结构、命名、危险操作红线、验收口径 |
LICENSE |
本仓 MIT 许可证;随包出货/ vendor 内容的条款归属见 §15 |
No comments yet. Be the first to write one.