v0.4.0

ARTEX v0.4.0 中文更新说明

ARTEX v0.4.0 重点完善 ScopeSentry 资产同步、任务完成校验与 Worker 收尾，并修复 Windows 证据保存、Python 检测和路径兼容问题。代码优化主要体现在职责拆分、事务一致性、执行准入和终态保护；本次没有性能基准，不宣称吞吐、响应速度或模型成本提升。

版本与范围

• 发布版本：v0.4.0。
• 功能基线：v0.3.18，功能核验截至提交 19d9bbc，参见 功能提交比较。
• 发布文档与 CI 调整前，该范围共修改 87 个文件，新增 7580 行、删除 537 行，包含功能代码、测试和当时的规划、报告及更新日志。这不是最终发布提交的总统计，也不代表性能指标。
• 此前已部署的功能版本标识为 0.3.18-main-19d9bbc；本轮将这些变更以 0.4.0 正式发布，并补充 GitHub Actions 回归和发布预检。
• 本文只针对实际发布源码。doc/report.md 中另一工作区的 server.go / server_mgmt.go 全量拆分尚未合入本次版本，不属于 v0.4.0 的发布成果。doc/plan.md 的“待实施”是早期规划记录，当前实现和限制以本文及对应源码为准。

1. ScopeSentry 同步：后台执行、持久化历史与可恢复处理

使用行为变化

场景	v0.3.18 及之前	v0.4.0
判断是否完成	源扫描任务进度与同步结果容易混淆，返回后统一提示完成	明确标注“源任务扫描进度”；ARTEX 同步独立显示同步中、成功、部分成功、失败或已中断
刷新或关闭页面	结果主要保存在当前页面，离开后无法回看	同步历史与逐项明细落 PostgreSQL；后台任务不因页面关闭而取消
大批量资产	每个目标、每种类型最多处理 5000 条	新后台模式逐页处理，可超过 5000 条；旧同步接口保留原上限
页面拉取失败	难以说明哪些数据已取得、哪些尚未完成	保留前面已取得和已提交的数据，给出失败页面与部分完成状态
中断恢复	缺少持久化页面与逐项处理记录	先保存下载页面，再逐条入库；恢复时重放保存页面并跳过已记录项
重复同步	成功写入次数容易被理解为新增资产数量	分别显示源记录处理结果和按资产 ID 去重的独立资产数量
失败反馈	缺字段和部分关联 IP 失败可能静默遗漏	保存跳过、解析失败、入库失败及关联 IP 失败的具体原因

后台同步启动后返回任务编号，页面通过历史记录查看进度。服务端为后台同步设置单进程互斥，同一进程已有后台同步时，新启动或恢复请求返回冲突提示；后台运行期限为 6 小时，并受服务进程生命周期控制。

同步历史与统计口径

历史保存请求范围、数据源引用、源目标及资产标识、开始和结束时间、逐类型状态、逐项结果与原始 JSON。源 MCP 配置或实时资产被删除后，历史请求及观察记录仍可用于追溯；实时对象引用可变为空。

统计分为两层：

• 源记录统计：拉取、成功写入、新增、更新、未变化、跳过、失败，以及适配器显式派生 IP 的写入与失败次数。成功写入包含新增、更新和未变化，不等于新建资产。
• 独立资产统计：按本轮涉及的规范资产 ID 去重，区分直接资产与派生资产，并按新增、更新、未变化分类。同一资产被多个源记录触及仍只计一次；本轮分类优先级为新增、更新、未变化。

新增与更新判定比较实际资产内容，忽略 created_at、updated_at、last_seen 等时间字段；集合字段会规范化排序，避免仅因数组顺序变化被计为内容更新。

例如，回归夹具提供了 5001 条指向同一 App 的源记录。恢复处理后，源记录统计为 5001 次成功写入、1 次新增、5000 次未变化，独立资产只有 1 个。这一用例验证分页与计数语义，不是 5001 个独立资产的性能测试。

成功表示本次读取及处理没有发现失败或遗漏提示。存在跳过、失败、截断、详情获取警告或其他未完成范围时，会显示部分成功或失败；正常核实的零资产结果可以成功，不能把零资产直接当作源端故障。

恢复、重试与重新同步的区别

操作	处理范围	适用场景
从保存的页面继续	同一后台同步记录；读取已保存页面，跳过已记录项，再读取后续页面	进程退出、页面处理未完成、后续分页请求失败
仅重试失败和跳过记录	创建新同步记录，处理旧记录中保存的失败或跳过项 JSON	入库等临时问题已解决，需要重试已取得的记录
重新同步所选范围	创建新同步记录，重新从源端读取指定目标和类型	源数据已修正、原始 JSON 未保存，或需要再次核对整个范围

恢复会跳过已经记录为失败或跳过的项；处理这些项应使用专门的重试入口。仅失败项重试使用已保存 JSON，不会自动取得源端后来修正的记录；缺少完整 JSON 时会提示重新同步源范围。

服务启动时将前一进程遗留的 running 同步标为 interrupted，保留已提交记录，由用户选择继续。后台恢复的能力依赖新增页面记录，旧同步接口产生的记录不支持同样的断点恢复。

来源信息与字段映射

同步继续覆盖子域名、服务和 App，并可从子域名记录派生关联 IP；按项目同步时保留创建或复用企业及写入范围的能力。

• 子域名映射主机名、记录类型、记录值及关联 IP。
• App 映射名称、类别、描述、ICP 和 Bundle ID。
• HTTP 服务补充源端 host、statuscode、technologies、faviconmmh3、contentlength 等字段的兼容映射。
• 非 HTTP 服务校验域名或 IP，并接受合法的整数或字符串端口，范围为 1 至 65535。
• 服务资产通过 MCP get_asset_detail 读取详情，保留列表原字段，并把源端返回的完整详情另存于原始 JSON；缺少资产 ID 或详情读取失败会明确提示。

原始 JSON 与 Agent 可见的 assets.extra 分开保存，不把整段源文本和内联响应正文直接灌入资产上下文。逐项 JSON 可下载，单条观察记录最多保存 16 MiB；超限时保留结果与来源标识并提示原文未保存。该限制不是整个同步任务或数据库占用的总上限。

数据一致性与兼容边界

页面内容先持久化，再处理其中记录；源资产及其派生资产、来源观察记录和计数在同一事务内提交。子域名关联 IP 写入失败时，该源项及其派生写入回滚，另外保存失败观察，避免留下“源项成功、派生失败却无提示”的状态。记录唯一约束和已处理项检查用于防止同一恢复过程重复计数。

旧 POST /api/sync/scopesentry/sync 保持同步响应方式，并增加历史记录和真实结果反馈。它仍受每目标每类型 5000 条保护上限及 10 分钟请求期限约束；恰好达到上限时会进一步核验是否还有数据，不能仅因数量等于 5000 就宣布截断。大批量处理应使用新后台入口。

新增接口：

方法与路径	用途
POST /api/sync/scopesentry/jobs	启动后台同步或失败项重试
POST /api/sync/scopesentry/history/{id}/resume	恢复可继续的后台记录
GET /api/sync/scopesentry/history	分页查看同步历史
GET /api/sync/scopesentry/history/{id}	分页查看逐项明细；按需读取单项原始 JSON

源端 list: null 通过 count_assets 核实分页终点，无法核实或源端仍有记录时不会伪装成成功空页。App 按任务筛选使用源接口支持的搜索表达式，避免使用其不支持的任务过滤字段。

恢复不等于源端快照同步。 ScopeSentry 使用页码分页，扫描过程中的新增、删除或排序变化仍可能移动尚未读取的记录。已下载页面可以稳定重放，未下载页面没有固定快照保证；建议在源扫描稳定后重新核对范围。源接口没有返回的截图、响应正文文件及其他附件不属于已同步内容。同步历史默认保留，已处理页面会清空冗余临时载荷，但没有新增自动历史保留期限或完整附件镜像能力。

2. 任务完成：先核验剩余工作，再保存收尾结果并终验

修复的具体问题

此前，Planner 证明全部目标为 met 或发出完成信号后，引擎可直接把任务写为 done，随后取消仍在执行的 Worker。对于全面审计，某一路检查的证据可能被当作整体完成，其他必要方向尚未完成便被中止；取消原因 goal_met 也不能证明被停止检查已验证通过。

v0.4.0 将“目标证据达成”“可停止剩余工作”“执行已退出”和“任务最终完成”分开处理。prove_goal 继续保存目标证明，goal_met 改为申请收官；两者都不能绕过服务端完成校验。

新的完成协议

1. 完整读取剩余工作。 新增 list_remaining_work，按意图 ID 游标分页，返回总数、后续游标、受阻及删除原因。查询涵盖全部非 done 意图，包括 open、running、paused、blocked、exhausted、stopped、deleted，不依赖概览中的最近窗口。
2. 明确停止依据。 普通收官要求全部目标已达成。每个未完成意图都要提供 remaining_work 处置：只接受 duplicate 或 irrelevant，必须有非空理由；重复检查还须引用有效事实、漏洞或已完成意图。引用范围及类型由数据库校验。出错、受阻或预算耗尽本身不能作为必要检查已完成的依据。
3. 安装执行准入屏障。 收官尝试落库后，停止普通规划与新意图领取，要求已有 Worker 转入保存结果阶段，避免收尾开始后又启动普通工作。
4. 等待实际退出。 Worker 仅整理已有输出、保存事实和漏洞、说明未完成项。引擎等待执行与工具回调真正退出，之后才生成稳定快照；收到取消响应或框架终止事件不等于底层回调已结束。
5. 只读终验。 使用新的终验运行核对原始目标、描述、目标节点、约束、停止理由及已保存证据，必须提交明确的 completion_verdict。终验只有内置只读证据工具与结论工具，不开放 Shell、扩展工具、子 Agent、新探测或图写入。
6. 比较并提交终态。 提交前重新读取输入并比较摘要，同时检查尝试编号、阶段和任务生命周期。条件仍有效才提交 done；无法充分核验则保留证据、反馈拒绝原因并重新规划。任务到达绝对截止时间时复用该流程，不能确认完成的写为 timeout 并记录未完成范围。

单点或定量目标仍可在证据充分、剩余工作确属重复或无关时收官，不要求所有意图无条件自然结束。全面审计中的必要独立检查应继续完成；服务端能验证声明完整性和引用有效性，停止理由是否语义充分仍需终验模型判断。

收尾限制与超时处理

收尾控制通过执行时白名单生效，允许保存事实、登记漏洞、查看已有证据及必要的本地文件整理；不允许发起 Bash 探测、任意扩展工具调用或新的委派。限制会传递到间接工具调用和子 Agent 路径，工具执行前及前置 Hook 后再次检查。

当前源码设置 Worker 收尾阶段最多 30 秒，任务等待在途执行的宽限期为 90 秒，终验最多 45 秒、8 轮。这些期限不是整个任务必定在固定总时长内完成的承诺：已经准入的调用可能继续执行，忽略取消的回调仍需被等待。

普通收官超过宽限期会强制取消并放弃本次完成判定。取消后仍未实际退出时，任务被隔离并暂停，继续保留执行占用和并发槽位，退出前禁止恢复；不会一边把旧执行视为结束，一边启动新的执行与之重叠。

收尾终止原因新增 settlement_requested。被收官中断的意图不会直接写成 done；最终停止的检查保留原状态、停止理由及未完成说明。已保存结果仍可查询，停止或正常工具返回均不自动等于检查成功。

并发与状态保护

• 执行准入、意图领取和收官安装共享同步保护，避免新工作跨过收官屏障。
• 完成尝试保存 attempt_id、阶段、快照和输入摘要；追加目标、证据、约束或范围变化会使旧终验结果失效。摘要覆盖当前任务及直接来源任务的相关图和证据，并非只比较目标数量。
• 快照与终态提交使用短事务及明确锁顺序，设置锁等待和语句期限；模型和网络调用不在该事务内执行。这里解决一致性，不构成数据库并发性能提升声明。
• 用户暂停、任务删除和绝对超时与收官协调，迟到的终验不能覆盖已改变的生命周期。终验取消后，先前提交的结论也不再授权完成。
• 终验拒绝后，新执行使用新的收尾控制器，避免复用已经关闭的控制状态。

页面、报告与恢复

任务列表和详情增加收官阶段提示：“保存收尾结果”“最终复核”，并可查看最近一次尝试编号、原因、终验说明、剩余检查及其停止依据。收官记录作为任务主状态之外的附加信息展示；暂停和已有终态仍有自己的语义。

任务 Markdown 报告追加收官记录和剩余检查，明确停止决定不代表验证通过。Reporter 沿用原有独立报告流程；任务收官不等于所有漏洞报告已生成，报告版本及证据一致性继续由原机制核验。

进程重启会使旧收官决定失效，保留证据并恢复需要重新评估的工作；不会拿上一进程的半成品决定直接提交完成。归档包含收官记录，恢复归档时保留历史快照、推进尝试编号，并使仍在收尾或终验的旧决定失效。没有收官记录的旧归档继续兼容。

3. 代码优化与实际结构调整

本次优化把新增协议按职责组织，减少同步接口、资产映射、数据库事务和任务协调相互混杂。相关 Go 文件仍处于原有包中，不把文件拆分本身描述为运行速度提升。

领域	本次实际代码组织	作用
ScopeSentry 接口	server/sync_scopesentry.go 保留数据源与列表相关逻辑；新增 sync_scopesentry_run.go、jobs.go、pages.go、ingest.go、history.go、retry.go、detail.go，文件名均带 sync_scopesentry_ 前缀	分开请求与结果模型、后台生命周期、分页、校验映射、历史、重试和详情读取
同步数据库	db/sync_history.go、sync_pages.go、sync_asset_changes.go、sync_retry.go	明确页面持久化、资产内容变化判定、来源观察和统计的事务边界
任务协调	server/engine_completion.go 统一普通收官与任务超时的收尾、终验、提交和恢复；替换旧 engine_timeout.go 中的主要超时收尾实现	避免两套完成路径各自落终态、各自处理在途执行
完成输入与协议	agent/completion.go、completion_input.go、remaining_work.go；db/task_completion.go、task_completion_read.go、task_completion_archive.go	分开模型只读终验、输入预算、全量剩余工作查询、数据库提交与归档
执行框架	Norma 的 SettlementController、settlement_control.go 与 tool/execution_guard.go	将“隐藏工具”补为实际执行限制，并等待真实回调退出
前端展示	sync-history.tsx、共享 sync-result.ts、task-completion.tsx	集中历史展示、状态判定和收官说明，减少各页面自行解释状态的差异

终验输入也采用明确预算：完整保留决策所需的目标、约束、剩余工作和引用，仅对辅助证据摘要采样及缩短。初始输入上限为 32 KiB，并按当前上下文窗口进一步收紧；这是字节预算，不是精确 Token 估算。关键输入超预算时直接拒绝发起终验，不通过截掉必要目标或检查来拼出“完成”结论。完整数据库快照和提交摘要不随模型输入采样而缩减。

企业范围上下文补回显式范围及关键词；即使关闭覆盖度指标，Planner 仍能取得任务边界。企业范围用于规划，不能当作已经测试过的覆盖证据。

doc/report.md 另记的“新增 30 文件、将 server.go / server_mgmt.go 全量拆小”不在本次发布范围。本次 server_mgmt.go 的实际变更是技能相对路径规范化，不应与那项未合并重构混为一谈。

4. Windows 兼容与回归稳定性

问题	本次处理	边界
保存证据正文后对目录 Sync() 返回 Access is denied	正文仍做长度、哈希校验及文件刷盘、关闭、重命名；目录同步按平台处理，Unix 保留目录刷盘，Windows 跳过不支持的目录句柄操作	不忽略正文刷盘错误；Windows 目录在突然断电时的持久性仍取决于平台，不能宣称与 Unix 完全一致
python3 / python 路径命中不可执行的系统别名	自动检测除 LookPath 外，再运行最多 3 秒的 Python 探针并核验输出	仍需要实际可用的 Python；仅有商店别名不算解释器已就绪
技能相对路径在 Windows 返回反斜杠	路径清理及合法性校验后，用 filepath.ToSlash 统一接口相对路径	本地文件处理继续使用平台路径语义
子进程未退出便删除其输出文件，清理失败	清理先取消根上下文、等待进程退出信号与输出句柄释放，最多等待 10 秒，再删除会话目录	到期仍被进程持有的文件保留，后续会话垃圾回收可再次处理
测试使用 Unix Shell 命令或固定等待	Windows 用对应 PowerShell 命令；后台任务测试等待真实完成并关闭 Session	这是测试可移植性和清理修正，不表示任意用户脚本自动变为跨平台脚本
LLM 重试测试出现 nil HTTP client panic	用测试服务器的 client 显式初始化重试配置	修复测试夹具，不能描述为真实供应商重试策略新增功能

5. 数据库迁移与兼容

升级沿用启动时幂等 PostgreSQL schema 应用，新增表和字段使用 CREATE TABLE IF NOT EXISTS、ADD COLUMN IF NOT EXISTS 等语句。

表	保存内容
sync_runs	全局同步请求、状态、结果、时间与计数
sync_observations	逐源记录结果、原因、来源标识、原始 JSON 和资产变化
sync_pages	尚待处理的下载页面及页计数、完成和末页标记
sync_asset_changes	单次同步涉及的独立资产、变化分类和直接或派生来源
task_completions	每任务当前或最近收官尝试、阶段、快照、摘要及期限

同步历史属于全局来源记录，不是某个 ARTEX 任务的探索图。删除 MCP 或资产时保留历史，删除同步记录则由外键级联清理其明细、页面及资产变化记录。task_completions 与任务关联，随任务删除清理。

已有系统工具 prove_goal、goal_met 的 schema 会幂等补充缺失的可选 remaining_work 属性。迁移只合并这一属性，不重置用户的描述、默认参数、启用状态及其他自定义配置；已有该属性时保留其定义。Planner 运行时会追加完成协议指引，自定义提示仍应符合新的收官要求。

新同步历史从升级后的运行开始保存，不追溯重建以前仅存在于浏览器的结果。升级也不会自动重跑历史目标或把旧的 done 任务全部重新终验。

6. 验证范围与真实模型验收边界

以下区分功能提交已有验证记录、本轮发布定向回归和外部 CI。文档核验检查了本次发布源码及用例，不把测试存在等同于测试已经执行，也不把模拟模型等同于真实模型验收。

已有功能验证记录

依据功能提交中的 CHANGELOG 验证记录：

范围	记录结果	统计口径与限制
本地 PostgreSQL 主模块回归	731 个顶层测试通过、14 个跳过	server 包在源码固定后单独完整复跑通过；不计子测试重复总数，跳过不计通过
Norma 模块回归	690 个顶层测试通过、8 个跳过	与主模块分别统计，不能同旧版含子测试数量直接比较
真实 ScopeSentry	非空结果及空结果同步通过	验证所接入源实例，不代表所有源版本、数据集和附件都已验证
大批量与故障恢复	5001 条分页失败后恢复、部分页面恢复、仅失败和跳过记录重试通过	大批量用例使用 MCP 夹具；不属于真实大规模源数据性能验收
完成协议	相关完成流程竞态检查通过	覆盖已保存结果、准入屏障、迟到回调和状态改变等协议行为
前端	10 项测试、TypeScript 检查、32 页静态导出通过	不等于所有浏览器交互已人工或端到端验收

历史 doc/report.md 中早期全量失败和另一工作区拆分验证有各自基线，不能用它们替代上述功能验证，也不能把原有跳过项算作通过。真实模型配置、符号链接权限及其他环境条件仍会使部分用例跳过。

本轮发布定向回归

发布准备阶段已确认以下本地定向回归通过：

• Windows 隔离 PostgreSQL 下的全部 TestEvidence，以及 Python 执行、Python 检测和技能相对路径相关回归。
• Linux 主模块与 Norma 的收官、同步、收尾及执行保护定向测试，实际启用 -race、-shuffle=on。
• TaskCompletion 归档往返回归。

定向测试覆盖页码边界、失败保留、资产与来源原子提交、计数恢复、保存页面重放、失败项重试、各未完成状态拒绝、暂停和追加目标使旧终验失效、隔离保留槽位、只读终验、间接工具限制、收尾期限及实际回调等待。它们不构成五个平台全量测试通过声明。

真实模型仍需验收的内容

完成协议测试大量使用受控模型 provider，已验证流程和状态保护；尚未完成真实外部模型 Planner/Worker 长流程的全面验收。仍需在实际模型和任务上确认：

• 全面审计会继续完成必要的独立方向，停止理由不会把受阻、出错或未测试错误归为无关。
• Worker 能依据已有输出保存有效事实、漏洞和未完成说明；脚本错误不会被工具返回状态掩盖。
• 只读终验能按引用补查证据，拒绝证据不足的完成候选，并产生可用的最终说明。
• 长任务、复杂来源继承及不同上下文窗口下，协议能与具体模型的行为配合。

这些语义判断和报告质量不能仅由锁、事务、工具白名单或模拟测试保证；本版本不宣称全面消除模型漏测、误判或漏报。

7. GitHub Actions 发布与回归

本轮新增 sync-completion-regression 和 windows-regression，保留既有测试、前端和漏洞报告回归：

• Linux 使用隔离 PostgreSQL，主模块同步与收官回归以及 Norma 收尾、执行保护回归均启用 -race -shuffle=on，包顺序通过 -p 1 控制。
• Windows job 使用 runner 内置 PGBIN 启动独立 PostgreSQL 测试数据目录，实际执行全部 TestEvidence 及 Python、技能路径回归，结束后关闭测试数据库。
• 发布 prepare 阶段要求 CHANGELOG 中对应版本说明非空；缺失或空白直接失败，不再静默退回无版本说明的发布正文。存在 doc/releases/v0.4.0.md 时以该详细说明作为正文，通过 artifact 交给发布作业。
• Release 在校验通过后构建包和 Docker 镜像，检查包数量、文件名、SHA256 及双架构 manifest，再发布 GitHub Release；相关 Actions 更新到本轮已核实的主版本。

继续提供五个平台包：Linux amd64/arm64、macOS amd64/arm64、Windows amd64，以及 SHA256SUMS。Docker 保持 Linux amd64/arm64 双架构，并执行镜像启动冒烟检查。五平台构建与冒烟不等于五平台完整功能回归。

发布准备提交 788c8c6 的四项 GitHub 检查均已通过：测试布局、既有漏洞整理回归、Windows 回归、同步与收官回归；工作流语法检查和 4 项打包契约检查也通过。正式版本的五平台构建、镜像和 Release 发布结果以 GitHub Actions 和 v0.4.0 Release 为准。

8. 升级建议

1. 升级前备份 PostgreSQL 与 ARTEX 数据目录，包括任务工作目录、证据库、配置和密钥。尽量等当前同步或收尾结束；需要中断时先暂停任务并记录运行状态。
2. 下载对应平台 v0.4.0 包并校验 SHA256SUMS，或使用对应版本 Docker 镜像，保留现有配置和数据卷后重启。前端应与后端一起升级，避免混用缓存的旧页面。
3. 检查启动日志中 schema、工具参数补充、同步恢复和收官恢复的结果。迁移账号需要创建表、字段和索引的权限；若收官恢复无法确认旧状态，任务会保守暂停，应先解决数据库问题再继续。
4. 在同步页查看历史状态。中断的后台记录可从保存页面继续；失败及跳过项单独重试；源数据改变或原始 JSON 缺失时重新同步范围。重试后核对源记录与独立资产两种统计。
5. 检查仍运行的审计任务和自定义 Planner 指引：目标 met 不再立即触发任务 done，必要未完成检查会阻止收官。观察收尾和终验记录，调整过小的上下文窗口或补充任务目标与停止依据。
6. Windows 部署确认安装可用 Python，验证证据保存与自定义工具；不要将解释器系统别名或进程清理超时后的残留文件视为正常验收通过。

若需要回退，应优先使用升级前的数据库和数据目录备份，并避免旧、新进程同时操作同一运行任务。本次增加持久化状态和工具 schema，未验证旧二进制对所有升级后运行记录的向后读取行为，不能承诺仅替换二进制即可完整回退。

9. 从 v0.3.16 升级的累计背景

以下内容已在 v0.3.17 / v0.3.18 发布，不是 v0.4.0 新功能：

• v0.3.17：模型配置来源与 LLM 录制查看、Agent 空输出诊断、多漏洞候选与独立登记指引、拦截加载失败时保守阻断、os.Root 工作区边界、noa 上下文窗口学习与恢复修正，以及中文发布说明接入。
• v0.3.18：修正内置 ScopeSentry Skill YAML 元数据，保存时使用 YAML 解析和编码，保留多行及嵌套字段，取消 MCP 关联时清理旧字段，并增加元数据与上传回归。

v0.4.0 在这些既有能力之上加入同步历史、可恢复后台处理与服务端完成协议。旧版本的提示改进和本次完成状态保护各有作用，不能把累计变更全部描述为本次新增。

Full Changelog: v0.3.18...v0.4.0