Codex/local admin

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## 变更说明
+
+说明具体问题、修改后的行为及本次范围。
+
+## 验证结果
+
+列出实际完成的检查；区分隔离验证、真实QQ及浏览器验证，说明必要的未验收范围。
+
+## 使用与兼容性
+
+说明使用文档入口、配置影响、是否需要重启及升级方式。
+
+## 限制与待办
+
+列出本次仍未解决或未验证的事项；若没有，写“无”。

.gitignore

@@ -1,12 +1,22 @@
-plugins/*.so
-plugins/*.dll
-.idea/
-.DS_Store
-.vscode
-go-zero*
-nohup.out
-zerobot
-ZeroBot-Plugin*
-*.syso
-/.direnv
-/result
+plugins/*.so
+plugins/*.dll
+.idea/
+.DS_Store
+.vscode
+go-zero*
+nohup.out
+zerobot
+ZeroBot-Plugin*
+*.syso
+/.direnv
+/result
+
+# Local Windows builds, credentials, logs and isolated runtime data.
+/.local/
+/plugin/*/data/
+/third_party/**/data/
+/internal/**/data/
+/kanban/data/
+
+# Local conversation notes are not part of usage/development documentation.
+/docs/local-notes/

AGENTS.md

@@ -0,0 +1,20 @@
+# 本项目协作约定
+
+用户要求：每个功能更新后同步更新使用文档；如果该功能没有使用文档，先创建。
+
+- 功能新增、行为修改和影响使用方式的修复，都应在本次交付中更新对应使用说明。
+- 通用使用入口为 `docs/local-admin/user-guide.md`，文档索引为 `docs/local-admin/README.md`；运行维护说明为 `docs/local-admin/operations.md`。
+- 新功能没有对应说明时，先创建使用文档，并在通用指南或索引中加入入口。日期化开发/测试记录不能替代使用步骤。
+- 使用说明应写清入口或命令、必要权限、作用范围、生效时机和实际限制；只描述已实现行为。
+- 更新开发进度、相关测试结果与未验收事项，区分自动化验证和真实 QQ 验收。仅修改文档时无需重启服务或重跑机器人测试。
+
+## 第一版 GitHub 交付约定
+
+- 用户已要求：第一版完成后更新到自己的 GitHub 仓库 `qiye-yuri/ZeroBot-Plugin`；第一版尚未完成时不提前发布，也不把模拟或部分验收写成完整验收。
+- 提交、PR及版本说明采用中文；提交按 `feat: 中文说明`、`fix: 中文说明`、`docs: 中文说明`、`test: 中文说明` 等类型组织，PR说明具体变化、验证结果与仍存在的限制。
+- 上传实现所需源码、构建/测试配置、依赖及使用和开发文档。对话逐字记录、聊天问答/会话摘要、临时调试资料和私有运行证据不上传；来源于对话但已整理为可复用使用/开发说明的内容可以保留。
+- 发布前逐项检查文件清单并显式暂存；不要用整个目录暂存把本机配置、密钥、QQ档案、截图或运行数据带入提交。公开文档使用示例身份和路径，保留必要的测试摘要与范围，真实QQ明细留在本机。
+- 不因文件按日期命名就自动排除使用或开发文档，也不删除本机对话资料来达到不上载的目的。发布前检查保留文档的链接与被排除文件之间的依赖。
+- 默认目标为用户自己的 `origin`，不向上游 `FloatTech/ZeroBot-Plugin` 推送或发PR。具体版本号和标签先与仓库既有版本核对，不能将“后台第一版”直接当作整个项目版本降为v0.1。
+- 中间交流、本机调查和原始开发记录统一保存在 `docs/local-notes/`，该目录整体忽略；公开文档只放 `docs/local-admin/`。
+- 完整步骤见 `docs/local-admin/github-delivery.md`。

CHANGELOG.md

@@ -0,0 +1,22 @@
+# 变更记录
+
+## 本地管理后台 v0.1 — 2026-10-13
+
+此版本号描述后台功能范围，项目主体仍沿用原有版本体系。
+
+### 新增
+
+- 本机管理后台：认证、运行概览、连接、插件、AI、日志与配置备份恢复。
+- 多连接及表单草稿保护、中文操作提示、深浅主题、小屏适配与文件导出。
+- Agent持久档案、模型/回复快照与资源观察及离线核对工具。
+- Windows服务管理、隔离回归入口和完整使用/开发文档。
+
+### 修复
+
+- AI配置与指令共享、保存冲突和失败保护、GPT引用及中文长回复处理。
+- 非主人Agent动作的当前群与权限边界，群语音重复发送及私聊向群生成的问题。
+- 热词等频绘图、启动资源请求阻塞、恢复后插件列表首次读取和本机首页导航。
+
+### 验证与限制
+
+自动化、实际浏览器与真实QQ验证按[第一版说明](docs/local-admin/release-v0.1.md)记录。部分真人Agent、客户端体验和真实持续负载验收已取消，未测项目不记作通过。运行配置和中间交流不随源码公开。

README.md

@@ -1,3 +1,11 @@
+## 本地机器人管理后台 v0.1
+
+本分支增加本机管理后台，支持连接、插件、AI、日志与配置备份。仅监听本机回环地址，默认端口为3010。
+
+[使用指南](docs/local-admin/user-guide.md) · [第一版说明](docs/local-admin/release-v0.1.md) · [开发与验证](docs/local-admin/self-test.md)
+
+---
+
 <div align="center">
   <img src=".github/hua_nobg_512.gif" alt="椛" width = "256">
   <img src="https://github.com/FloatTech/ZeroBot-Plugin/assets/41315874/93fb795d-e519-45a6-a654-076fd6ac54ae" alt="zbp-uwu" width = "400">

docs/local-admin/README.md

@@ -0,0 +1,28 @@
+# 本地机器人管理后台：使用与开发文档
+
+本地管理后台v0.1，Windows为首要验证环境；管理自己的单个ZeroBot-Plugin进程及已有多条OneBot连接。
+
+| 入口 | 用途 |
+| --- | --- |
+| [使用指南](user-guide.md) | 安装与启动、各后台页面、QQ命令、Agent和排障 |
+| [第一版说明](release-v0.1.md) | 功能、验证、限制及升级方式 |
+| [运行维护](operations.md) | 服务启停、配置生效、恢复与数据边界 |
+| [Windows OneBot](onebot-windows.md) | 本机NapCat安装、账号、连接与密钥配对 |
+| [AI配置检查](ai-config-check.md) | 接口类型/地址/密钥/模型与实际业务检查 |
+| [AI角色权限](ai-role-permissions.md) | 主人、群主、管理员和普通用户权限 |
+| [Agent验证](real-agent-acceptance.md) | 实际动作、回执、持久记忆与重启验证 |
+| [Agent档案](agent-history-2026-10-03.md) | 对话留存、重置、备份及模型请求容量 |
+| [群语音](qq-ai-voice.md) | QQ内置群AI语音与私聊限制 |
+| [识图](deepseek-vision.md) | 现有Agent图片描述流程与模型配置 |
+| [GPT引用](gpt-quoted-message.md) | 引用文字与本次要求分别处理 |
+| [响应与插件](response-status.md) | 全局/群响应规则与插件开关区别 |
+| [配置备份](backup-restore-2026-10-02.md) | 预览、确认、覆盖范围与恢复后重启 |
+| [统计与观察](combined-observation.md) | 模型、回复和资源资料独立与联合核对 |
+| [需求](requirements.md) | 范围、验收标准与设计 |
+| [开发进度](progress.md) | 第一版实现及已验证范围 |
+| [自测](self-test.md) | 复验入口与真实/隔离边界 |
+| [GitHub交付](github-delivery.md) | 中文提交/PR、文件筛选与中间记录排除 |
+
+功能细节由使用指南链接到对应说明。每次功能更新同步维护使用文档；没有对应说明时先创建。根目录[开发约定](../../AGENTS.md)同时适用。
+
+公开文档不包含本机QQ身份、凭据、截图、聊天明细或私有验收文件；中间交流与原始开发记录集中在被忽略的docs/local-notes，运行产物继续保存在.local。

docs/local-admin/admin-foundation-2026-10-01.md

@@ -0,0 +1,55 @@
+# 本地后台基础：启动与验证
+
+## 本机使用
+
+后台地址默认是 `http://127.0.0.1:3010/`。首次启动生成 `.local/admin/setup-code.txt`，在页面选择该文件，设置至少 12 个字符的后台密码即可进入。设置码成功使用后失效并删除；此密码与 QQ 登录分开，不能用 OneBot Token 登录。
+
+后台凭据仅保存随机盐与 PBKDF2-HMAC-SHA256 派生值（600,000 次），保存在 `.local/admin/credential.json`。会话存在内存中，有效期 8 小时；退出或重启后原会话失效。Windows 数据目录及凭据文件使用受保护的 DACL，仅当前用户与 SYSTEM 拥有访问权限。
+
+用独立计划任务宿主运行时，在项目根目录执行：
+
+```powershell
+# 开启本机后台；本操作不改机器人账号、昵称或 OneBot 配置
+.\scripts\configure-local-admin.ps1
+.\scripts\stop-local-services.ps1 -Service ZeroBot
+.\scripts\start-local-services.ps1 -Service ZeroBot
+
+# 关闭后台，保留原机器人启动方式；同样需重启 ZeroBot
+.\scripts\configure-local-admin.ps1 -Disable
+.\scripts\stop-local-services.ps1 -Service ZeroBot
+.\scripts\start-local-services.ps1 -Service ZeroBot
+```
+
+手动启动也可使用：
+
+```powershell
+.\.local\bin\zerobot.exe -c .local/config.json -admin -admin-addr 127.0.0.1:3010 -admin-data .local/admin
+```
+
+不传 `-admin` 时不会创建后台监听或读取后台凭据。地址只接受字面 IPv4 `127.0.0.1`；端口占用时明确报错并停止启动，不静默换端口。机器人无法连接 OneBot 时后台仍可加载并显示等待连接；概览标记的是 OneBot 传输连接，不替代 QQ 登录状态检查。
+
+## 接口约定
+
+| 接口 | 权限/作用 |
+| --- | --- |
+| `GET /api/session` | 只返回首次设置/登录状态；已登录时提供当前会话 CSRF 校验值 |
+| `POST /api/setup` | 本地设置码与新密码；只能在尚未初始化时使用 |
+| `POST /api/login` | 后台密码登录；每分钟最多五次失败尝试 |
+| `POST /api/logout` | 已登录并持有 CSRF 校验值，注销当前会话 |
+| `GET /api/overview` | 已登录；运行时间、构建信息、当前 OneBot 账号、连接及插件数量 |
+| `GET /api/plugins` | 已登录；已编译插件元数据及启动时默认状态 |
+
+全部接口仅接受回环来源及正确 Host，跨站 Origin/Fetch Metadata 被拒绝；写请求必须为同源 JSON 并带 `X-Local-Request: 1`，已登录写操作另需 `X-CSRF-Token`。Cookie 为 HttpOnly、SameSite=Strict；服务仅本机 HTTP，故不设置要求 HTTPS 的 Secure 标志。响应不缓存，不记录请求体或凭据。网页不把会话放入 URL/localStorage，不加载外部字体、头像、图标或脚本。
+
+静态服务只暴露内嵌的三个页面文件，不映射本地数据目录或备份。插件用法和名称作为文本节点展示。
+
+## 可重复执行的自测
+
+在项目根目录执行；运行中的程序需使用另一个输出文件名，避免覆盖被 Windows 锁定的可执行文件：
+
+```powershell
+.\scripts\build-windows.ps1 -RunTests -OutputName zerobot-next.exe
+go run scripts/smoke-local-admin.go -binary-name zerobot-next.exe
+```
+
+集成脚本创建独立 `.local/smoke-admin/run-*` 目录，只复制必要启动素材，使用假账号、本地模拟 OneBot 和测试密码；不读取实际机器人配置、控制数据库或后台凭据，不向真实 QQ 发消息。运行结果写入该目录的 `result.json` 和 `.local/smoke-admin/latest.json`，退出时停止自己的测试进程。未指定 `-binary-name` 时测试 `.local/bin/zerobot.exe`。

docs/local-admin/admin-password.md

@@ -0,0 +1,11 @@
+# 修改后台密码
+
+登录本机后台进入“后台安全”。填写当前后台密码、新密码及新密码确认，点击“修改密码并退出”后确认。新密码至少12个字符、不超过512字节，需与旧密码不同；不自动去掉首尾空格。这里仅管理后台密码，与QQ登录、OneBot Token和模型密钥分别设置。
+
+成功保存后所有后台会话失效，当前页面返回登录页，用新密码重新登录；其他标签页或浏览器在下次请求时要求重新登录。机器人和NapCat无需重启，消息处理保持运行。已开始的其他后台请求不追溯撤回，因此提交前需等待其他设置操作结束，并确认未保存编辑可以丢弃。
+
+密码输入不保留到浏览器存储或文件。离开安全页、退出、过期或成功后清空三项输入；请求中阻止切页/退出和重复提交。取消确认保留输入，服务端拒绝或网络异常后清空输入。若请求中断且不确定结果，请重新登录确认，优先使用新密码；不要根据页面未收到成功反馈推断保存失败。
+
+当前密码错误不会立即退出当前会话；登录与修改共享每分钟5次错误尝试限制。成功修改原子替换本机凭据，仅保存加盐派生值，不创建可恢复的旧密码备份；现有配置备份/恢复也不修改后台密码。写入失败保留旧凭据与会话；凭据被外部修改或文件异常时拒绝覆盖，按维护说明检查后重新启动。
+
+验收：在页面查看入口和输入校验；只有准备好记录新密码时才实际提交修改，再验证新密码登录及旧会话失效。自动测试使用临时后台与合成密码，不修改日常密码。不在聊天中发送密码。

docs/local-admin/agent-history-2026-10-03.md

@@ -0,0 +1,29 @@
+# Agent 连续对话与人物设定
+
+## 行为与数据
+
+| 项目 | 当前行为 |
+| --- | --- |
+| 行动轮数 | 移除单次任务最多 8 轮的循环；正常任务可继续执行，直到 `end_action`、没有动作或发生错误 |
+| 重复操作 | 同一任务重复生成相同动作批次，包括 A/B/A 循环时停止；变化的 Echo 不视为进展，新消息可开始新任务 |
+| 对话留存 | SQLite 持久保存已记录的事件、动作尝试、实际响应与任务结束标记，没有按轮数、条数或时间自动删除的规则 |
+| 会话隔离 | 每个机器人账号独立数据库；正数会话编号为群，负数为私聊用户；群内保留发言者身份 |
+| 修改人物设定 | 更新运行实例，保留历史；正在执行的旧设定任务停止，后续消息使用新设定 |
+| 重启 | 下一条事件创建 Agent 时重新加载当前会话记录；升级前只在旧进程内存中的记录无法补回 |
+| 手动重置 | 主人指令 `重置AI聊天Agent` 为已知会话写入重置标记，从新上下文开始；旧记录继续留在数据库 |
+| 请求容量 | 官方 DeepSeek 每次加载近期历史最多约 900,000 UTF-8 字节，给系统提示、记忆与输出留空间；超出的早期内容只从本次请求省略，不删除磁盘记录 |
+| 其他限制 | 单次模型 HTTP 请求仍有 30 秒超时，输出长度参数沿用原设置；取消轮数限制不等于提供方上下文和单次输出无限 |
+
+记录位于仓库内 `data/aichat/history/<机器人QQ>.sqlite`，当前账号对应 `data/aichat/history/87654321.sqlite`。首次收到可记录的事件时创建，并不是程序启动时立即生成。原消息钩子记录消息、相关通知/请求以及正常插件的消息动作；记录机制本身不主动向 QQ 发消息。事件和回复不再按原来的 1024/512 字节截短；已配置 AI 密钥和密钥设置命令内容会隐藏。这里保留的是 OneBot 事件/动作数据，图片等资源不会自动下载为离线附件，也不保存模型内部思考过程。
+
+Windows 对目录和数据库设置私有 ACL，仅当前运行用户与 SYSTEM 可访问；记录写入或配置读取失败会停止 Agent 动作，避免悄悄漏记后继续执行。现有 `data/aichat/agent/<会话编号>.txt` 长期记忆文件仍保留，记忆与事件档案分开使用；过长记忆只截取近期内容进入提示，不截断原文件。既有聊天角色权限、群开关与 @ 规则继续适用。
+
+后台现有三类配置备份不包含对话数据库或长期记忆文件。需要另行备份对话时先停止 ZeroBot，再复制 `data/aichat/history/` 整个目录（包括可能存在的 WAL/SHM 文件）和 `data/aichat/agent/`；恢复前也先停止服务。当前未新增网页记录查看、编辑或导出入口。档案会随使用增长，应按实际磁盘容量安排备份和整理。
+
+## 人物设定
+
+[默认人物设定](../../third_party/zbputils/chat/char.yaml) 已同时写入本机共享 AI 设置的 Agent 人物设定和性别字段。其他 AI 字段、密钥和启动 JSON 保持原值。
+
+保留 19 岁虚拟女生、粉蓝单马尾和校园风形象，把设定自然融入语气。通常简短接话，认真问题可以展开；少用固定口头禅和表情，傲娇以轻微俏皮为主，不挖苦用户。不编造经历或记忆，区分群内不同用户，只根据最新意图行动，成功后不重复发送，完成后结束当前任务。
+
+后续在后台修改 Agent 人物设定即可应用，并保留记录。磁盘档案完整保留不代表模型每次都能读取全部旧记录；超出请求容量的内容暂时不会提供给模型，当前也没有新增历史检索工具。