feat: add ERP agent pet bridge and startup guide

2026-08-14 14:28:28 +08:00
parent a803070819
commit 4c08f4c948
252 changed files with 134752 additions and 72 deletions
@@ -0,0 +1,208 @@
+# 朗速 ERP 智能桌宠：同事启动指南
+
+本文面向从 Git 拉取源码后进行 Windows 联调的同事。当前仓库默认是“只读/计划预览”联调，数据库写入、采购发票落库、请假提交和通用低代码新增都不会因为安装插件而自动开启。
+
+## 先看结论
+
+- 桌宠、AstrBot 插件和 `lserp-agent-cli.exe` 不直接连接 SQL Server，也不接收数据库密码。它们必须绑定到同一台 Windows 上已经登录的 `Ls_ERP.exe` 进程。
+- 每一次桥调用都必须同时传入七项 ERP 会话范围：ERP PID、数据库作用域指纹、用户编号、用户名、账套、子系统编号、管理员状态。只传 PID 或把数据库名写进自然语言都不受支持。
+- `lserp_AI` 只读画像是联调参考材料，不是生产授权；`business-adapters.example.json` 中采购/请假均保持 `enabled=false`，不要直接改成 `true`。
+- MiniMax Key 只放在 AstrBot 服务账号的秘密管理器中。不要把 Key、ERP 密码、连接串或客户数据提交到 Git。
+- 商用启动器还要求签名、guga 素材授权、AstrBot/MiniMax 合规证据和旧版 ERP 构建产物。没有这些材料时，可以运行自动化测试和只读桥联调，但不应声称“已商用就绪”。
+
+## 1. 获取代码
+
+在 Windows 的工作目录执行（账号、密码不要写入命令行或文档）：
+
+```powershell
+git clone http://192.168.0.7:4133/cyf/lserp_cs_6.0.git
+Set-Location .\lserp_cs_6.0
+git checkout main
+```
+
+确认当前工作树没有同事未提交的改动：
+
+```powershell
+git status --short
+git log -1 --oneline
+```
+
+## 2. 环境要求
+
+### Windows 桌面联调
+
+- Windows 10/11 x64。
+- Visual Studio 2022（含 .NET Framework 4 targeting pack、桌面开发工作负载）用于旧 ERP/管理员 CLI。
+- .NET 8 SDK（桌宠宿主和桥 CLI）；.NET 6 SDK（CommandKernel 测试）。
+- Microsoft Edge WebView2 Evergreen Runtime `151.0.4129.50` 或更高版本。
+- PowerShell 7；商用验收脚本另外要求 Windows PowerShell 5.1。
+- 同一 Windows 用户下运行 AstrBot、`Ls_ERP.exe` 和桌宠宿主；当前版本不支持远程 AstrBot。
+
+### AstrBot
+
+使用已审核的 AstrBot `4.27.2`，不要直接升级到其他版本：
+
+```powershell
+# 在 AstrBot 实例目录执行，路径按实际安装位置调整
+Copy-Item -Recurse -Force `
+  .\astrbot_plugin_lserp `
+  .\AstrBot\data\plugins\astrbot_plugin_lserp
+
+& .\AstrBot\.venv\Scripts\python.exe -m pip install `
+  --require-hashes `
+  -r .\AstrBot\data\plugins\astrbot_plugin_lserp\requirements.txt
+```
+
+在 AstrBot 管理界面配置一个只授予 `chat + file` 的本机 API Key，并把 MiniMax Key 注入 AstrBot 服务账号的秘密存储。桌宠进程不应继承 `MINIMAX_API_KEY`。
+
+## 3. 先跑离线检查（不连接客户数据库）
+
+源码根目录执行：
+
+```powershell
+# CommandKernel 单元/契约测试
+dotnet run `
+  --project .\插件库\Lskj.CommandKernel.Tests\Lskj.CommandKernel.Tests.csproj `
+  -c Release --no-restore
+
+# 部署脚本和商用合同的正负例检查
+pwsh -NoProfile `
+  -File .\插件库\Lskj.AgentBridge\Deployment\CommercialPackage\Test-DeploymentContracts.ps1 `
+  -RepoRoot (Get-Location)
+
+# AstrBot 插件离线测试（unittest 的工作目录必须是插件根目录）
+$astrBotPython = 'C:\\Langsu\\AstrBot\\.venv\\Scripts\\python.exe'
+Push-Location .\插件库\astrbot_plugin_lserp
+& $astrBotPython -m unittest discover -s tests -v
+Pop-Location
+```
+
+当前基线应看到 CommandKernel `294 passed`、部署合同 `79 passed`；AstrBot 测试数量以该提交的实际输出为准。任一测试失败先停在源码/依赖问题，不要连接客户库排查。
+
+## 4. 构建桌宠和受限桥 CLI
+
+在 Windows x64 上发布自包含目录：
+
+```powershell
+dotnet publish .\插件库\Lskj.AgentPet.Host\Lskj.AgentPet.Host.csproj `
+  -c Release -r win-x64 --self-contained true `
+  -p:PublishProfile=WinX64
+
+dotnet publish .\插件库\Lskj.BridgeCli\Lskj.BridgeCli.csproj `
+  -c Release -r win-x64 --self-contained true `
+  -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true
+```
+
+宿主发布目录必须包含 `Lskj.AgentPet.Host.exe`；桥 CLI 的文件名应为 `lserp-agent-cli.exe`。宿主还要求一份经书面授权的 `1536×1872` 静态 WebP 精灵图，路径通过 `LSERP_PET_SPRITE_PATH` 指定。不要在客户生产机临时执行 `npx codex-pets add guga`；npm 包的许可证不等于精灵图的商用授权。
+
+## 5. 配置 ERP 只读桥
+
+桥是在 ERP 启动时创建的命名管道，必须在启动 `Ls_ERP.exe` 前由同一进程环境设置：
+
+1. 复制 `插件库/Lskj.AgentBridge/Deployment/command-rollout.example.json` 到包外受 ACL 保护的目录。
+2. 将 `customerId`、`databaseScopeFingerprint`、`accountBooks.values` 和 `subSystemIds.values` 替换为本次已批准会话的真实值。
+3. 保持 `defaultAction` 为 `deny`，只保留需要联调的只读命令（例如 `module.search`、`module.parameters`、管理员只读的 `module.diagnose`）。不要加入 `*.create`、`*.execute`、`*.submit` 或动态写入命令。
+4. 用原始文件计算 SHA-256，并在启动 ERP 前设置环境变量：
+
+```powershell
+$rollout = 'C:\ProgramData\Langsu\AgentBridge\command-rollout.readonly.json'
+$env:LSERP_AGENT_BRIDGE_ENABLED = '1'
+$env:LSERP_AGENT_ROLLOUT_CONFIG = $rollout
+$env:LSERP_AGENT_ROLLOUT_SHA256 = (Get-FileHash -Algorithm SHA256 $rollout).Hash.ToLowerInvariant()
+$env:LSERP_AGENT_ROLLOUT_CUSTOMER_ID = 'COLLEAGUE-UAT'
+
+# 仅在需要读取低代码模块参数、且已完成人工复核时设置；保持采购/请假 enabled=false
+$env:LSERP_BUSINESS_ADAPTER_CONFIG = 'C:\ProgramData\Langsu\AgentBridge\business-adapters.readonly.json'
+
+Start-Process 'C:\Langsu\ERP\Ls_ERP.exe' -WorkingDirectory 'C:\Langsu\ERP' -Wait
+```
+
+ERP 登录完成后，核对发现目录 `%LOCALAPPDATA%\Langsu\Lserp\AgentBridge` 中出现与该 PID 对应的 `agentbridge-<PID>.json`。没有发现文件时，先检查启动环境、发布策略 SHA-256 和 ERP 日志；不要修改代码绕过门禁。
+
+### 如何取得七项范围
+
+范围必须来自实施人员核准的当前 ERP 会话或只读会话交接，不能猜测。数据库作用域指纹不是数据库名：它绑定配置端点、实际连接端点、实际数据库和提供者。若已有管理员 CLI，可在不执行业务写入的情况下运行：
+
+```powershell
+.\lserp-cli.exe doctor --ledger '<账套显示名>'
+```
+
+将输出中的 `databaseScopeFingerprint` 与当前登录的 ERP PID、用户编号、用户名、账套、子系统编号、管理员状态一起记录到受控交接单。若没有经批准的交接单，不要用 `lserp_AI`、服务器地址或数据库名自行推导指纹。
+
+## 6. 用受限 CLI 做只读冒烟
+
+下面的 `$scope` 是同一次人工核准会话的七项范围；每条命令都必须完整展开，不能只传 PID：
+
+```powershell
+$scope = @(
+  '--erp-process-id', '<ERP PID>',
+  '--expected-database-scope-fingerprint', '<64位小写SHA-256>',
+  '--expected-user-id', '<用户编号>',
+  '--expected-user-name', '<用户名>',
+  '--expected-account-book', '<账套>',
+  '--expected-subsystem-id', '<子系统编号>',
+  '--expected-is-administrator', 'false'
+)
+
+.\lserp-agent-cli.exe version
+.\lserp-agent-cli.exe bridge health @scope
+.\lserp-agent-cli.exe bridge context @scope
+.\lserp-agent-cli.exe workflow capabilities @scope
+```
+
+预期结果是 JSON。`bridge context` 只能返回当前会话投影；看到 `erp_session_scope_changed`、`erp_database_session_changed`、`erp_bridge_instance_changed` 时，停止操作，重新登录 ERP 并重新生成会话范围，不要重试旧计划。
+
+## 7. 启动桌宠
+
+正式商用启动必须使用 `Deployment/CommercialPackage/Start-LserpAgentPet.ps1`，并通过完整签名/合规预检。源码联调若尚未具备商用证据，仍需手工向宿主提供以下环境变量；宿主会自行校验令牌，缺任一项都会失败关闭：
+
+```powershell
+$env:LSERP_ASTRBOT_BASE_URL = 'http://127.0.0.1:6185'
+$env:LSERP_ASTRBOT_CREDENTIAL_TARGET = 'Langsu.Lserp.AstrBot.ApiKey'
+$env:LSERP_AGENT_BRIDGE_PROCESS_ID = '<ERP PID>'
+$env:LSERP_AGENT_EXPECTED_DATABASE_SCOPE_FINGERPRINT = '<64位小写SHA-256>'
+$env:LSERP_AGENT_EXPECTED_USER_ID = '<用户编号>'
+$env:LSERP_AGENT_EXPECTED_USER_NAME = '<用户名>'
+$env:LSERP_AGENT_EXPECTED_ACCOUNT_BOOK = '<账套>'
+$env:LSERP_AGENT_EXPECTED_SUBSYSTEM_ID = '<子系统编号>'
+$env:LSERP_AGENT_EXPECTED_IS_ADMINISTRATOR = 'false'
+$env:LSERP_AGENT_BRIDGE_DISCOVERY = "$env:LOCALAPPDATA\Langsu\Lserp\AgentBridge"
+$env:LSERP_PET_SPRITE_PATH = 'C:\SecureAssets\guga\spritesheet.webp'
+```
+
+`LSERP_ASTRBOT_SESSION_ID` 和 `LSERP_AGENT_EXPECTED_SESSION_SCOPE_TOKEN` 必须由受控启动器根据上述六项范围和 ERP 进程启动时间生成，不能手工编造。开发联调建议直接使用已构建包的启动器；商用场景按 [CommercialPackage/README.md](Deployment/CommercialPackage/README.md) 的完整命令执行。直接双击宿主、只填 PID、把 API Key 写在命令行，都会被拒绝。
+
+## 8. 聊天和图片冒烟用例
+
+桌宠显示后，先测试只读问题：
+
+1. “当前界面是什么模块？有哪些可用功能？”
+2. “当前模块新增需要哪些参数？哪些字段必填？”
+3. 管理员会话下：“这个模块初始化报错，先给我只读诊断结论。”
+
+图片测试使用 PNG/JPG/WebP/PDF/XLSX/UTF-8 CSV，最多 3 个文件、单个不超过 12 MB、总计不超过 36 MB。先发一张无客户数据的合成图片，确认 AstrBot 返回结构化识别结果；再在获得客户书面批准的 UAT 环境测试发票。图片识别失败时应停在 `attachment_preprocess_required`、`vision_*` 或 `document_*` 稳定错误，不得把模型自由文本当作 ERP 字段。
+
+当前版本没有开放“聊天直接落库”冒烟。采购发票、请假和通用低代码写入需要独立字段映射、固定 SQL/原生保存事务、权限、幂等、审计、UAT 授权和签名证据，流程见 `Deployment/CUSTOMER_ACCEPTANCE.md` 与 `Deployment/WRITE_ACCEPTANCE.md`。
+
+## 9. 常见问题
+
+| 现象 | 先检查 |
+| --- | --- |
+| `astrbot_session_process_binding_required` | 未使用启动器，或会话 ID 没有绑定 PID/启动时间/作用域令牌。 |
+| `bridge_session_scope_token_mismatch` | 七项范围来自不同登录会话，或指纹/管理员状态有一项不一致。 |
+| 没有 `agentbridge-<PID>.json` | ERP 启动时未继承 `LSERP_AGENT_BRIDGE_ENABLED=1`，或 rollout 文件/哈希/客户 ID不匹配。 |
+| `command_rollout_denied` | 只读发布策略没有放行该命令，或 ERP 当前用户本身没有权限。 |
+| 宿主提示 WebView2/精灵图错误 | 安装 WebView2 `151.0.4129.50+`，并确认素材为已授权、完整的 `1536×1872` WebP。 |
+| 图片请求提示 Key/区域错误 | 在 AstrBot 服务账号配置轮换后的 MiniMax Key 和正确 `global`/`cn` 区域；不要把 Key 放到桌宠环境。 |
+
+## 10. 停止与反馈
+
+结束联调时先退出桌宠，再正常退出 ERP；不要删除仍在运行实例的审计文件。反馈问题时只提供：提交号、稳定错误码、`correlationId`、测试命令和脱敏计数。不要上传 ERP 密码、MiniMax Key、数据库连接串、原始发票、员工请假原因或完整 SQL 日志。
+
+更完整的安全边界和商用验收要求见：
+
+- [AgentBridge README](README.md)
+- [桌宠宿主 README](../Lskj.AgentPet.Host/README.md)
+- [AstrBot 插件 README](../astrbot_plugin_lserp/README.md)
+- [商用包 README](Deployment/CommercialPackage/README.md)
+- [客户验收流程](Deployment/CUSTOMER_ACCEPTANCE.md)