人工智能AI 应用AI AgentAgent 沙箱AI 安全治理【免费下载链接】cloudflare-osAgent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems.项目地址https://gitcode.com/gh_mirrors/cl/cloudflare-os点击查看免费下载本文是 cloudflare-os一个基于 Cloudflare Workers 构建的 Agent workspace用于创建文档、构建应用并以公司上下文运行 Agent仓库内面向 AI 评审者的 Pull Request 评审指南。它规定了评审的优先级排序、内核代码的高关注区、基于能力capability的安全不变量、日志与错误上报中的密钥防护、Capn Web RPC 的语义陷阱以及 Vite 构建系统中静默失败的各类配置红线。读完本文你将获得一份可直接对照 diff 逐条执行的评审清单理解每一项规则背后的源码依据并能准确区分必须标记与不要标记的边界。评审总纲优先级决定一切REVIEW.md 开篇即给出了评审优先级的硬性排序从高到低内核标准kernel bar——workshop-backend与workshop-shared的公共 API 是维护者逐行阅读的代码要求最高能力安全不变量capability-security invariants——能力铸造minting路径上的任何绕过都是高危日志与错误中的密钥泄漏secret leakage through logs and errors——这是唯一被单独列为第三优先级的安全类别其余一切everything else。这个排序决定了评审者分配注意力的方式一个 UI 层的样式问题远没有一处as unknown as的类型绕过重要。此外REVIEW.md 开篇还明确了仓库内文档的分工构建、测试与开发流程见 AGENTS.md哪些变更可以被接受见 CONTRIBUTING.md而 REVIEW.md 只负责如何评审。内核高关注区workshop-backend 与 workshop-shared 公共 APIpackages/workshop-backend/与packages/workshop-shared/src/api.ts被明确定义为仓库的kernel。维护者会阅读其中的每一行代码因此评审者必须对其施加比 UI 或 gatekeeper 代码更高的标准。REVIEW.md 列出了四条具体规则每条导出成员都要有文档注释workshop-shared公共 API 的每一个导出成员都需要 doc comment——包括类型types、常量consts和函数functions而不仅限于接口interfaces。AGENTS.md 同样强调了这一点doc-commenteveryexported member。理由很直接kernel 的公共 API 是前端与后端之间的 RPC 契约由 packages/workshop-shared/src/api.ts 定义缺少注释的导出成员等于向所有调用方包括未来接入的 gatekeeper欠下了可读性债务。拒绝手写接口 as unknown as 强制转换REVIEW.md 明确要求拒绝一个镜像 RPC 接口的手写 interface 再加上as unknown as强制转换的做法。正确的做法是从真实类型派生derive from the real type或者重新思考设计。这一规则在源码中有直接体现packages/workshop-backend/src/user.ts中通过PickRequired从源接口派生AccountCreatorStub、SingletonAccountStub等类型时注释明确写道These are derived from the source interfaces (Pick Required) rather than re-declared, so they cant drift——派生类型不会漂移而手写镜像必然会漂移。优先复用现有机制而非另起炉灶当评审者发现一个新增的平行机制parallel mechanism时应当指出该变更本应复用的既有机制是哪一个。这与仓库减少内核代码行数 更易评审的整体取向一致见 AGENTS.md 对 kernel 的描述。大改动按关注点拆分一个较大的 kernel 改动应按关注点拆分成独立的 PR至少也要按提交commit分组使得workshop-backend/workshop-shared可以脱离 UI 单独评审。评审者应标记那些把 kernel 与 UI 打包在同一个 PR 中的情况。基于能力的安全不变量能力安全capability-based security是本仓库安全模型的核心。REVIEW.md 列出的是必须逐条核对的不变量任何违反都构成否决block理由。环境ambience只能来自配置不能自我断言一个资源要变成ambient自动注入只能通过用户或管理员配置。gatekeeper 绝不能自行断言自己的 ambience。这意味着评审时要检查是否有 gatekeeper 代码在未经配置的情况下把自己声明为 ambientAGENTS.md 中大量关于 auto-provisioning gatekeeper 的描述如VendorDescription.autoProvisionsAccount都围绕由部署管理员在 admin 面板选择 disabled / optional / enabled 模式展开正是不变量ambience 源于配置的体现。getGatekeeperClassFor()唯一的核心关卡packages/workshop-backend/src/user.ts中的getGatekeeperClassFor()注意不是各个 gatekeeper 实现的同名 vendor 方法是唯一的核心关卡single chokepoint在能力被铸造之前被禁用的 gatekeeper 与被禁用的资源在这里统一被强制执行。源码实现packages/workshop-backend/src/user.ts#L1923-L1948清晰展示了这一逻辑先通过connectedAccounts.get(accountId)找到账号调用 gatekeeper 侧的account.account.getGatekeeperClassFor(url)解析出资源再读取readAdminConfig(this.env)检查config.disabledGatekeepers.includes(vendorId)命中即抛错该 gatekeeper 已被管理员禁用随后用isResourceDisabled(config, vendorId, resource.urlPattern)检查资源级禁用注释明确写道Blocking here prevents minting a new capability to a disabled resource even if the request bypasses the (separately filtered) picker/agent listings.同时该关卡只经由面向用户/UI 的Overseer.newGatekeeper与蓝图实例化到达——gadget 或 agent 代码永远无法直接触达。因此评审规则是标记任何不经过getGatekeeperClassFor()就铸造 gatekeeper 能力的新路径。认证/授权配置必须留在环境变量里认证与授权配置AUTH_GATEKEEPERS、DISABLE_PASSWORD_AUTH在packages/workshop-backend/src/auth/config.ts中被刻意设计为环境变量驱动并且不得移入AdminConfig。原因在源码注释与 AGENTS.md 中都有说明一旦被移入AdminConfig一个被攻破的管理员会话admin session就能修改它从而瓦解认证边界。实际解析逻辑见 packages/workshop-backend/src/auth/config.tsAUTH_GATEKEEPERS是一个逗号分隔的 vendor id 白名单lowercasedDISABLE_PASSWORD_AUTH true时关闭密码登录但仅在至少一个 OAuth 提供方存在时才生效。评审者应拒绝任何将这两项配置搬迁到AdminConfig的变更。AdminConfig 的唯一写者是 AdminSettingsAdminSettings是权威AdminConfig的唯一写者其他代码只能通过readAdminConfig(env)读取。源码验证packages/workshop-backend/src/admin-settings.ts#L297 定义updateAdminConfig(patch: PartialAdminConfig)所有站点名称、横幅、公告、主题色等配置的更新都收敛到这个方法packages/workshop-backend/src/admin-config.ts#L347 定义readAdminConfig(env)被server.ts、overseer.ts、login-flow.ts、deployment-config.ts等大量热路径代码调用——每次调用只是一次廉价的 KV 读取。AGENTS.md 补充了其存储细节AdminSettingsDurable Object 将权威配置镜像到单一保留 KV 键.adminConfig见isReservedBlueprintKey()。评审时应拒绝任何绕过AdminSettings直接写AdminConfig的路径。mcp-shared/tools.ts信任边界在packages/mcp-shared/中tools.ts是信任边界trust boundaryREVIEW.md 给出了三条子规则边界之外无人能读取工具的 annotations——工具注解annotations的消费被严格限制在tools.ts内部工具只有在服务器声明readOnlyHint: true时才作为 observation 运行——其余一切写操作进入待批准队列自动应用auto-apply一个写操作额外要求vetted端点——ServerTrust类型在 packages/mcp-shared/src/tools.ts 中定义为vetted | byo源码注释显示vetted表示管理员断言该端点的注解可靠只有 portal 能产生经由MCP_PORTAL_TRUST_ANNOTATIONSbyo表示用户粘贴的 URL。对byo端点尊重readOnlyHint是对注解完全不可信原则的明知偏离因此在写操作上额外要求vetted是对该偏离的补偿。另外每个 SDK OAuth 操作都必须传入sdkFetch(...)这样端点和 SSRF 检查才能在重定向redirects之后仍然存活——即重定向不能绕过 SSRF 防护。blueprintId 部署后不可编辑packages/bundled-blueprints/blueprints/下的blueprintId在部署后绝不被编辑——安装installs和提升promotion都以它作为键重命名会导致旧条目成为孤儿。评审时要标记任何可能在部署后改变blueprintId的变更。日志、错误与密钥防护这是唯一被 REVIEW.md 单列为独立优先级的非内核主题足见其重要性。结构化日志规范服务端代码通过gadgets/backend-utils/logger记录日志要求使用模块级module-scopedlogger带稳定的点分隔componentgatekeeper 额外带vendorId捕获的值以error字段传入。实际实现见 packages/backend-utils/src/logger.tscreateLoggerExtraFields(defaults)创建一个带固定 component 元数据的 ALS-free 结构化 Worker logger。AGENTS.md 给出的使用范式是const logger createLoggerGitHubLogFields({ component: gatekeeper.github, vendorId: VENDOR_ID }); // ... logger.warn(failed to notify credential expiry, { event: credentials.expiry.notify.failed, error: err });密钥永不入日志绝不记录或上报 secrets、prompts、headers、tokens 或请求/响应体。由于异常消息和堆栈会到达外部的 Reporter因此任何被抛出thrown或作为上报元数据report metadata附加的内容都适用同样的规则。这条规则的严苛程度在 AGENTS.md 的错误上报章节中进一步明确上报上下文report context遵守与日志字段相同的 no-secrets 规则且只有有界标量bounded scalars会被保留为 attributes。Gatekeeper UI 的错误上报路径Gatekeeper 管理/配置 UI不得直接从自己的 Worker 源origin上报错误。它们以 Workshop 拥有的 opaque-originsrcDoc框架运行通过postMessage将受限报告发送给 Workshop hosthost 只接受来自已知框架窗口origin 为null的消息附加 host 拥有的 surface/vendor 上下文后再进行同源 POST。前端报告永远不携带权威authority。评审时应拒绝任何从 gatekeeper Worker 域名发起的直接跨源上报。reportedUserId 与 pageLocation报告的reportedUserId是客户端提供的、未经验证的字段——它只是一个诊断标签永远不能被当作身份或权威来读取。评审时应拒绝任何把它当作 identity/authority 的变更。pageLocation只保留 origin 和 pathname且是在边界处重建rebuild而非裁剪trimmed因为分享链接的 fragment 是 bearer capability而href会保留凭据credentials。非http(s)URL 被整体丢弃见 AGENTS.md 对normalizePageLocation的描述。自动捕获只属于可信一方自动错误捕获automatic error capture只能安装在可信的 first-party 表面绝不能在 gadget 或用户编写的代码中安装。Capn Web RPC三条必须知道的语义陷阱REVIEW.md 针对仓库广泛使用的 Capn Web RPC 给出了三条不要误报或必须标记的规则。这些规则与 AGENTS.md 末尾的三条 IMPORTANT 完全呼应。Promise 流水线是刻意的不要误报 floating promisesCapn Web 实现了 promise pipelining与 Capn Proto 类似一个 RPC promise 可以不 await就直接作为参数传递或直接当作 stub 使用。因此不要把未 await 的 RPC promise 报告为 floating promises。这直接决定了不要标记清单的第一条。任何把 promise pipelining 当作异步错误的 lint/评审结论都是误报。useState 持有 RpcStub 必须包对象运行时中所有 stub 看起来都是可调用的系统无法判断 stub 指向的是不是服务端函数。useState的 setter 在收到函数包括任何可调用对象时会调用它来获取新状态。因此当useState的状态将要持有RpcStub时必须把 stub包装进一个对象再设为状态。评审时要标记直接以 stub 作为 state 值的代码。Stub 必须被释放Stub 必须被释放否则会造成服务端资源泄漏stub[Symbol.dispose]()、using声明或useEffect清理函数中释放组件获得的 stub。获得了 stub 但从不释放是值得标记的服务端泄漏。AGENTS.md 特别强调当 React 组件在useEffect中获得 stub 时cleanup 函数应当释放该 stub。构建系统Vite tasks最容易静默失败的地方REVIEW.md 对构建系统的评语是这些失败是静默的break silently而非响亮地崩溃因此即使 diff 看起来没问题也值得标记。 该仓库的构建/测试/清理均通过 Vitevp见 scripts/vp/run.ts以 task 形式运行而不是传统的 package.json 脚本。缓存的 vp task 只见内置环境一个被缓存的vptask 只能看到内置环境PATH、HOME、CI、NODE_OPTIONS等。因此读取环境变量的构建必须是声明了env的 task——因为 package.json 脚本上不存在env/untrackedEnv字段一个复制了 task 命令的兄弟脚本sibling script不会从该 task 的env声明中获得任何好处——它走的是被剥离环境的路径。AGENTS.md 给出了正确范例workshop-frontend的build声明env: [VITE_*]既转发标志又把它们折入指纹fingerprint值一变就是一次可报告的缓存未命中而不是重放陈旧 bundle。评审时要标记task 声明了env但实际调用方是脚本的情况。env 指纹的是值不是它指向的东西env对变量的值做指纹而不是对变量指向的路径内容做指纹。因此workshop-backend的build用cache: false而不是env: [BUNDLED_BLUEPRINTS_DIR]该变量命名的是工作区之外的蓝图目录若路径保持不变目录内的编辑对指纹不可见陈旧的bundled-blueprints.ts会被重放。任何命名工作区外路径的变量都应使用cache: falseAGENTS.md 称之为the same caution for any var naming a path outside the workspace。读写的 task 永不缓存一个 task 若读取自己也会写入的路径就永远不会命中缓存。因此新 task 必须从input中排除自己的输出以及vitest/wrangler 的 scratch 路径node_modules/.vite、node_modules/.vite-temp、.wrangler覆盖细节见 scripts/vitest-task-vite-config.tsgatekeeper SPA 构建build:app的排除规则必须是工作区级的否则各个 gatekeeper 会互相使对方失效AGENTS.md 解释只有目录内容可以被排除且排除必须 workspace-wide。三条明确的不得红线REVIEW.md 用祈使句明确禁止了三类回归不要给 tsconfig 加incremental——tsc会读写自己的.tsbuildinfo把整个类型检查从 task 缓存中移除而收益小于成本AGENTS.md 的实测无incremental时 65% 命中率、13.4s有它时 2% 命中率、21.1s不要重新引入调用pnpm run --recursive的根脚本——根脚本本身就是vp run调用-r会选中根包导致自递归竞态见 AGENTS.md 对--filter!cloudflare-os替代-r的解释不要从包的setupFiles中移除 scripts/assert-workerd.ts 来让测试变绿——它在navigator.userAgent不是Cloudflare-Workers时抛错防止 workerd 测试池启动失败时静默回落到 Node 而假装通过。pnpm test 的 --filter 写法是平台敏感的pnpm test的--filter!cloudflare-os硬编码了根包名重命名根包会让脚本套件静默翻倍。它必须带且不加引号书写cmd.exe会保留单引号字面量加引号的 filter 在 Windows 上匹配不到任何东西脚本以运行了零个测试的状态退出 0。评审时要检查该命令的写法是否保持了--filter!cloudflare-os的原始形态。发布清单的 golden 测试在有意的发布清单release manifest变更之后golden 文件必须重新生成并评审其 diffUPDATE_GOLDEN1 node --test scripts/release/manifest-lib.test.ts源码验证scripts/release/manifest-lib.test.ts的注释与断言均指向testdata/golden-manifest.jsonGOLDEN_PATH测试从真实配置生成的清单与 golden 文件匹配未生成时提示用UPDATE_GOLDEN1重新生成。golden 文件是本仓库 CI 与部署服务之间的契约因此任何 diff 都必须被人工评审。新 gatekeeper 的默认凭据输入一个不接收第三方 OAuth 凭据的新可安装 gatekeeper 应列入NO_DEFAULT_CRED_INPUTS定义于 scripts/release/manifest-lib.ts#L260。原因在 AGENTS.md 中说得非常具体部署向导会在未填写的 secret 输入上阻止 Install因此一个多余的默认 secret 输入会让该 gatekeeper 在部署向导中无法安装。评审时要检查新增 gatekeeper 的默认输入是否与实际所需凭据一致。外部贡献的评审标准来自团队外部的贡献被限制为小改动明显正确、仅靠阅读补丁即可平凡验证trivially verifiable。评审这类 PR 时应以此标准衡量不要要求外部贡献者扩大范围broaden scope不要要求他们顺带做重构或相邻的清理adjacent cleanup。这背后是外部贡献者的信任模型他们无法接触到内部评审上下文因此要求的是一眼可验证的正确性而不是架构级重构。不要标记Do not flag清单REVIEW.md 专门列出了一份明知有问题但不得标记的清单避免评审者被误判消耗。每一项都有明确的技术理由不要标记的事项技术理由未 await 的 RPC promiseCapn Web promise pipelining 是刻意设计见上文 RPC 一节fork PR 上跳过的 preview deploymentGitHub 设计上就不向 fork 的运行提供 secretstest:run作为脚本名Vite task 不得与 package.json 脚本同名这正是pnpm --filter pkg build/test在此仓库不可用的原因oxlint 警告如no-shadow保留给增量清理不阻塞 CI同样不要标记缺少 type-aware lint 规则tsconfig 中的singleThreaded: true实测为最快且最小的配置AGENTS.md 给出实测tsgo 并行 7.3s/1.9GB vs 单线程 2.0s/0.7GB类型量 6.9 倍、实例化 4.2 倍任何 tsconfig 缺少baseUrlTypeScript 7 已移除该选项TS5102paths条目都是相对显式路径其中最后两项还揭示了仓库的两个技术底座tsgoTypeScript 7作为全工作区tsc以及 oxlint 由 Vite 固定版本1.76.0驱动、无独立.oxlintrc.json。评审时忽略Ignore during review的项最后REVIEW.md 明确了哪些文件在评审时直接忽略生成文件gitignored会自动重建packages/*/src/generated/**含app.txt、*-configurator-ui.*、bundled-blueprints.ts、browser-export-runtime.txt以及任何dist/pnpm-lock.yaml——除非变更本身就是依赖变更此时要对照 pnpm-workspace.yaml 中的minimumReleaseAge供应链策略实际配置值为minimumReleaseAge: 1440即 1440 分钟检查blueprint 目录中已提交的*.gadget归档——它们是不透明数据opaque data无法也不应逐字节评审。结语把 REVIEW.md 用起来的评审工作流REVIEW.md 是一份为机器评审员AI reviewer优化的操作手册它与 AGENTS.md如何构建、测试与开发、CONTRIBUTING.md什么变更可被接受形成互补。一次合格的评审可以按以下流程执行先定位变更触及的范围是否落在packages/workshop-backend/或packages/workshop-shared/src/api.ts是则启用 kernel 高关注区标准doc comment、类型派生、机制复用、PR 拆分再按优先级扫描能力铸造路径是否绕过getGatekeeperClassFor()packages/workshop-backend/src/user.ts#L1923-L1948认证配置是否被移出环境变量tools.ts边界外的注解读取是否出现日志/异常/上报元数据中是否出现 secrets、prompts、headers、tokens 或 body然后处理 RPC 与构建语义是否误报 promise pipeliningstub 是否释放task 的env/cache/input声明是否符合缓存规则参考 scripts/vitest-task-vite-config.ts 与 scripts/vp/run.tsgolden 文件是否需要重新生成UPDATE_GOLDEN1 node --test scripts/release/manifest-lib.test.ts最后对照不要标记与忽略清单收尾确保没有把刻意设计当成缺陷。按此流程评审者既能守住内核安全与密钥防护这两条最重要的底线又不会在刻意为之的 promise pipelining、singleThreaded或baseUrl缺失上浪费评审资源。赞分享人工智能AI 应用AI AgentAgent 沙箱AI 安全治理【免费下载链接】cloudflare-osAgent workspace built on Cloudflare Workers for creating documents, building apps, and running agents with your company’s context and systems.项目地址https://gitcode.com/gh_mirrors/cl/cloudflare-os点击查看免费下载相关推荐GPT-Image-2 广告创意提示词实战从 JSON 结构化模板到分阶段创意工作流GPT Image 2 广告创意提示词实战从 JSON 结构化模板到分阶段创意工作流 本文以 awesome gpt image 2 API and Prom人工智能提示工程媒体生成PyMC 示例库pymc-examplesPR 评审指南评审流程、检查清单与实战要点PyMC 示例库pymc examplesPR 评审指南评审流程、检查清单与实战要点 本篇指南面向 pymc examples 仓库中 Pull Requ人工智能机器学习科学计算uncss代码评审指南贡献者提交PR的检查清单uncss代码评审指南贡献者提交PR的检查清单 一、功能完整性检查 1.1 核心功能验证 选择器检测 确保 src/uncss.js https://lin前端开发工具上一篇如何在iPhone上免费运行本地大语言模型完整隐私保护指南下一篇knowledge-work-plugins 之 Zoom Video SDK for Windows 官方示例应用完全指南20 个 Sample 选型、代码模式与构建实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
