HHostingByteSoftware
Ctrl K
ComunidadGuías…

CHANGELOG.md

Rama main · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
# Changelog

所有重要变更都记录在此文件中。版本号遵循 [Semantic Versioning](https://semver.org/)。

## [1.0.0] - 2026-10-22

本版本重新发布，标签更新到包含以下改动的提交；旧源码包需重新下载，已有克隆需刷新标签。

### Added

- 按 Skill 版本选择“沿用 Skill 既定流程”，单 Skill 任务免除强制重复规划；网页、API 和重试任务继承版本策略。
- 通用最终操作交付，支持全部账号、Skill 和文件格式；模型提前声明真实路径，操作成功、文件新鲜度和原有完成条件满足后省去独立结束轮次。
- 默认关闭的上下文组成与轮次耗时观测，不改变模型输入，不增加摘要调用。

### Changed

- 新部署默认开启文件接收模式与通用交付，不需设置版本白名单；可显式关闭文件接收模式，使用额外平台验证。
- 文件未变化、路径未知、失败和取消等情况仍回到普通处理路径；保留既有工作流兼容适配。
- 对外文档、示例和界面占位值使用通用名称。
- 清理无调用代码和历史转接入口，合并重复附件解析，移除前端无效状态，并开启未使用符号检查。
- 快照和上下文观测默认关闭；已有实例的显式配置不随版本发布被覆盖。

### Upgrade

- 相对 v0.4.9 包含 `20261022_0009_skill_flow_policy` 迁移，为 Skill 版本和任务增加默认关闭的既定流程字段。
- 完整范围、验收模式区别及回退要求见 [发布说明](RELEASE_NOTES.md)。

## [0.4.4] - 2026-09-24

### Changed

- 任务改为完全无人值守、一口气执行到底：移除 Agent 的 `ask_user` 工具（工具表、参数校验、模型响应解析的独占规则、系统提示全部同步）。信息不足时 Agent 必须采用与输入和用户目标最一致的合理假设继续，记录并在最终摘要中披露假设；只有输入不可用或无法消除的矛盾才允许 `block`。模型若因旧习惯发出 `ask_user`，收到的是可恢复的"自行假设并继续"指引，重复停留则由既有卡死保护（`SANDBOX_AGENT_STALLED`）如实失败，任务不再进入挂起状态。
- 系统提示新增"Unattended execution"规则，并把"用 ask_user 暴露矛盾"改为"自行假设并在摘要说明"。

### Compatibility

- `waiting_user` 状态、`pending_question` 字段与 `POST /api/v1/jobs/{id}/answer` 保留，仅供 v0.4.3 之前的历史任务；新任务不会再进入该状态。外部 API 客户端示例保留对历史状态的防御性处理。

## [0.4.3] - 2026-09-24

### Changed

- 单条沙箱命令预算由 900 秒提高到 3000 秒（`SKILLGO_SANDBOX_COMMAND_TIMEOUT_SECONDS`，config 默认值、`.env.example`、`deploy/ecs.env.example` 同步）：图纸批量校验等任务单批实际需要 30-45 分钟。命令工具的模型 schema 上限、参数校验、系统提示、超时恢复提示全部改为从该配置动态取值，消除此前散落的 900 硬编码；`run_python` 600 秒上限保持不变。

## [0.4.2] - 2026-09-24

### Changed

- 持久化快照容量上限由 256 MiB 提高到 512 MiB（对正常重任务最大 127 MB 快照留 4 倍余量；恢复内存峰值仍在 2 GiB worker 限额内）。
- 用户输入文件（`/workspace/input`）不再计入每轮工作区快照：输入为平台投放的不可变文件，崩溃恢复/沙箱切换/依赖升级换箱时改为从对象存储重新投放，多附件重任务的快照体积与每轮打包耗时永久下降。

### Fixed

- 快照因超出容量上限（或 Docker 传输短暂不可用）而失败时不再杀死任务：降级为跳过本次及后续快照并记录"已跳过工作区快照"中性事件，任务继续执行、最终产物校验不受影响；路径越界/校验和不符等完整性错误仍然致命。
- 快照辅助容器清理超时由 60s 提高到 180s 并自动重试一次，清理失败不再掩盖真正的导出错误（此前 ReadTimeout 曾掩盖"快照超容量"根因）。

## [0.4.1] - 2026-09-24

### Added

- Agent 新增 `inspect_document` 工具，文档/图片理解按需路由：`structure` 走 MinerU `/file_parse` 并请求 `content_list`，返回每个文本块的 `type`/`text`/`bbox`/`page_idx` 与页码范围支持，支撑扫描件 OCR 与原位翻译/标注；完整块列表落盘 `/workspace/work/document_inspection/<sha256>.json`，模型上下文只返回路径与前 20 个样例。`understand` 走视觉模型回答渲染页面问题，`auto` 按文件类型自动选择；结果按文件摘要/意图/页码范围缓存，避免重复 OCR。

### Changed

- 系统提示明确：数字版 PDF 存在可用文本层时直接用 PyMuPDF 抽取文字与坐标，不再无谓调用 OCR；仅扫描件或需要块级坐标时才使用 `inspect_document(structure)`。

## [0.4.0] - 2026-09-20

本版本主线是**让长任务真正跑得完、断了能续**：新增 Skill 能力环境自动准备与任务持久化快照恢复，命令超时不再摧毁沙箱，并系统治理 Agent 上下文（重复读文件、工具输出被截断）；执行过程界面改为 扁平行动流。

### Added

- Skill 能力环境体系：能力预检与经验证的 golden runtime；任务开始前自动准备并绑定隔离的能力环境，沙箱在安全的 Agent 轮次边界恢复；能力目录扩展并暴露依赖分析。
- 通用 PyPI 依赖准备：支持从公共 PyPI 解析任意 wheel 依赖（仅预编译 wheel、自动锁定间接依赖版本与哈希）；任务执行中允许最多 2 次依赖升级请求，触发环境重建与沙箱切换而不必从头重跑。
- 持久化任务快照与围栏恢复（durable snapshots / fenced recovery）：Worker 崩溃或重启后任务从快照继续；工作区快照/恢复改为流式处理，内存占用限定在约 1 倍工作区大小。
- 不可变引用架（reference shelf）：Skill 静态资料与用户输入文件在首次从头读取后钉住，后续分页读取直接由内存服务，消除同一文件被重复读取数十次的问题（超过 20KB 的文件与可变工作文件仍走正常分页）。
- 计划引用支持目录：以目录内常规文件的相对路径与逐文件哈希聚合绑定；重规划时合并既有产物绑定。
- 执行过程界面：展示模型思考摘要并在行动流中保留工具调用理由；执行计划与可展开运行日志区分，Skill 执行扁平化为单一日志。
- 多附件 OCR/视觉分析并行处理（并发上限 3）。

### Changed

- 命令/脚本超时改为容器内 GNU `timeout(1)` 包装：超时只终止子进程（先发 TERM，5 秒后 KILL），沙箱与 `/workspace` 完整保留，Agent 从脚本自身的断点状态续跑；仅 docker-exec 传输层彻底卡死才回收容器。默认命令预算 900 秒。
- 工具输出两级内联阈值：`command`/`run_python`/`run_verifier` 最近结果 52 KiB 以内全量内联（`SKILLGO_SANDBOX_TOOL_INLINE_BYTES` 可调）；超限全文落盘并保留头 2KB + 尾 2KB 片段（traceback 与最终状态在末尾）。其他工具保持 4KB 阈值。
- `read_file` 请求的窗口（offset/limit 改为可选，最大 30000 字符）始终完整返回，不再被通用 4KB 摘录截断。
- 计划中途校验放宽（"中途信任、边界验证"）：更新计划不再因引用文件暂缺或步骤证据缺失而阻断，仅返回待处理警告；最终交付仍严格校验真实产物。
- 平台默认模型单轮预算不限时；Worker 扩展到 5 副本，Worker/环境 Worker/任务沙箱内存分别上调到 2GB/1GB/2GB。
- PDF 附件默认强制开启 OCR，未配置 OCR 能力时在发送前明确阻断；Nginx 附件上传超时放宽到 905 秒。

### Fixed

- `read_file`/`list_files`/`write_file` 访问 `/workspace` 外路径时返回可恢复的工具错误载荷，`SANDBOX_PATH_DENIED` 不再直接杀死整个任务。
- 运行时画像检测剥离平台派生的 x-skillgo 命名空间，文档示例命令不再被误判为必需依赖。
- Worker 恢复扫描不再锁定健康任务；产物校验错误可恢复，清理阶段失败也会保留证据。
- 同名附件自动重命名，用户列表兼容历史邮箱格式。
- 修复工作区快照目录 fsync 的调用错误并补齐 POSIX 分支测试。

### 迁移

- 新增 Alembic 迁移 `20260911_0008_prepared_environments`（能力/预备环境表），服务启动时自动执行。

## [0.3.1] - 2026-09-09

本版本集中升级模型调用的传输韧性：只要响应持续流动即不掐断任务，卡死在空闲检测窗口内被发现。

### Changed

- 模型单轮总预算支持 `timeout_seconds=0` 表示不限时：只要响应流持续有数据即不设单轮上限，空闲检测（首响应/流停滞）默认放宽到 600 秒，连接超时 15 秒不变。
- 沙箱任务级 wall-clock 上限与推理轮数/工具操作上限均支持 `0=禁用`：默认任务不再有总时限（`SKILLGO_SANDBOX_JOB_TIMEOUT_SECONDS=0`），推理轮数与工具操作默认放宽到 300/480 次；防失控依赖轮数上限、重复循环干预与分层空闲检测。

### Added

- Agent 推理请求改为流式接收（SSE）：聚合增量内容、推理文本与工具调用分片为完整响应；网关忽略流式请求时自动回退为整体 JSON。
- 模型传输分层超时：连接超时、首响应等待（无任何响应数据）、流停滞等待（生成中途无新数据）与含重试的总截止分别配置（`SKILLGO_MODEL_CONNECT_TIMEOUT_SECONDS`、`SKILLGO_MODEL_FIRST_CHUNK_TIMEOUT_SECONDS`、`SKILLGO_MODEL_STREAM_STALL_TIMEOUT_SECONDS`，也可按模型在 agent_options 覆盖；总截止始终保持有界，不因心跳延长）。
- 传输进展诊断：推理轮次事件记录首响应耗时、SSE 数据块数、字节数与重试次数；失败时区分 `MODEL_FIRST_RESPONSE_TIMEOUT` 与 `MODEL_STREAM_STALLED` 错误码并附带传输统计。

### Fixed

- 上下文分配优先保留最近一次完整工具交互，避免工具结果被全部裁掉后仍继续推理；观察摘要限制大小，大结果保存到文件并返回有界 UTF-8 摘录。
- 输入预算纳入原生工具定义，首次模型请求前预留反馈空间；预算不足记录各部分占用并明确失败，同时保存任务运行时模型预算快照。
- 嵌入式数据库迁移不再覆盖 API/Worker 日志配置，恢复模型传输与任务诊断日志。
- 避免单 Skill 指南在固定提示与活动上下文中重复发送，保留完整规则及多 Skill 活动指南。
- 区分模型连接失败、响应超时与通信中断；记录失败推理轮次耗时、输入预算估算和传输尝试诊断。
- 短暂连接超时、读取中断与协议断连可在原请求总预算内重试；取消不会触发重试。
- 明确每次 Python 工具调用启动独立进程，要求通过工作区模块与中间文件复用解析结果，减少跨调用变量错误和重复生成。

## [0.3.0] - 2026-09-07

### Added

- 编排计划支持步骤依赖、输入输出文件哈希、受影响阶段失效与重规划；活动 Skill 和原始要求按模型预算保留。
- 新增真实验证器工具与可查询证据、生成图片视觉检查、固定入口和 Agent 混合执行。
- 工作台支持自动匹配 Skill、缺失信息提问与回答后重新排队；已确认答案保留到任务重试。
- 模型连接增加协议适配、推理强度与上下文/输出预算，迁移 `20260907_0007` 保存编排记忆与模型参数。

### Changed

- Skill 包导入现在兼容仓库包装目录、嵌套的唯一 `SKILL.md`、UTF-8 BOM、文件名大小写差异，以及缺少部分 Frontmatter 的真实 SkillHub 下载包。
- Skill 资料预填优先保留包内合法 slug；可选的 AI 分析使用独立的默认 45 秒超时，超时或模型不可用时回退到本地解析结果，不再阻塞上传。
- 新建 Skill 时会规范化中文或非法 slug；全局标识冲突会在分析阶段建议 `-2`、`-3` 等可用值。

### Fixed

- 补齐工作台“自动选择 Skill”的可见开关滑轨与圆点，区分开启、关闭及禁用状态，并支持键盘切换。

- 验证只接受最新实际验证器的结果和产物哈希，失败验证不能被普通成功命令或模型声明覆盖。
- 已启动但失败的写操作会使缓存与旧验证失效；重复读取在有实际新结果时恢复计数，成功的重复空操作不会无限重置防循环。
- Skill 自动匹配先检索相关候选，零匹配时不再随意选择第一个 Skill；文档中的可选命令不再全部成为启动硬依赖。

- 修复部分真实 Agent Skill ZIP 因目录包装或元数据不完整而无法导入的问题，同时继续拒绝多个 `SKILL.md`、危险路径、特殊文件、重复路径和异常解压。
- 上传连接被浏览器或企业网关中断时，不再误报为无法识别 ZIP；界面会区分网络传输问题与后端 `422` 包校验错误，并给出可操作提示。

## [0.2.6] - 2026-09-04

### Added

- 工作台附件上传展示真实字节进度；上传完成后继续显示 OCR、视觉分析或附件解析阶段，不再把耗时处理笼统显示为“发送中”。
- 对话附件完成后展示“OCR 已识别”“视觉 + OCR 已完成”等可审计状态；部分能力失败时明确区分 OCR 与视觉结果。
- PDF 附件开启 OCR 后可直接交给 MinerU `/file_parse`，识别结果进入普通对话或 Skill 任务上下文。

### Changed

- PDF OCR 只调用 OCR 文件解析模型，不会把 PDF 错误发送给视觉 Chat Completions；图片继续使用视觉理解，并按用户选择叠加 OCR。
- 任务和对话记录按附件真实处理结果保存 `ocr`、`vision`、`vision_with_ocr` 或 `mixed` 模式。

### Fixed

- 修复开启 OCR 后上传 PDF 仍因“普通对话无法理解文件格式”而无法发送的问题。
- 扩展 MinerU multipart 文件名与媒体类型映射，PDF 使用 `.pdf` 和 `application/pdf`，不再退化为未知二进制文件。
- 扫描型 PDF 未开启 OCR 时返回可操作的提示，避免用户无法判断失败原因。

## [0.2.5] - 2026-09-03

### Added

- 模型连接新增明确的接口类型，OCR 可直接选择 MinerU 文件解析协议并调用 `/file_parse`，不再要求服务兼容 OpenAI Chat Completions。
- MinerU 返回的 Markdown OCR 内容会被规范化为附件文字证据，并移除只在 MinerU 临时目录中有效的图片引用。
- 新增 Alembic 迁移保存模型接口类型，已有连接安全默认为 OpenAI 兼容协议。

### Changed

- 工作台“OCR 识别”改为左右滑动开关，补齐开启、关闭、禁用和键盘焦点状态。
- MinerU 连接测试通过 OpenAPI 验证 `/file_parse` 协议，不再为测试连接触发一次耗时的完整 OCR 推理。
- 平台设置会根据接口类型调整字段说明；MinerU 固定声明为 OCR 能力，避免误配为对话或视觉模型。

### Fixed

- 修复将 MinerU 根地址错误拼接为 `/chat/completions` 后导致模型配置测试失败的问题。

## [0.2.4] - 2026-09-03

### Added

- 平台模型连接可分别声明对话、视觉和 OCR 能力，并为三类能力独立设置默认模型。
- PNG、JPG/JPEG 和 WebP 图片附件默认由视觉模型理解；用户开启“OCR 识别”后，按 OCR、视觉理解、对话回答的顺序协同处理。
- 附件和任务记录保存分析模式、状态、视觉模型、OCR 模型及降级错误，支持审计和问题定位。
- Alembic 迁移为已有模型、对话附件和任务输入安全补齐附件智能字段，旧模型默认保持对话能力。

### Changed

- 平台设置重构为模型角色概览、独立默认项和能力配置抽屉；工作台在 OCR 模型未配置时明确禁用 OCR 开关。
- 视觉与 OCR 使用 OpenAI-compatible 多模态 Chat Completions 接口；OCR 失败时保留警告并继续视觉理解。
- 图片分析结果可以作为 Skill 任务的附件证据传入执行上下文，但原始图片仍由既有任务存储和沙箱边界管理。

### Security

- 图片扩展名必须与 PNG、JPEG 或 WebP 文件签名一致，避免仅凭 Content-Type 接受伪造图片。
- 图片、OCR 文字和视觉分析结果始终作为不可信数据，不得覆盖平台、用户或已审核 Skill 指令。
- 测试新模型连接时不再复用其他模型的已保存 API Key，避免跨模型服务误发凭据。

## [0.2.3] - 2026-08-26

### Added

- 管理员可在版本审核时为沙箱 Skill 开启“运行联网”，并可在发布后随时关闭或重新开启；所有版本默认断网。
- 任务创建时保存实际联网状态及授权来源 Skill 版本，多 Skill 任务按任一授权版本开启联网，历史记录不受后续开关变化影响。
- 固定入口执行模式、产物 SHA-256 验证快照与验证失效机制，确定性 Skill 不再由模型临时选择脚本。
- 审核页、Skill 版本列表、任务运行页和工作台任务卡展示联网需求、当前授权及任务快照。

### Changed

- 将沙箱 Agent 循环、工具注册、固定执行和产物验证从 Worker 主流程拆分为独立模块。
- Skill 内容中的网络声明、URL和依赖文件仅作为审核提示，不再自动授予任务容器网络。
- pip/npm 依赖继续限定在一次性工作区，apt/apk 等系统包安装保持禁止。

### Security

- 只有管理员审核过的具体 Skill 版本能够获得运行联网权限，权限变更写入审计日志，模型和普通用户不能自行开启。
- 任务容器继续不接收数据库连接、JWT Secret、模型 API Key、Endpoint Key或 Docker Socket。
- 当前联网仍为不限制目标域名的 Docker bridge；管理员只应为可信 Skill 开启，域名白名单、出口代理与 SSRF 防护不在本版本范围内。

## [0.2.2] - 2026-08-24

### Fixed

- 普通对话上下文同时遵守消息数量与字符上限，最近单条超长消息也会安全截断，避免请求体失控。
- 删除参与多 Skill 编排的任意 Skill 时完整清理关联任务、运行记录和绑定关系，不再遗留失效引用。
- 部署时等待 API 健康后强制重建 Web/Nginx，避免后端容器地址变化后 `/health` 等代理路由返回 502。

### Changed

- 自动化部署同时验证首页与 API 健康路由，失败时输出 Web/API 日志并停止发布。
- 只有完整自检成功后才以原子方式记录实际部署的 Git 提交号，便于迁移、审计和故障定位。
- Tag 升级流程采用相同的数据库、API、Web 启动顺序与健康检查。

## [0.2.1] - 2026-08-22

### Changed

- README 聚焦当前已实现能力与实际运行边界，不再陈列未排期的功能路线图。
- GitHub Release 工作流默认发布正式版本，不再自动标记为 Pre-release。

## [0.2.0] - 2026-08-22

### Added

- Alembic 数据库迁移基线，兼容安全接管已有 v0.1 数据库。
- 部署前配置、Docker GID、gVisor Runtime 和沙箱镜像预检。
- PostgreSQL、托管文件和本机配置的版本化备份与校验恢复脚本。
- 指定 Release Tag 的备份优先升级脚本。
- 统一的 15 天托管文件生命周期：对话附件、任务输入与生成产物到期后自动释放，任务记录和结果摘要继续保留。
- 文件过期下载状态，以及带服务器磁盘可视化的管理员存储概览。
- 孤儿文件安全缓冲清理、系统审计事件和 v0.1 数据库的无损升级迁移。

## [0.1.0] - 2026-08-22

### Added

- 多用户账号、三级角色、管理员审核和唯一超级管理员。
- Skill 上传、结构校验、不可变版本、发布审核与社区可见性。
- 任务级 Docker Volume 与容器隔离，gVisor `runsc` 支持。
- 基于租约的 Worker、心跳、重试、取消和失效恢复。
- 多 Skill 编排、工具事件、上下文续话和附件处理。
- 可验证产物、完整性校验和用户隔离的下载。
- 同步与异步 Skill API Endpoint，独立 API Key 和幂等请求。
- React 工作台、Skill 社区、运行记录、用户管理和模型配置界面。
- Docker Compose 私有化部署、gVisor 安装与环境自检脚本。

### Security

- 密码使用 Argon2 哈希，管理操作和资源访问写入审计记录。
- 任务容器默认非 root、只读根文件系统、去除 Linux Capabilities 并限制 CPU、内存和 PID。
- 本机密钥、运行数据、用户文件和备份默认被版本库忽略。

[Unreleased]: https://github.com/Max-cu/SkillGo/compare/v0.4.0...HEAD
[0.4.0]: https://github.com/Max-cu/SkillGo/compare/v0.3.1...v0.4.0
[0.3.1]: https://github.com/Max-cu/SkillGo/compare/v0.3.0...v0.3.1
[0.3.0]: https://github.com/Max-cu/SkillGo/compare/v0.2.6...v0.3.0
[0.2.6]: https://github.com/Max-cu/SkillGo/compare/v0.2.5...v0.2.6
[0.2.5]: https://github.com/Max-cu/SkillGo/compare/v0.2.4...v0.2.5
[0.2.4]: https://github.com/Max-cu/SkillGo/compare/v0.2.3...v0.2.4
[0.2.3]: https://github.com/Max-cu/SkillGo/compare/v0.2.2...v0.2.3
[0.2.2]: https://github.com/Max-cu/SkillGo/compare/v0.2.1...v0.2.2
[0.2.1]: https://github.com/Max-cu/SkillGo/compare/v0.2.0...v0.2.1
[0.2.0]: https://github.com/Max-cu/SkillGo/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/Max-cu/SkillGo/releases/tag/v0.1.0