Archify Skill 内置可选更新提醒器跨 Agent 低打扰更新感知的设计与实现【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify面向读者Skill 维护者、Agent 集成开发者、安全与发布工程师。本文基于仓库内设计文档 docs/skill-embedded-optional-update-notifier-design.md 展开并结合源码 archify/scripts/check-update.mjs、archify/scripts/update-contract.mjs 与测试 archify/test/update-notifier.test.mjs 佐证。Archify 是一套为架构、工作流、时序、数据流与生命周期图提供可验证渲染的 Agent Skill见 archify/SKILL.md。本文讲解其内置“可选更新提醒器”的完整技术方案如何在 Skill 被激活时以一次低频、只读、可缓存的网络检查发现候选版本如何在确认提醒可见后才去重以及如何用本地状态机、安全缓存与发布门禁把“提醒”和“更新”彻底解耦。读完本文你将掌握一套可在多 Agent 宿主Codex、Claude Code、Cursor、OpenCode 等间复用、可测试且不扩权的最小更新感知协议。1. 背景Skill 安装方式碎片化带来的“长期旧版本”问题Agent Skills 可以通过 Marketplace、Plugin、跨 Agent CLI如gh skill、Git 仓库或直接复制目录等多种方式安装。不同安装方式的更新能力并不一致——尤其是直接复制安装的SKILL.md目录通常没有持续的上游版本提醒机制。对于高关注度、频繁发布的 Skill会累积出四类问题用户长期停留在旧版本却从不主动打开管理页面或运行更新命令同一个 Skill 分布在不同 Agent 宿主中维护者难以依赖单一 Marketplace 触达全部用户在 Skill 内直接执行安装命令会扩大供应链与权限风险每次激活都联网检查或弹窗提示会带来时延、工具调用和通知疲劳。仓库的配套市场调研 docs/research/skill-plugin-update-reminder-market-design.md 对比了 Claude Code、GitHub Copilot、gh skill、Gemini CLI、VS Code Agent Plugins 与 Vercel Labsskills的更新机制后给出结论市场还没有一套同时覆盖“跨 Agent 安装、可靠版本识别、权限差异、低打扰提醒、自动更新、回滚”的完整 Skills 更新系统。因此设计文档推荐建设独立于各 Agent 的更新感知层——这正是 Archify v0.1 提醒器的定位。核心思路提醒与更新解耦。Skill 只负责让用户“知道有新版本”用户不作任何选择时已安装内容与当前任务完全保持不变。2. 目标与非目标v0.1 的边界v0.1 的唯一职责可以用一句话概括发现候选版本并让用户感知不下载、不安装、不执行远端命令、不覆盖 Skill 文件。2.1 目标在支持本地脚本和网络访问的 Agent 中提供一致的更新感知检查失败时保持静默不阻断、不降级用户原任务同一候选版本在成功确认展示后不再提醒正常路径只展示一次让用户清楚看到当前版本、候选版本、本地固定状态摘要和官方发布说明把版本检查控制在低频、低流量、可缓存的只读请求内保持检查逻辑确定、可测试并独立于模型的版本比较能力保证“提醒事件”本身不构成更新授权。2.2 非目标v0.1 明确不负责自动下载、安装或激活新版本调用gh skill update、npx skills update或宿主原生更新命令修改、替换或删除 Skill 安装目录中的任何文件解决跨 Skill 依赖、版本约束或回滚统一 Claude、Codex、Gemini、Cursor 等原生 Plugin 的更新状态把远端响应文本转换为可执行命令向从未安装过提醒器版本的旧用户主动推送消息。3. 设计原则与安全不变量六条安全不变量是整套协议的“宪法”后续所有组件、缓存与发布流程都围绕它们展开。用户决定提醒器只报告事实和候选版本用户忽略、稍后处理或继续使用旧版本时不产生任何安装副作用。非阻断版本检查不是 Skill 主工作流的前置成功条件。超时、断网、缓存损坏、远端格式错误和运行时缺失均转换为静默结果随后继续原任务。本地决策远端只声明发布元数据是否显示提醒、是否已提醒过、何时再次检查全部由本地逻辑与本地状态决定。不执行远端输入远端 manifest 不含updateCommand提醒器不把远端字符串传给 shell、包管理器、脚本解释器或动态模块加载器。只写缓存提醒器仅能写入自己的系统缓存目录实现中不存在写入 Skill 根目录、Agent 配置目录或项目目录的路径。不以版本号作为提醒事件的唯一身份version只用于比较和向用户解释远端候选发布 ZIP 的 SHA-256 用于构造提醒eventKeyGit tree SHA 用于发布门禁。摘要只能证明候选内容一致不能单独证明发布者可信本地快照不保存自身 ZIP digest避免生成自引用摘要。4. 方案范围v0.1 支持的模式与运行时基线设计文档规划了三种触发模式其中 v0.1 只实现第一种模式触发方式Agent 额外工具调用v0.1 状态Skill 激活调用SKILL.md在首个候选产物存在后调用独立检查脚本每次激活最多 1 次已实现CLI/MCP 顺带检测未来由原本必经的 CLI 或 MCP 调用附带检测结果0未实现需单独评审宿主 Hook 调用未来由 SessionStart 或 Plugin Hook 在会话边界调用通常为 0未实现需单独评审注意CLI/MCP 与 Hook 只是“可复用同一契约”的未来适配点不是当前 Archify 行为它们不得在未经独立设计、测试和用户可见性评审时接入正常 CLI 输出。缓存只能减少网络请求不能消除纯SKILL.md模式下那次 Agent 工具调用对短小、纯提示词型 Skill评审时需要确认该额外调用是否值得。运行时基线MVP 使用无第三方依赖的 Node.js ESM 脚本声明 Node.js 18 兼容Node.js 不可用时返回静默结果。若目标用户中缺少 Node.js 的比例不可接受再评估单文件二进制或宿主专用实现。5. 组件与目录结构建议发布包包含以下内容仓库中已实际落地archify/ ├── SKILL.md ├── skill-release.json └── scripts/ ├── check-update.mjs └── update-contract.mjs外部组件https://tt-a1i.github.io/archify/skill-updates/archify/stable.json system-cache-dir/archify-skill/version-version-sha256-prefix/committed-generation/state.json仓库实际文件与职责对应如下archify/SKILL.md定义何时调用检查器以及不同状态对应的 Agent 行为见其## Update awareness一节archify/skill-release.json随当前安装版本发布的本地身份快照archify/scripts/update-contract.mjs零依赖纯模块唯一拥有 SemVer、严格字段、UTC 时间、固定来源和发布说明 URL 契约运行时、发布门禁和包内烟测共同复用archify/scripts/check-update.mjs执行缓存、HTTP、版本比较与提醒去重stable.json维护者发布的最新稳定版元数据仓库内实样见 docs/skill-updates/archify/stable.jsoncommitted-generation/state.json按已安装版本分片的完整检查与提醒快照不随 Skill 更新覆盖同一版本的多个 Agent 共享去重不同版本互不重置状态。关于缓存目录命名检查器按“本地完整版本的 SHA-256 前缀”分片源码中取前 24 位十六进制见versionCacheDirectory因此state.json实际位于形如version-24位hex/committed-generation/state.json的路径下。6. 运行流程一次检查的生命周期设计文档给出了完整的判定流程图核心决策链如下Skill 被激活首个候选产物存在后运行check-update.mjs若nextCheckAt尚未到期 → 返回silent读缓存否则无条件GET stable.json请求与校验失败 → 记录退避时间并返回silent候选 SemVer 未严格高于安装版本 → 刷新缓存并返回silent/current候选 digest 已确认展示 → 按策略返回silent否则返回update_availableeventKeyAgent 展示提醒 → 确认eventKey已展示 → 继续原始任务。对应到源码 archify/scripts/check-update.mjs 的checkForUpdate主流程检查步骤可以拆成七步读取本地身份读取随包发布的skill-release.json确认本地skillId、channel、版本、官方仓库和固定 manifest URL完成条件是得到合法本地身份或安全返回silent。检查缓存读取用户缓存并检查nextCheckAt未过期则直接使用缓存否则进入一次远端检查。无条件请求使用硬编码可信 origin 请求stable.json不持久化或回传服务端 validator。源码中DEFAULT_MANIFEST_URL固定为https://tt-a1i.github.io/archify/skill-updates/archify/stable.json且fetchCandidate会在 URL 不匹配时直接抛错。校验响应校验响应大小、JSON schema、skillId、channel、来源和必要字段候选身份可被本地确定地接受或拒绝。版本比较与去重先比较候选与本地版本的 SemVer precedence只有严格更高的稳定版本才是更新随后用不可变 digest 构造事件身份并检查是否已经展示。同版本或降级候选即使 digest 不同也必须返回current。Agent 展示并确认Agent 只在update_available时展示提醒然后确认该eventKey已展示确认状态与实际用户可见行为一致。继续原任务版本检查绝不取代或缩减原请求。7. 本地发布快照skill-release.jsonskill-release.json随每个版本构建不由运行时修改。设计文档示例为 v3.1.0仓库当前实样为 2.17.0-dev.1{ schemaVersion: 1, skillId: archify, channel: stable, version: 3.1.0, source: { repository: https://github.com/tt-a1i/archify }, updateManifestUrl: https://tt-a1i.github.io/archify/skill-updates/archify/stable.json }本地快照使用严格字段白名单并由 release identity 门禁保证与package.json完整版本一致。源码 archify/scripts/update-contract.mjs 的validateLocalRelease要求顶层字段必须是schemaVersion、skillId、channel、version、source、updateManifestUrl六项不多不少用键排序比较实现schemaVersion 1、skillId archifysource只允许repository字段且必须等于https://github.com/tt-a1i/archifyupdateManifestUrl必须等于固定的 GitHub Pages manifest URLchannel 必须与版本号匹配prerelease 版本 →development否则 →stable。读取安全运行时只接受不超过 4 KiB 的非符号链接普通文件通过固定文件句柄执行有界读取路径到句柄绑定期间发现替换即拒绝绑定完成后只从该固定 inode 读取。FIFO、设备文件、符号链接和超限内容都按无效安装静默处理不会阻塞 Skill 主流程。这些约束在源码的readJsonFile、assertBoundedRegularFile、isSameFile中逐一实现archify/scripts/check-update.mjs。为什么本地快照不存 ZIP digest候选的 tree/archive digest 只存在于外部 stable manifest。如果把当前 ZIP 的 digest 写进 ZIP 内部会形成无法收敛的自引用。运行时永远不会用远端声明重写本地身份。8. 远端发布协议stable.json 与字段约束远端协议是提醒器唯一信任的数据源。设计文档示例v3.2.0{ schemaVersion: 1, skillId: archify, channel: stable, version: 3.2.0, publishedAt: 2026-08-28T08:00:00Z, source: { repository: https://github.com/tt-a1i/archify, ref: v3.2.0, treeSha: 8f11d3... }, artifact: { sha256: 56da... }, summary: 改进大型项目扫描与架构图布局, releaseNotes: https://github.com/tt-a1i/archify/releases/tag/v3.2.0, severity: normal }仓库当前真实 manifest 见 docs/skill-updates/archify/stable.jsonv2.16.0含完整 40 位 treeSha 与 64 位 sha256。8.1 字段约束表字段要求schemaVersion必须为检查器支持的整数版本skillId必须与本地快照完全一致channelv0.1 仅接受stableversion必须是严格的稳定 SemVerMAJOR.MINOR.PATCH不接受 prerelease、build metadata 或数字前导零publishedAt必须是秒精度、真实日历日期的 UTCYYYY-MM-DDTHH:mm:ssZv0.1 以稳定版 annotated tag 的 tagger time 为权威值运行时不把它用于调度或事件身份source.repository必须匹配本地允许的官方仓库source.ref必须精确等于vversion只能验证不能拼接成 shell 命令source.treeSha必须是发布 tag 中archify/的 40 位小写 Git tree SHAartifact.sha256必须是发布archify.zip的 64 位小写 SHA-256用于提醒事件身份summary必填纯文本1–160 个字符v0.1 校验但不直接输出远端文本releaseNotes必须逐字节等于https://github.com/tt-a1i/archify/releases/tag/vversion不接受显式端口、大小写变体、查询或片段severitynormal或security两者都不触发自动安装响应体硬上限 32 KiB重定向禁用非成功响应、错误媒体类型和声明超限的响应会先取消未读 body再静默失败。这些校验在 archify/scripts/update-contract.mjs 的validateStableUpdateManifest中实现它检查字段精确集合、isStableCoreVersion、ref vversion、HEX_40的 treeSha、HEX_64的 sha256、validateCanonicalUtcTimestamp真实日历时间回验、summary 的 1–160 长度与CONTROL_OR_BIDI控制字符过滤、validateReleaseNotesUrl的逐字节匹配。SemVer 实现细节parseSemver与compareSemver支持 BigInt 数值比较避免超大版本号溢出、prerelease 语义2.16.0-dev.9 2.16.0数字段按数值比较、前导零拒绝、build metadata 忽略2.16.0build.9 2.16.0。这些行为有专门的单测覆盖见下文 §13。9. 本地缓存协议状态机、并发协调与容量边界本地缓存是整套设计中最复杂的部分。完整committed-generation/state.json示例{ schemaVersion: 1, skillId: archify, installedVersion: 3.1.0, check: { nextCheckAt: 2026-08-31T08:00:00Z, consecutiveFailures: 0 }, notification: { offeredDigests: [ sha256:56da... ], acknowledgedDigests: [ sha256:12ab... ] }, candidate: { version: 3.2.0, targetDigest: sha256:56da..., severity: normal, releaseNotes: https://github.com/tt-a1i/archify/releases/tag/v3.2.0 } }缓存状态载荷只持久化“调度、去重和展示候选”所需的最小事实eventKey始终由skillId与targetDigest确定推导远端publishedAt在网络边界校验后不进入缓存未被行为读取的观测时间不成为持久协议字段。state.json只接受不超过 64 KiB 的非符号链接普通文件需要解析的active-claim/owner.json只接受不超过 1 KiB读取器使用O_NOFOLLOW、O_NONBLOCK并在读取前完成“路径 → 句柄 → 路径”的身份绑定随后最多从固定 inode 读取“上限 1”字节。缓存叶文件还必须位于读取前后身份不变的真实committed、pending或active-claim父目录中。9.1 两阶段确认offered → acknowledged检查器输出提醒并不等于用户已经看见。为了避免 Agent 未展示结果却把版本永久标记为已提醒采用两阶段状态check返回update_available和eventKey把 digest 加入尚待确认的offeredDigestsAgent 展示提醒后执行轻量本地确认把该事件从offeredDigests移入acknowledgedDigests。确认调用只写缓存、不联网仅在真正出现新候选时增加一次工具调用。确认按eventKey中的 digest 匹配已 offered 集合而不要求它仍是当前候选——因此刷新从 A 切到 B 时刷新期间已经展示的 A 仍可可靠确认。确认集合在当前安装版本的缓存分片内持久保留所以 manifest 即使经历 A → B → A 回退已确认的 A 也不会再次提醒。acknowledgedDigests不采用概率结构或有损淘汰不会因容量治理而重新提醒已确认事件。单一安装版本在积累到 64 KiB 极限后会进入静默退避、不再接纳新提醒直至该版本分片被替换或清理。这是 v0.1 用“永不返回不可确认提醒”换取精确去重的显式边界源码中encodeRecoverableState在提交前模拟全部 offered 确认闭包与最坏失败退避见 archify/scripts/check-update.mjs。9.2 目录准备与路径安全缓存目录准备也属于协议边界。检查器先把位于用户主目录或系统临时目录下的受信任前缀解析成真实路径再从文件系统根开始逐级lstat已有组件必须是真实目录缺失组件只按单层创建符号链接和其他文件类型一律拒绝。创建完成后使用 BigInt 设备号/inode零 inode 且birthtimeNs可用时回退到 birthtime 与文件模式两者都不可用时失败关闭重验全部组件并把已验证的规范路径和祖先快照作为本次进程的缓存 token。每次mkdir、独占写入、改名、非递归清理都在操作前后复验同一 token。发现身份变化、结果缺失或类型错误时返回silent/cache-unavailable不发起后续网络请求也不把提醒或确认报告为成功。9.3 generation 与 active-claim 并发协调缓存根目录下面按本地完整版本的 SHA-256 前缀分片。未过期缓存直接读取最高完整、合法的committedgeneration不创建协调记录。需要写入时检查器先以原子mkdir创建永久的reserved-generation分配标记再只写自己的pending-generation目录reservation 从不改名、删除或复用generation 只接受最多 20 位十进制文本分配器从全部合法操作目录中选择最小未占用编号超长或非规范伪名称不参与分配不能借稀疏高水位制造超长文件名并永久阻断检查固定的active-claim负责网络请求互斥候选 writer 先在自己的预填充 claim 目录写入 generation 与随机 token每轮先检查固定 claim只有路径不存在时才通过原子 rename 晋升绝不直接覆盖空目录晋升成功后必须确认自己的 pending lease 仍新鲜并在最终缓存 token 复验之后、调用 fetch 之前再次确认 active generation/token任何一个可观测等待点失权都取消而不发请求即使两个进程都读到“没有 pending”的旧快照在 lease 有效的协作竞态中也只有一个能进入 fetch30 秒硬 lease 过期后后继 writer 才把旧 claim 原子移动到按旧实例稳定身份命名的退役目录提交不是“读 token 后覆盖固定文件”writer 在 mutation 前后验证自己仍持有同一 active generation/token更高 generation 接管后会把所有较低 pending 逐个原子改名为唯一的fenced目录再重新读取最高 committed 快照、应用本次 mutation、写完完整 state最后把自身 pending 原子改名为 committed。v0.1 把协调目录视为追加式本地 journalreserved、完整committed、fenced、cancelled、retired-claim和discarded-claim均保留避免在并发路径引入递归清理或 generation 复用。代价是同版本分片的 inode 数和readdir成本会随写入次数增长v0.1 不在运行路径内压缩 journal。升级产生的新版本分片天然与旧 journal 隔离。10. 检查器输出协议一行 JSON检查器 stdout 只输出一行 JSON诊断日志写入受控 debug 日志或 stderr并且默认关闭。CLI 入口与参数解析见 archify/scripts/check-update.mjs。10.1 静默{status:silent,reason:cache-valid}可用reason全集源码中逐一对应分支cache-valid、current、already-notified、runtime-unavailable、check-failed、invalid-manifest、invalid-local-release、cache-unavailable、check-in-progress、disabled、invalid-clock、invalid-acknowledgement、invalid-arguments所有silent状态对用户表现一致Agent 不输出“当前已是最新版”或内部错误。10.2 有可选更新{ status: update_available, eventKey: archifysha256:56da..., installedVersion: 3.1.0, latestVersion: 3.2.0, targetDigest: sha256:56da..., severity: normal, summary: Archify 3.2.0 is available; see the official release notes for details., releaseNotes: https://github.com/tt-a1i/archify/releases/tag/v3.2.0 }注意summary由已安装检查器根据已校验版本号生成固定文案不透传远端summary源码notification()中硬编码为Archify ${version} is available; see the official release notes for details.。manifest 仍保留供发布审核使用的简短摘要但不能借提醒通道向 Agent 注入动态指令。10.3 展示确认Agent 只在提醒已经对用户可见后运行--ack eventKey{status:acknowledged,eventKey:archifysha256:56da...}无效、过期或竞争失败的确认返回silent协议不联网也不改变安装内容。10.4 安全更新安全更新使用相同协议仅将severity设为security。它可以使用更醒目的文案但在 v0.1 中仍由用户决定是否更新。11. 检查策略频率、超时与退避建议默认值源码 archify/scripts/check-update.mjs 中的常量与之对应参数默认值正常检查 TTL72 小时随机 jitter±20%HTTP 总超时1000 毫秒单次检查重试0响应体上限32 KiB更新通道stable同一 digest 主提醒1 次已确认 digest 再次提醒不提醒失败时不在当前调用内重试第一次失败后退避 6 小时连续失败后退避 24 小时nextFailedCheck按consecutiveFailures饱和到 2 档。失败状态不能被解释成“当前已经是最新版”。新候选导致状态容量超限时使用同一退避节奏并删除已经被成功刷新撤回的旧candidate防止退避期间重复展示旧候选。关键语义只有失败刷新保留 last-good candidate一次成功且通过全部契约校验的刷新以当前 manifest 为权威——如果维护者撤回先前较高版本并把 stable manifest 恢复为当前版或更低版检查器必须提交该结果并返回current不能继续展示已撤回候选测试a successful refresh withdraws a previously offered higher candidate验证了这一点。每次 TTL 到期后执行一次无条件GETv0.1 不持久化或回传ETag等不透明服务端 validator避免把每客户端唯一值变成长生命周期关联标识304因此一律按普通 HTTP 失败处理测试an HTTP 304 is always a failed unconditional refresh验证。展示确认会按不受系统时间回拨影响的单调时钟在 1.2 秒内有界等待ACK_LOCK_WAIT_MS若自己的 generation 被更高 writer fence 则重新分配并重试避免用户已经看到提醒却丢失 ack。12. Skill 指令契约SKILL.md 的“Update awareness”设计文档建议在SKILL.md中保持简短把确定性逻辑留给脚本。仓库的 archify/SKILL.md 已经落地了该段核心语义如下After the first candidate exists, run the packaged checkerscripts/check-update.mjsonce with Node and continue the requested workflow. If the command cannot run, continue without mentioning the check.silent→ 继续不提版本检查update_available→ 用会话语言展示一条紧凑提醒说明当前版本、候选版本、本地固定摘要与官方发布说明链接severity为security时以克制的警告强调标注为安全更新只改变强调程度不改变用户自主权明确说明已安装 Skill 未变、是否更新何时更新由用户决定允许翻译本地固定句子但绝不引用、概括或翻译远端 manifest 的 summary提醒可见后用同一检查器--ack eventKey确认然后继续用户原任务。该段只定义“状态 → 行为”映射。HTTP、缓存、版本比较和安全校验全部由脚本负责避免不同 Agent 自行解释实现细节。The notice is information, not permission—— 通知不是授权。用户或宿主可设置环境变量ARCHIFY_UPDATE_CHECK_DISABLED1完全关闭检查CLI 直接返回silent/disabled不联网也不读写提醒状态见源码runCli首行判断。13. 测试方案不变量如何被机器证明设计文档列出的测试方案在仓库中由 archify/test/update-notifier.test.mjs约 3300 行完整实现。以下用单元测试样例印证关键设计点SemVer 比较覆盖stable、prerelease、降级、build metadata、BigInt 大版本号、前导零拒绝都有断言如compareSemver(2.16.0-dev.2, 2.16.0-dev.10) -1、compareSemver(2.16.0build.9, 2.16.0build.1) 0。同一版本/降级保护a changed digest never bypasses same-version or downgrade protection—— 同版本或降级候选无论 digest 是否变化都返回current。成功刷新撤回、失败刷新保留成功刷新可撤回先前较高候选失败刷新保留 last-good 未确认候选a failed refresh preserves the last-good unacknowledged candidate。两阶段确认闭环a newer immutable candidate is re-offered until the visible notice is acknowledged验证了update_available → --ack → already-notified的完整路径且确认前不重复发网络请求。回退不重复提醒an acknowledged candidate stays suppressed after a later candidate and manifest rollback验证 A → B → A 回退后已确认的 A 不再提醒。ETag 不持久化不回传opaque response validators are neither persisted nor replayed断言请求不带if-none-match且持久化状态不含 etag 字段。容量边界多组测试精确卡在 64 KiB 与 64 KiB1 字节边界验证“恰好可确认、超限被忽略、不剪枝历史、不返回不可确认提醒”a saturated exact acknowledgement history never returns an unacknowledgeable offer等。失败退避饱和failure backoff saturates safely instead of overflowing the cache counter防止consecutiveFailures溢出。并发与 fencing测试通过暂停mkdir/readdir/open/rename系统调用制造竞态窗口验证 reservation 不被复用、低代被 fence 后不能提交、恢复的旧 owner 无 pending 路径可提交、不删除新 owner 的唯一目录等。损坏与恶意文件测试用mkfifo创建 FIFO、符号链接、空目录、错误owner.json验证在 30 秒 lease 内按 busy 处理、超时后按稳定实例身份退役且绝不永久阻塞。集成测试要求Codex、Claude Code、Cursor、OpenCode 至少各验证一次激活流程有更新时提醒出现后原任务继续完成无更新时用户看不到任何版本检查文案断网条件下端到端额外等待不超过配置总超时Agent 未展示提醒时候选不会被错误永久标记为已读debug 日志不包含项目路径、用户输入和响应正文之外的敏感数据。安全不变量测试检查器不引用 shell 或进程执行 API源码确实未导入child_process远端字段和验证时可见的符号链接不能把写入导向 Skill 根目录、项目目录或 Agent 配置目录任意远端 manifest 都不能改变请求 origin、缓存路径或本地命令恢复性错误统一退出成功并返回有效silentJSON。14. 失败处理速查表故障行为下次检查DNS、离线、超时silent/check-failed6 小时后HTTP 304silent/check-failed无条件请求不接受 304退避HTTP 4xx/5xxsilent/check-failed退避响应超过上限silent/invalid-manifest首次 6 小时连续失败 24 小时JSON/schema 错误silent/invalid-manifest首次 6 小时连续失败 24 小时skillId/仓库不匹配silent/invalid-manifest首次 6 小时连续失败 24 小时验证时缓存根或祖先是符号链接/非目录或关键 mutation 前后身份变化silent/cache-unavailable停止后续联网且不报告提醒/确认成功下次激活重新验证state.json/owner.json是 FIFO、符号链接、非普通文件、超限或损坏不跟随该叶文件回退合法 generation或按 claim lease 恢复正常 TTL新候选使提交/确认闭包/失败退避投影超过 64 KiB不返回提醒保留精确历史、撤销旧候选并silent/cache-unavailable首次 6 小时连续失败 24 小时本地发布快照损坏silent/invalid-local-release不联网修复安装后Node.js 不可用跳过检测下次激活并发检查新鲜 lease 内一个进程检查其余用缓存跨 lease 暂停可能产生重复幂等 GET但只有当前 generation 可提交正常 TTL系统时间回拨对异常时间戳设上限并重新计算正常 TTL无论哪种故障都不能改变主任务结果或安装内容。15. 隐私与安全15.1 最小网络披露检查器在成功检查后的 72 小时 ±20% TTL 到期时才会再次向固定 URL 执行静态无条件GET失败后若 Skill 再次被激活则在首次 6 小时、后续 24 小时退避到期时允许重试。它不回传服务端ETag也不上传本地安装版本Agent 宿主名称项目路径、仓库名称或文件内容显式的 Skill 使用次数、频率字段或用户输入设备标识和账户标识。服务端仍会自然获得 IP、请求时间和常规 HTTP 元数据由于检查在 Skill 使用期间触发该请求时间也会泄露“TTL 到期后至少发生过一次使用”的粗粒度活跃信号设计文档要求如实披露这一点。15.2 信任边界更新 URL 和允许的官方仓库由本地发布包固定releaseNotes只作为用户可见链接不作为指令来源远端summary作为不可信纯文本校验长度和控制字符但不进入检查器输出用户看到的是本地固定摘要远端字段不能决定本地文件路径和可执行程序缓存路径由本地常量和操作系统 API 构造不接受远端片段检查器不导入child_process也不提供 shell 执行接口。15.3 残余风险v0.1 如实披露HTTPS origin 或发布账号被劫持时攻击者可能伪造“存在新版本”和发布说明链接checksum 能证明候选身份稳定不能证明发布者善意Skill 指令是否稳定执行仍受具体 Agent 宿主影响纯 Skill 模式需要一次额外工具调用会增加少量时延和上下文开销展示与本地确认不是同一原子动作若 Agent 在两者之间崩溃、确认失败或多个 Agent 同时读取未确认事件同一候选可能重复提醒。系统选择at-least-once 展示避免把用户尚未看到的提醒误记为已确认30 秒 hard lease 只能约束本地提交不能给已发出的 HTTP 请求提供远端 exactly-once要消除重复 GET 需要远端幂等键或 fencing token超出静态 GitHub Pages v0.1 的能力Node 18 没有稳定、跨平台的openat/renameat目录句柄 API能以同一用户权限精确插入两个系统调用之间、替换 canonical 祖先的恶意进程不属于本地缓存安全边界。后置复验会阻止它得到成功提醒或成功确认但无法承诺零外部单路径 mutationroot/管理员、映射盘或网络挂载重映射同样不在保证范围内。后续可通过签名发布、透明日志或宿主原生 Marketplace 降低来源风险但不属于 v0.1。16. 用户体验与交互语义16.1 普通更新⬆ Archify Skill v3.2.0 可用你正在使用 v3.1.0。有可用的新版本详情请查看官方发布说明。查看变更说明是否升级由你决定本次任务继续使用当前版本。16.2 安全更新⚠ Archify Skill 发布了安全更新 v3.2.1你正在使用 v3.1.0。建议查看安全说明后决定是否升级。查看安全说明当前版本保持不变。16.3 交互语义用户忽略提醒不更新不追问继续原任务用户要求查看变更只打开或概述发布说明用户要求更新v0.1 只提供官方升级入口执行更新属于后续独立流程。v0.1 只实现“忽略”和“查看变更”Snooze/Skip 不预留运行时字段待 v0.2 重新评审状态语义。17. 发布与旧版本迁移两阶段稳定版发布本仓库原先由main:/docs直接发布该模式不会等待普通 CI因此不能承载 manifest 的发布门禁。启用本方案前仓库管理员必须在Settings → Pages → Build and deployment → Source将来源一次性切换为GitHub Actions。仓库内的deploy-pagesjob 只在mainpush 上运行并显式依赖全部测试、ZIP freshness、包内 smoke 与 published-manifest 门禁切换前不得发布新的 stable manifest。稳定版发布顺序发布准备提交更新包版本、Changelog 与确定性archify.zip但docs/skill-updates/archify/stable.json仍保留紧邻的上一稳定版。stable tag 工作流拒绝任何已经等于或高于待发布版本的公共 manifest然后烟测并创建带archify.zip资产的 GitHub Release。manifest 跟进提交Release 成功后单独提交 manifest填入该 tag 的archifytree SHA、最终 Release 资产 SHA-256以及 annotated tag 的 canonical UTC tagger time。GitHub Releasepublished_at只作为运营观测值不进入 v0.1 运行时身份。后续 commit 更新stable.jsonCI 通过 GitHub API 要求 manifest 精确等于当前 latest stable Release不是任意历史 Release确认目标非 draft、非 prerelease下载其中的archify.zip并要求它逐字节等于目标 tag 根目录提交的archify.zip。从首个携带确定性构建器的版本起CI 还会在独立 worktree 从该 tag 重建 ZIP 并再次逐字节比较仅历史 bootstrap 版本允许以 tagged blob 作为闭环。最后把资产 SHA-256 与 manifest、目标 tag 的archifytree 同时核对。仓库内的发布门禁脚本 scripts/check-stable-update-manifest.mjs 实现了 treeSha 与归档 sha256 的双重比对。部署只有全部 CI job 成功deploy-pages才上传docs/artifact 并公开新候选部署前还会确认本次GITHUB_SHA仍是远端main因此完成较晚的旧 workflow run 不能把站点回滚。release identity 只允许公共 manifest 等于最新稳定版或在稳定版发布准备窗口中暂时等于紧邻的上一稳定版更旧版本不能借两阶段流程长期滞后。工作流失败时公共 manifest 仍指向上一条完整 Release不会提醒用户访问尚不存在的发布说明。旧安装用户迁移旧版本没有检查逻辑无法通过本方案被远程唤醒。首次上线需要一次独立迁移活动发布明确标注“更新提醒能力迁移版本”的 Release、在 README 顶部增加阶段性升级公告、置顶 Issue 或 Discussion、通过社群和文章渠道通知、提供经过验证的官方重新安装入口。完成这次人工迁移后新版本用户才进入持续的内置提醒链路。18. 分阶段实现路线图v0.1通知闭环已落地本地skill-release.json远端stable.json无依赖检查脚本72 小时 TTL、无条件 GET、1 秒超时、失败静默SemVer 更新资格判断、digest 事件身份和确认后去重Agent 提醒后继续原任务只提供发布说明不执行更新。v0.2用户提醒偏好SnoozeSkip this version关闭普通更新提醒但保留安全提示提醒历史和调试诊断。后续独立提案识别原生 Plugin/Extension 更新所有者对接gh skill或其他跨 Agent 更新管理器展示脚本、MCP、Hooks 和权限差异签名发布、安装验证和回滚。这些能力不应通过扩充 v0.1 检查脚本顺带实现应分别评审其权限与生命周期。19. 验收标准与评审v0.1 达到以下条件后可进入小范围发布100% 更新检查仅执行只读网络请求和本地缓存写入0 条代码路径可以下载、安装或执行候选版本内容缓存命中时脚本执行时间目标低于 50 毫秒不计 Agent 工具调用调度网络检查的额外等待由 1000 毫秒总超时严格封顶同一候选 digest 成功确认后不再提醒正常路径展示一次展示与确认间故障允许重复所有恢复性故障均不阻断用户任务用户未明确选择后续动作时Skill 安装状态完全不变提醒内容包含当前版本、候选版本、摘要和官方发布说明至少在四个目标 Agent 中完成真实调用验收。设计文档还给出了可复制的评审结论模板结论 / 必须修改 / 延后到 v0.2 / 已接受的关键取舍检查周期、提醒去重、支持运行时、安全更新交互、远端 manifest owner供维护者与评审人在 Issue #167 的讨论中直接使用。20. 总结Archify 的内置可选更新提醒器演示了一种“提醒与更新解耦”的最小可行方案以skill-release.json固定本地身份以严格字段契约的stable.json承载远端元数据以check-update.mjs完成缓存调度、SemVer 比较与 digest 去重并以 offered/acknowledged 两阶段确认保证“提醒可见才去重”。六条安全不变量用户决定、非阻断、本地决策、不执行远端输入、只写缓存、不以版本号作唯一身份把每一次版本检查都限制为一次低频只读 GET 和一次受控的本地状态写入——它从不下载、不安装、不执行也因此可以在 Codex、Claude Code、Cursor、OpenCode 等宿主间安全复用。如需继续深入建议依次阅读设计文档 → 市场调研 → 契约模块 → 检查器实现 → 不变量测试 → 发布门禁脚本。【免费下载链接】archifyAgent skill for beautiful, verifiable architecture, workflow, sequence,>项目地址: https://gitcode.com/GitHub_Trending/arch/archify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考