AI-governance-framework/00-框架治理_maintainers-only/06-中央飞书发送器

中央飞书反馈发送器（Windows PowerShell）

本目录仅用于框架维护端部署在公司云服务器，绝不进入项目使用包。它使用 Windows PowerShell 和 .NET，不依赖 Python，也不需要重启服务器或重启 Nginx。

部署边界

• CentralFeedbackServer.ps1 仅监听 http://127.0.0.1:9010/。
• Nginx 对公网暴露已存在域名下的 /framework-feedback/，并代理至本机端口；/framework-feedback/health 可用于无敏感公网连通性检查。
• App ID、App Secret、固定群 chat_id 仅写入云服务器的 DPAPI 加密配置，不能出现在仓库、项目包、Nginx 配置、日志或聊天中。
• 当前为内部试运行的无项目凭证模式：项目端可直接调用公网 HTTPS 接口。Nginx 限流、请求体大小、Markdown 文件边界与项目端“负责人授权、脱敏检查”仍然生效；任何获得接口地址的人都可能尝试向反馈群投递文件，框架维护者必须定期审查审计日志，并在需要时恢复项目凭证校验。
• 接口只接收 Markdown 反馈记录，原文件不落盘；审计日志仅保留项目编号、版本、文件哈希、触发 Hook、发送时间和飞书 message_id。
• 项目端负责正式 Hook、负责人授权、脱敏和版本规则；中央接口仅校验项目凭证、非空审计字段、Markdown 文件名、大小与请求体边界，避免格式差异阻断正常自动发送。

服务器执行顺序

1. 在服务器创建 E:\FrameworkFeedbackSender，将本目录中的脚本复制进去。
2. 使用将运行发送器的同一个 Windows 账户，在该目录执行：

   .\Initialize-CentralFeedbackServerConfig.ps1 -AppId '<App ID>' -ChatId '<chat_id>'

脚本会弹出 Windows 密码输入框；在框内粘贴 App Secret。密码框会遮蔽内容，关闭后仅将其加密保存到服务器。不要将三个值发送到聊天。

如需先确认远程桌面的密码输入框，执行 ./Initialize-CentralFeedbackServerConfig.ps1 -VerifyInteractiveInput，在弹框中输入 TEST-123。该模式不会读取、保存或修改任何配置。

1. 如未来恢复按项目鉴权，可对每个项目生成一次提交密钥：

   .\Register-CentralFeedbackProject.ps1 -ProjectId 'PROJ-001'

它会只显示一次提交密钥。当前无项目凭证模式不需要执行这一步；恢复鉴权后，凭证应通过受控私密方式配置到项目电脑的运行环境，且不得提交 Git。

1. 先在服务器本地前台启动并观察：

   .\CentralFeedbackServer.ps1

用另一个 PowerShell 窗口验证 Invoke-WebRequest http://127.0.0.1:9010/health -UseBasicParsing 返回 200。按 Ctrl+C 停止前台进程。

1. 将 nginx.framework-feedback.conf.example 的 location 合并进现有 HTTPS server {} 块，并在 http {} 块添加一次 limit_req_zone。先运行 nginx -t，仅在通过后运行 nginx -s reload。
2. 最后以同一 Windows 账户创建“开机时启动”的任务计划，任务动作为：

   powershell.exe -NoProfile -File E:\FrameworkFeedbackSender\CentralFeedbackServer.ps1

当前不需要重启服务器；可立即手动启动任务并验证。服务器以后自然重启时，任务会自动恢复服务。

当前前台运行方式：停止与重新启动

在尚未配置任务计划期间，发送器由运行 CentralFeedbackServer.ps1 的 PowerShell 窗口维持。关闭该窗口或在窗口中按 Ctrl+C 都会停止发送器；这不会重启服务器或 Nginx，但公网反馈接口会暂时不可用。

如需在同一个 Windows 账户下重新启动：

1. 先确认旧的发送器窗口已停止；不要同时启动两个实例。
2. 打开管理员 PowerShell，执行：

   Set-Location 'E:\FrameworkFeedbackSender'
   .\CentralFeedbackServer.ps1

1. 保持该窗口打开；另开一个 PowerShell 验证：

   Invoke-WebRequest 'http://127.0.0.1:9010/health' -UseBasicParsing

返回 200 与 {"status":"ok"} 后，发送器即恢复。若端口已被占用，应先核实是否已有正常实例正在运行，不要直接结束未知业务进程。

任务计划配置完成后，应优先通过“任务计划程序”启动、停止或重启对应任务，而不是再手动运行第二个 PowerShell 实例。

一键飞书投递自检

在首次部署、飞书应用凭据更新或故障排查时，可在服务器以初始化配置所用的同一 Windows 账户执行：

Set-Location 'E:\FrameworkFeedbackSender'
.\Test-CentralFeedbackSender.ps1

该命令会向固定反馈群发送一份 CENTRAL-SENDER-SELF-TEST.md 测试文件，用于验证“服务器解密配置 → 飞书取 Token → 上传文件 → 群文件消息”的链路。测试文件不含项目数据，脚本不会显示 App Secret、群 ID 或 Token；当前前台发送器无需停止。

这项自检不替代项目端的正式提交测试；项目端测试仍必须使用项目自己的提交凭证、正式 Hook、负责人授权和脱敏后的反馈记录。

如需验证公网入口和飞书投递的完整链路，可执行：

Set-Location 'E:\FrameworkFeedbackSender'
.\Test-CentralFeedbackEndpoint.ps1 -Endpoint 'https://<existing-domain>/framework-feedback' -ProjectId 'TEST-FEEDBACK-001'

脚本会发送一份不含业务数据的测试文件。当前无项目凭证模式不需要输入提交密钥；接口拒绝元数据时，服务端只返回未通过的字段名，不返回字段值、文件内容或任何凭据。

运行与故障边界

• 任务计划运行账户必须与初始化 DPAPI 配置的账户一致，否则无法解密服务端凭据。
• 不要使用 -ExecutionPolicy Bypass 绕过公司终端策略；若策略阻止运行，应由终端管理员批准该受控脚本。
• Nginx reload 不是服务器重启；若 nginx -t 不通过，不执行 reload。
• 当飞书调用失败时，接口只返回通用失败类别；项目主 Agent 必须登记未自动发送，并提示负责人手动发送同一文件。