企业官网建设流程全解析

Agnes Harness（AGH）是一款面向 FDE 的可插拔 Agent 框架，其插件安全治理覆盖安装、信任、能力哈希绑定与回滚的完整生命周期：每一步都用内容哈希与能力指纹互相校验，确保你信任的永远是"你预览过的那一份"插件代码。本文带你从零看懂这套机制。

为什么插件需要一套"安全生命周期"

AGH 的口号是 "Built for trust"（为信任而生）。在 安全与信任指南 中，项目把信任拆成三层边界：

关键点在于：信任是版本级、内容级的。信任 v1 不等于信任 v2；换了任何一个字节，之前的信任决定自动失效。这正是 AGH 插件管理的核心设计，实现见 packages/package-manager/。

第一步：先预览，后安装——不哈希确认绝不落盘

Web 界面的插件管理页可以一眼看到装了什么、来自哪里、是否启用：

在 Web 的「设置 → 插件管理 → 从来源安装」，或用 CLI 执行package inspect，你会先看到一份预览：

• 包 ID、版本、来源（npm / 本地目录 / 市场）
• 内容哈希（integrity）与能力哈希（capabilityHash）
• 能力声明、告警（warnings）与阻断项（blockers）

有阻断项的包无法通过"点确认"绕过，必须解决原因后才能继续。

安装流程有一个容易被忽略的细节：包先写入临时的 staging 目录（形如.stage-<uuid>），提交前会对目录树重新计算一次哈希，与预览时的哈希比对，不一致就报E_LOCK_MISMATCH（"package preview is stale"）。这保证了"你看到的预览 = 实际落盘的代码"。相关实现在 staging.ts 与 manager.ts。

📌 成功安装的新包默认是禁用状态——装上了 ≠ 生效了，还需要下一步的信任审查。

第二步：信任绑定——两个哈希对不上就拒绝

启用插件前需要一次信任决定（trust decision）。CLI 的命令形如：

node packages/cli/dist/local/agnes.mjs package trust <包ID> <INTEGRITY> <CAPABILITY_HASH>

注意它有两个参数：integrity（整包内容哈希）和capabilityHash（能力指纹）。在 lifecycle.ts 中，系统会把你的决定与锁文件里的包快照逐项比对——任何一项不一致，直接报E_WORKSPACE_UNTRUSTED（trust decision differs from the package snapshot）。

这意味着：

1. 包被改动过（哪怕一个字节）→ 旧信任作废；
2. 能力声明被偷偷加了一项 → 能力哈希变了 → 旧信任作废；
3. 信任决定本身是"绑定到快照"的，不能含糊地说"我信任这个包"。

CLI 信任流程演示：

信任门：四道检查一次过

即使哈希对上了，trust-gate.ts 还会依次检查四道门：

其中"发布隔离期"是个有意思的设计：新发布的包要"晾"一段时间才能被信任，降低抢注和快速换壳攻击的空间。

危险能力：想"跳过检查"也不行

trust-gate.ts 中还定义了"危险能力"判定：声明了通配符网络访问（*主机），或同时声明tools.invoke+subagent的包，不允许通过 force/skip 路径强行放行。这类包必须走完整审查。

第三步：能力哈希是怎么算出来的

能力指纹不是简单JSON.stringify。integrity.ts 中的做法是：

1. 对贡献项（contributions）和依赖（dependencies）做规范化序列化（canonical：对象键排序、数组保序），消除格式差异；
2. 对扩展类贡献补上默认runtimeSupports，避免"没写"和"写了 in-process"被判成两种能力；
3. 计算SHA-256得到 capabilityHash。

能力集合本身来自扩展清单的声明，解析逻辑见 capabilities.ts：tools、hooks、slots、services、network、network.publicRead、events、tools.invoke、artifacts、subagent等。注释里有一句很直白："never infer grants from truthy prefixes"（绝不从布尔前缀推断授权）——能力必须是明确声明的。

第四步：更新与回滚——旧版本有指纹，回滚要重新审查

更新时自动保留上一版

执行更新时，系统把当前版本完整快照为previous（锁文件中记录其treeIntegrity），并在包存储中备份为.previous-<hash>目录，见 store.ts。同时 assertNoReferences 会检查有没有别的包依赖它、profile 或部署工作区是否还引用着旧能力——有引用就报 "package has active references"，拒绝更新。

回滚不是"一键时光倒流"

回滚时（manager.ts）：

1. 先验指纹：对保留的上一版目录重新算哈希，与previous.treeIntegrity不符就报previous package tree differs——备份被改过，回滚直接失败；
2. 再验元数据：重新 inspect 上一版，贡献项与依赖的规范化结果必须和锁文件记录一致；
3. 默认落回"未信任 + 禁用"：普通回滚完成后，目标是trusted: null, enabled: false，你需要重新检查哈希、重新信任、重新启用——回滚本身不自动继承任何信任。

官方文档也提醒：回滚依赖"保留的上一版"，保留是有界的，不是任意历史版本仓库；被吊销、删除或无法验证的快照不能被自动复活。

每一步都留下审计记录

每次安装/信任/启用/更新/回滚/删除提交后，都会追加一条审计事件（见 audit.ts）：操作者、来源哈希、旧/新状态、capabilityDiff（能力差异）等，文件以 0600 权限追加写、只增不改。事后审计"某次能力变更是谁放行的"，直接查审计日志即可。

新手操作速查表

🧭 完整操作路径参考：安装、启用、更新与删除指南，插件开发视角见 插件开发文档。

结语：哈希是"记忆"，流程是"牙齿"

AGH 的插件安全治理思路可以浓缩成一句话：预览定指纹，信任绑指纹，变更换指纹，回滚验指纹。你信任的不是"某个名字的软件"，而是"某一组字节 + 一份能力声明"。理解了这个闭环，你就能放心地把第三方能力装进自己的 Agent，也能在出问题时用审计日志把责任链完整还原。