用真实任务，理解权限与依赖。
Test tasks. Trim permissions.
Permsift 在隔离副本里执行你指定的安装、测试或构建任务，记录任务结果、权限边界与运行条件。在这个共同底座上，你可以收缩权限，也可以独立观察依赖。两条路径都保留可复查的证据。
当前为 v0.13，本地 CLI（任务执行限 macOS），隔离后端为 Anthropic Sandbox Runtime 0.0.77。配置解释与保存报告的离线分析不需要运行沙箱。结论限定于本次任务、环境与采集范围。见 0.13.0 交付说明。
| 你想回答的问题 | 从哪里开始 | 后续操作 |
|---|---|---|
| 这组任务能在什么权限下完成？代码改变后旧规则还有效吗？ | 权限入门：explain → run | 有明确收缩目标时 tighten；审阅后 adopt，变更后 check |
| 这次测试/构建观察到了哪些依赖？改变代码或依赖后发生了什么？ | 依赖观察入门：explain → observe | inspect 查询包；compare 比较两次保存记录 |
依赖观察每个任务执行一次，不需要先进行权限搜索。缺少加载记录不表示包无用，也不生成删除建议。
原有 lint、类型检查或测试命令可以明确使用 assertions: [{type: exit_code, value: 0}]，无需制造结果文件；检查强度取决于命令自身。新观察记录的 inspect --package 还解释谁声明了每个安装版本、入口和文件结构，并与本次加载记录区分。见 成功条件配置、按包查看及 execa 实测。
首次交给别人试用，见 试用说明与反馈模板：干净源码包、两条入门、固定外部项目维护流程及明确执行预算。npm run trial:verify 从新目录和新 npm 缓存重走接入；外部项目的缓存准备和四次沙箱安装需明确选择 --with-maintenance。
希望自己逐步体验，按 手工试用 从全新克隆开始：安装与 doctor → 权限建立/采用/变更复验 → 独立观察与比较 → 带一个自己的真实问题接入。每段都有成本和反馈提示。
要求：macOS、Node.js 22 或更新版本、npm，以及系统自带的 /usr/bin/sandbox-exec。已在 macOS 15.8、Apple Silicon、Node.js 24.21.0 上实测。其他系统版本需先通过 doctor；Linux 和 Windows 上拒绝执行沙箱任务。
在项目目录中执行：
npm ci --ignore-scripts
npm run build
# 先看配置、默认权限和成功条件；不运行任务或安装依赖
node dist/cli.js explain --config examples/demo/permsift.yaml --limits examples/limits.json
# 真正执行任务前，检查本机隔离能力
node dist/cli.js doctor然后选择上面的使用路径。explain --for observe 显示单次观察安排，--for tighten 显示基线/最终验证与额外搜索的关系；--for check 只解释当前宽对照配置，不冒充历史方案。见 运行前的配置解释。
想直接体验权限搜索，可以执行 npm run demo：订单金额项目的测试和构建不需要额外下载依赖。初始写范围为工作区和缓存，典型结果会缩到测试的 reports/ 与构建的 dist/。基线与最终验证各重复三次，候选和恢复另有执行成本。
完整报告位于命令输出的 .permsift/<experiment-id>/ 目录，每次默认使用新目录。结果限定于本次测试集合，不代表全局最小权限。
终端默认显示中文摘要：先给出有依据的结论与任务/边界结果，再说明影响判断的来源缺口；真正的失败、结论冲突和验证依据问题突出显示。“固定边界”“本次这组任务”“已记录”等限定保留在结论旁。inspect 结果目录 --details 只读展开完整依据，--json 保持原结构化输出。保存的 summary.json / summary.md 与详细报告继续保留候选、恢复和来源事实。当前 check 报告使用 v2，并为约定变化增加要求审阅的结论。见 终端展示 和 结果解释。
现在也可以声明少量固定保护目标，例如“构建可以生成产物，但私人配置不能读取、源码目录不能修改”。目标会进入任务的实际禁止规则，并在搜索、恢复、宽对照和修复中保持；摘要分别显示任务与逐条保护结果。首批仅覆盖工作区内已有普通文件/目录的离线任务直接访问，不覆盖安装阶段。运行 npm run protection:verify 查看完整故事和额外耗时，或阅读 保护目标。
执行时可选 --save-artifacts，保存最终方案一次验证的少量产物；之后 node dist/cli.js diagnose .permsift/EXPERIMENT 离线检查删除、清空、指定值改变和测试报告删改。按产物说明每条断言与共同结果，分开格式错误和内容不符合；不重新执行任务，不评价整体测试质量。npm run success:verify 提供无需注册表的完整例子，见 成功条件诊断。
验证通过后，可以明确采用基线。工具保存最终重复验证的必要 JSON 证据、采用理由和前一份选择；清理原实验目录后仍可追溯。
node dist/cli.js adopt .permsift/EXPERIMENT \
--config tasks.yaml --limits /absolute/path/trusted-limits.json \
--reason '采用已验证的任务权限与保护目标'
# 代码或依赖改变之后，读取已采用基线；不重新进行权限搜索
node dist/cli.js check --config tasks.yaml --limits /absolute/path/trusted-limits.json
node dist/cli.js inspect .permsift-baselines
npm run maintenance:verify默认基线存储位于配置目录的 .permsift-baselines/。采用与查看不执行任务或安装；check 仍做真实复验。成功条件、保护目标或任务列表变化时，即使当前任务通过也会明确要求审阅，返回 review_required；验证修复不会自动改变采用基线。用法、移动/历史记录、信任边界及大型项目检验见 基线采用。
# 阅读整轮权限实验、回归或观察结果
node dist/cli.js inspect .permsift/EXPERIMENT
node dist/cli.js inspect .permsift/EXPERIMENT/report.json --json
# 比较两份已经保存的 usage.json
node dist/cli.js compare before/usage.json after/usage.json
# 把一个包在所有任务中的记录放到一起
node dist/cli.js inspect usage.json --package glob-parent
# 仓库自带真实记录投影；无需准备或安装示例项目
node dist/cli.js inspect examples/reports/fast-glob-tasks.json --package glob-parent
npm run offline:verify
npm run results:verifycompare / inspect 不需要 config、limits、原项目或沙箱，默认输出终端摘要，--details 展开依据，--json 输出结构化结果。compare 可用 --output NEW_DIRECTORY 保存 comparison.json/md；它与 observe --baseline 共用比较逻辑。各任务、安装实例和来源健康度分别展示，明确区分未采集、不完整、没有记录和贡献 0 字节。差异不是自动回归判定；离线分析不能替代执行验证。用法和退出码见 离线分析，接入与收益检验见 使用记录。
observe 每个任务运行一次，记录已安装的 npm 包、Node 模块加载与本次解析来源；可比较改动前后的新增加载和版本变化。v0.10 可为直接运行项目内 tsc 的任务开启编译输入观察，解释声明文件等为何进入同一次编译，并单独比较输入包、文件和原因变化。v0.11 可读回同一次任务新生成的 esbuild metafile，解释输入、全部报告输出、每个包的字节贡献、引入链及外部引用，并比较前后变化。不启动权限搜索。
node dist/cli.js observe --config examples/projects/bundle-kit/observe.yaml --limits examples/limits.json
# 用上一次 usage.json 对比当前观察
node dist/cli.js observe --config examples/projects/bundle-kit/observe.yaml --limits examples/limits.json --baseline .permsift/PREVIOUS/usage.json示例需先 npm run examples:prepare。报告位于 usage.md / usage.json，任务断言和真实边界证据仍在 report.md。模块观察需要 Node 22.15+ 或 23.5+；类型、任意资源读取和原生工具内部不由模块钩子覆盖。没有模块加载记录，不表示依赖无用或可以删除。 编译输入和打包记录是另两种证据，各列不能相加成“实际用了几个包”，也不能据此认定某包仅是工具或可以撤权。详见 依赖使用报告、TypeScript 编译输入、esbuild 产物依赖 和 收益取舍。
# 准备固定上游源码；安装发生在 observe 的沙箱内
npm run medium:prepare
node dist/cli.js observe --config examples/third-party/fast-glob/observe.yaml --limits examples/third-party/fast-glob/limits.json# 检查本机真实沙箱能力，使用内置假数据和本地测试端点
node dist/cli.js doctor
# 验证初始策略
node dist/cli.js run \
--config examples/demo/permsift.yaml \
--limits examples/limits.json
# 自动收紧；指定目录必须尚不存在
node dist/cli.js tighten \
--config examples/demo/permsift.yaml \
--limits examples/limits.json \
--output .permsift/my-experiment
# 重新验证导出的策略；project 路径由导出文件记录
node dist/cli.js run \
--config .permsift/my-experiment/recommended.yaml \
--limits examples/limits.json
# 改代码或准备好更新后的依赖后，验证旧规则
node dist/cli.js check \
--config examples/demo/permsift.yaml \
--baseline .permsift/my-experiment/report.json \
--limits examples/limits.json也可以在构建后运行 npm link，使用 permsift doctor 等命令。项目尚未发布到 npm；package.json 的 private 标志用于避免意外发布。
--json 将完整报告输出到 stdout，进度仍输出到 stderr。--keep-workspaces 保留临时工作区，方便排查；默认清理工作区并保留报告、日志和差异。
| 退出码 | 含义 |
|---|---|
| 0 | 当前策略完成验证；check 表示兼容，tighten 仍需看 search_complete；observe 表示任务通过且范围内记录已读回 |
| 1 | 基线任务或边界断言失败，或 check 发现需要审阅的回归 |
| 2 | 配置错误、环境异常、超时、验证未完成、check 无法判断或 observe 记录不完整 |
| 130 | 用户中断，已尽可能保存不完整报告 |
- 明确测试、构建任务及成功条件。已准备依赖的项目离线运行；安装场景提供受支持的锁文件、缓存条件与域名上限。
- 编写场景文件，指定命令、初始写目录以及产物断言。需要读取收缩时再声明 initial_read_grants；默认自动生成候选，可补充手工规则。
- 在可信位置准备 limits 文件，明确批准读写授权范围和实验预算。开启读取收缩须声明 allowed_read_roots；CLI 不自动加载项目提供的最高权限。
- 先执行 explain，确认默认读取、安装/任务权限、产物清理和检查范围；选择权限路径时再 run，选择依赖路径时直接 observe。
- 权限收缩围绕具体保护目标或有价值的授权范围进行；审阅结果后可 adopt，日常变更用 check。依赖观察保存 usage.json 后可离线 inspect / compare。
例子见 场景配置 和 演示 limits。这些 limits 适用于已审核的演示项目，真实项目需要你先审查。
所有文件断言都描述本轮新产生的输出。 执行前会从工作区副本删除这些输出，避免旧产物导致假通过。不要把源文件或不可替代的输入写成输出断言。原项目不受这些删除操作影响。
路径只接受 @workspace、@cache、@tmp 三类别名及其子路径。当前支持受限的安装域名列表，不接受任意原始后端配置、宿主验证脚本或自定义环境变量。
doctor、run、tighten、check、observe五个命令。- 规则回归检查：冻结当前输入、验证旧规则、宽规则对照和经过复验的补充建议。
- 按任务独立的读写权限搜索、失败回退与恢复复测；读权限变化后重新搜索写权限。
- 自动候选及来源记录，工作区、缓存和临时目录变化，统一准备后的基线复测。
- 干净输入快照、独立缓存、输出刷新及进程组清理。
- 读取、写入、报告保护及 TCP 连接探针，配套宿主侧对照检查。
- 文件内容、JSON 值、结构化测试结果和 JUnit XML 断言。
- JSON/Markdown 报告、生效后端配置、有限日志和文件变化证据。
- 失败解释：规则变化、拒绝操作与路径、失败断言、错误摘要及恢复结果。
- 单元测试、真实 macOS 沙箱集成测试、CI 配置和可重复演示。
# 无额外依赖的读写收缩演示
npm run demo:read
# 下载固定提交的 clsx 并准备锁定依赖；仅准备阶段联网
npm run third-party:prepare
# 原始构建、五种产物的行为断言、权限搜索及导出规则重放
npm run third-party:verify读取演示会保留构建脚本、package.json、源码文件和需要加载的 dist 目录，撤销测试脚本和配置文件等读取授权。项目内假敏感文件在初始宽规则下可读，收缩后按实际授权检查是否拒绝；它们没有被额外加入 denyRead。
旧配置继续保留整个工作区可读。initial_read_grants: [] 表示不授予任何项目文件内容读取，仍保留 cwd 目录访问和固定基础读取。写权限不隐含读取，任务若加载构建产物，也需要该产物的读取授权。详见 读取规则说明 和 第三方 clsx 验证。
# 实验之外联网安装锁定依赖，禁用生命周期脚本
npm run examples:prepare
# 在真实沙箱中离线搜索，生成各项目报告与 summary.json
npm run examples:verify这三个项目均未填写 narrower_candidates：Node 原生测试生成 JUnit 报告；esbuild 打包 TypeScript 并执行构建产物；TypeScript 增量编译产生缓存，使用并删除临时文件，再验证产物。详见 代表项目说明。它们是随仓库提供的可运行项目，生态工具实际参与执行；第三方大型生产项目仍需另行验证。
失败后先阅读 report.md 的 Failure explanations，再按链接检查完整证据。拒绝日志可能缺失；报告区分“捕获到权限拒绝”和“已证明失败原因”。
# 真实 npm ci、域名收缩、断网测试/构建、冷暖缓存和导出重放
npm run install:verify
# 只运行冷缓存的收缩任务
node dist/cli.js tighten \
--config examples/install/permsift.yaml \
--limits examples/install/limits.json例子固定 clsx 2.1.1。安装阶段运行 npm ci --ignore-scripts，尝试撤销 example.org 和 registry.npmjs.org；冷缓存保留实际需要的下载域名。已有缓存从明确的固定种子独立克隆，npm --offline 安装，得到的无网络规则只适用于该缓存条件。随后执行 4 项依赖行为检查并生成构建产物，任务命令始终断网。
首版支持 npm、v2/v3 锁文件和注册表 tarball；旧安装配置保留完整工作区读取；分阶段配置支持任务读取收缩。暂不支持私有凭据、项目 .npmrc、Git/file 依赖、npm workspaces 或依赖生命周期脚本。详见 安装与网络权限。
支持能够确认父 tarball 归属的内嵌依赖：它们可以没有独立下载信息，安装后核对实际包的名称、版本和父包声明；失败时不执行后续任务。npm run bundled:verify 用本地注册表验证完整 CLI 流程，见 内嵌依赖。
npm run stages:verify在 install 内声明 initial_write_grants 后，该字段用于安装，顶层 initial_write_grants / initial_read_grants 用于安装后的任务。任务获得独立规则，能够撤销不需要的依赖写权限和包读取；确需依赖内缓存时可保留小目录。安装规则固定后的任务候选从验证过的安装状态克隆，减少重复 npm ci；最终重复验证和 run/check 仍从原始输入重新安装。
导出一份包含两段规则的配置，报告区分实际安装次数与快照复用次数。旧 v0.5 安装配置保留共用写规则行为。见 分阶段说明 与 示例。
# 下载固定提交并放入锁文件、任务脚本，不在宿主安装依赖
npm run medium:prepare
# 沙箱内冷安装验证、固定暖缓存搜索、导出重放
npm run medium:verify这个例子使用 fast-glob 3.3.3，锁定 507 个依赖项，编译上游 TypeScript、运行全部 246 项单元测试，并验证构建 API。适配脚本明确跳过依赖声明文件的兼容检查，仍检查项目源码；上游 .npmrc 被排除，使用随例子提交的锁文件。
report.md 新增耗时表，report.json 与每轮证据记录复制、完整性哈希、变化清单、安装、任务、边界探针等分项。复用安装状态的任务保留完整性核对和任务前后清单，省去不存在的安装阶段清单；默认逐轮清理副本，最终仍重新安装。见 实测方法与配置成本。
改代码或改依赖后的检查详见 回归检查。旧规则通过时只做配置要求的重复验证；权限变化、普通任务失败和未知结果分别记录。经过复验的补充建议保存为 suggested.yaml，便于审阅和重放。
# 安装演示的固定依赖，再验证代码、真实依赖和普通错误的变化
npm run regression:prepare
npm run regression:verifynpm test
npm run test:integration
npm run check单元测试检查配置、路径、快照、断言、搜索、进程管理和探针对照。集成测试在真实 macOS 沙箱中验证权限收紧、必要权限撤销、导出配置重放、旧产物、越界访问、超时和中断；其他系统上明确跳过集成测试，不用 mock 替代隔离验证。
- CI 覆盖与场景验收：默认完整回归、两组 macOS 集成、原场景迁移与成本口径。
- 诊断预算：原上限内保留 worker 线索、明确遗漏和最终状态来源。
- 工具链事件压力：XO 单文件对照、当前容量限制及包计数的解释范围。
- 观察可靠性与定向 lint 实测：重复日志压缩、worker 缺口解释和实际成本。
- 整体重构计划：共同实验底座、两条独立使用路径、多轮交付与迁移验收。
- 第一轮内部模型：五对象、身份与缺失含义、旧数据适配及结论判断表。
- 共同执行底座：第二轮接口、流程与报告分工、原生执行事实、保存和安装复用时序。
- 两条模型使用案例：真实权限回归与依赖观察记录的离线回放。
- 早期环境检验：本机结果、换环境复现步骤及未验证范围。
- 耗时与中等规模实测：计时口径、可复现对比与配置限制。
- 完整校验与一致性：有界扫描、历史摘要兼容、暖安装观察及同预算对照。
- 配置参考：全部字段、成功断言与 limits。
- 架构与搜索流程：模块、候选修改、结果状态和证据。
- 搜索效率：成组撤销、延后复查和同项目次数对比。
- 快照工作区：写时复制、跨轮隔离、回退与本机对照。
- 分阶段权限：独立安装写规则、安装快照复用、任务读取与完整重放。
- 安装与网络权限：安装阶段、冷暖缓存、域名上限和断网验证。
- 规则回归检查：代码与依赖变化后的验证、对照和建议采用。
- 安全边界：固定权限、支持的工作负载和已知限制。
- 开发与测试：修改代码、测试分层和 CI。
- 实测记录：本机实际运行结果与验收映射。
- 后续路线：MVP 之后的验证方向。
源码以 MIT License 发布。底层 Sandbox Runtime 的许可证见其独立包；本项目通过 npm 依赖引用它。