cyf/lserp_cs_6.0

Fork 0

Files

T

郎速科技 4c08f4c948 feat: add ERP agent pet bridge and startup guide

2026-08-14 14:28:28 +08:00

12 KiB

Raw Permalink Blame History

朗速 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 的工作目录执行（账号、密码不要写入命令行或文档）：

git clone http://192.168.0.7:4133/cyf/lserp_cs_6.0.git
Set-Location .\lserp_cs_6.0
git checkout main

确认当前工作树没有同事未提交的改动：

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，不要直接升级到其他版本：

# 在 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. 先跑离线检查（不连接客户数据库）

源码根目录执行：

# 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 上发布自包含目录：

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 前由同一进程环境设置：

复制 插件库/Lskj.AgentBridge/Deployment/command-rollout.example.json 到包外受 ACL 保护的目录。
将 customerId、databaseScopeFingerprint、accountBooks.values 和 subSystemIds.values 替换为本次已批准会话的真实值。
保持 defaultAction 为 deny，只保留需要联调的只读命令（例如 module.search、module.parameters、管理员只读的 module.diagnose）。不要加入 *.create、*.execute、*.submit 或动态写入命令。
用原始文件计算 SHA-256，并在启动 ERP 前设置环境变量：

$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，可在不执行业务写入的情况下运行：

.\lserp-cli.exe doctor --ledger '<账套显示名>'

将输出中的 databaseScopeFingerprint 与当前登录的 ERP PID、用户编号、用户名、账套、子系统编号、管理员状态一起记录到受控交接单。若没有经批准的交接单，不要用 lserp_AI、服务器地址或数据库名自行推导指纹。

6. 用受限 CLI 做只读冒烟

下面的 $scope 是同一次人工核准会话的七项范围；每条命令都必须完整展开，不能只传 PID：

$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，并通过完整签名/合规预检。源码联调若尚未具备商用证据，仍需手工向宿主提供以下环境变量；宿主会自行校验令牌，缺任一项都会失败关闭：

$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 的完整命令执行。直接双击宿主、只填 PID、把 API Key 写在命令行，都会被拒绝。

8. 聊天和图片冒烟用例

桌宠显示后，先测试只读问题：

“当前界面是什么模块？有哪些可用功能？”
“当前模块新增需要哪些参数？哪些字段必填？”
管理员会话下：“这个模块初始化报错，先给我只读诊断结论。”

图片测试使用 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 日志。

更完整的安全边界和商用验收要求见：

12 KiB Raw Permalink Blame History Unescape Escape