# 朗速 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)