写给 AI 编码代理的「十条工程铁律」Coucou 的 CLAUDE.md 里藏着人机协作的潜规则【免费下载链接】coucouA tiny friend in your Macs notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.项目地址: https://gitcode.com/gh_mirrors/co/coucou2026 年第三季度Coucou 以刘海守护者的姿态连续多日冲上 GitHub 趋势榜——一只叫 Mochi 的小方块住在 MacBook 的刘海以及 Windows/Linux 的屏幕顶端里实时盯梢 Claude Code、Codex、Cursor、Gemini CLI 等 AI 编码代理的每一次文件读写、命令执行与权限请求甚至能在你锁屏后搬到 iPhone 的动态岛上。社区教程从5 分钟上手写到0% CPU 的隐藏性能细节热度背后真正值得深挖的却是仓库根目录那份不足三十行的小文档——CLAUDE.md。它名义上是写给 AI 编码代理的项目指南实质是一部浓缩的人机协作事故史每一条铁律都能在源码里找到对应的强制实现而每一段强制实现又都对应着一类真实的工程事故。这篇文章把十条铁律逐条拆开追到 HookServer.swift、ClaudeSettingsFile.swift、pipe.rs 与 main.rs 里去看看这份潜规则到底在守护什么。一、先说清楚这份文档是写给谁看的Coucou 是双端项目NotchBuddy/是原生 Swift 6 / SwiftUI 的 macOS 应用windows/是 Tauri 2Rust TypeScript的 Windows/Linux 版本。这样一个横跨三种操作系统、十多种 agent 接入的项目靠人肉维护上下文显然不现实——它的真实同事正是 Claude Code 本身README 的 Credits 里坦率写着 Built by Louis Raillé with Claude Code。于是 CLAUDE.md 扮演了入职手册它不教语法而是把不许做的事列成规则。与它同源的还有 CONTRIBUTING.md 里的 Rules of the house面向人类贡献者的简化版两条文档共享同一套价值观只是受众不同。这种双文档同规则的做法本身就是一种工程纪律人类和 AI 代理在同一套约束下工作规则才不会被绕过。把 CLAUDE.md 的 Rules 数一遍正好十条Swift 6 SwiftUI/AppKit零第三方依赖角色纯代码绘制密钥只在 Keychain绝不落盘或进 git零遥测网络调用只面向用户配置的服务永不阻塞 Claude Code应用不响应hook 立即退出永不覆盖~/.claude/settings.json备份、合并、展示 diff、用户确认后才写无显式点击绝不发邮件或批准权限性能铁律岛隐藏时 0% CPU保持 bundle IDfr.louisraille.NotchBuddy不变永不重排已上架的 UIpill、卡片、设置、聊天…pill ID 是稳定契约永不重命名。下面逐条对号入座——每一条都能在源码里找到它的执法者。二、逐条拆解每条铁律背后都是一类真实事故铁律 1零依赖与纯代码绘制堵住供应链与体积两个口子Character is drawn in code (CanvasTimelineView), no Rive/Lottie/images——这条在 macOS 端由 BotCanvasView.swift 执行Mochi 的圆角方块身体、投影在球面上的眼睛、弹跳动画全部是 SwiftUI 绘制出来的不携带任何图片资源Windows 端则由 engine.ts 用 Canvas 2D 复刻同一套形状与时间轴。这条规则防的是两类事故其一是第三方依赖的供应链风险——一个插在 GUI 框架和渲染引擎之间的第三方库本身就是遥测、密钥窃取和崩溃的潜在来源其二是二进制资源的不可审查性——代码可以 reviewPNG 里的像素不能。零依赖换来的是整个仓库可以被人逐行读完的可审计性这在隐私敏感工具上是近乎宗教级的坚持。铁律 2密钥只在 Keychain——防止开源即裸奔Secrets live in the Keychain, never on disk or in git.在 Windows 是 Credential Manager在 Linux 是 Secret ServiceGNOME Keyring / KWallet。以 StripePoller.swift 为例Stripe API key 通过KeychainStore.shared.get(stripe-api-key)取用poll()里第一行就是guard let key ... else { return }——没有密钥就直接放弃轮询而不是降级成明文缓存。开源项目的密钥管理是事故高发区一旦 key 落盘等于把生产凭据写进每一个 clone 者的硬盘。把密钥强制放进系统级保管箱是从机制上让忘记删除密钥这种事变得不可能。铁律 3零遥测——隐私事故的预防性立法Network calls only to services the user configured.这句话在代码层面同样可验证全仓库的网络出口只有三类——用户主动配置的服务 APIGitHub、Notion、Stripe、Vercel、Resend、Cal.com 的 poller、用户自己填的聊天模型 API以及 iPhone 同步时走用户自己的私有 CloudKit 数据库。没有任何埋点上报 SDK没有任何统计一下有多少人用了的匿名收集。社区评论反复强调的全程无遥测、不上传数据正是这条铁律的对外承诺。铁律 4永不阻塞代理——监控工具的生死线这是十条里最重的一条也是整个架构设计的原点。Coucou 的本质是盯梢盯梢者绝不能反客为主拖垮被盯梢者。C 端和 Rust 端各有一套独立的止损机制macOS 端HookServer.swift 为每个客户端 socket 设置 5 秒的SO_RCVTIMEO把单次 payload 上限卡在 1 MBmaxPayload 1_048_576并发连接封顶 32解析失败时立即回写{ok:true}并关闭连接——Claude Code 永远能得到一个正常的应答而不是被挂起。Windows/Linux 端pipe.rs 的注释直接写明了三级保障coucou-hook300 ms 连不上管道就干净退出只有岛确认审批卡片已上屏ACK 800 ms之后才进入等人的长等待无论发生什么决策超时一到就断开连接把决定权交还终端。main.rs 把这一思想执行得更彻底每个 hook 事件都有一条硬预算——连接 300 ms、无人在等的 fire-and-forget 事件 2 秒、权限请求 110 秒。worker 线程超预算就直接process::exit(0)进程死亡会带走管道句柄代理毫发无损。这套预算-超时-让位机制回答了一个所有 agent 监控工具都会遇到的根本问题当监控器宕机时被监控的 AI 是停下等待还是继续干活Coucou 的答案是永远继续。铁律 5settings.json 的备份-合并-diff-确认四段式——配置文件事故的标准疗法Never overwrite~/.claude/settings.json是贡献者最容易踩的坑也是事故率最高的场景一个安装钩子的工具随手把用户精心配置的 settings 文件覆盖成自己的格式等于毁掉用户的整个 agent 工作流。Coucou 用 ClaudeSettingsFile.swift 把它做成了不可跳过的流水线读取即取证read(at:)返回(object, bytes)二元组把解析结果和原始字节一起保留——文件不存在与文件存在但读不了被严格区分读不了就抛错并明示nothing was written写入前校验write(_:to:expecting:)首先比对磁盘上的当前字节与当初展示给用户的字节不一致就抛.changed——防止安装期间用户或另一个工具改动了文件导致用旧快照覆盖新内容原子写先写到同目录的临时文件settings.json.coucou-pidrename()覆盖目标崩溃或磁盘写满只会留下原文件完好带日期备份freeBackupURL(for:)生成settings.json.bak-20261011-0107式命名同一秒内重装也不覆盖上一份备份权限继承与 symlink 尊重备份保留原文件权限位且通过resolvingSymlinksInPath()跟随 dotfiles 常见的符号链接。CHANGELOG 0.2.2 还专门补了一条加固记录~/.claude/settings.jsonis never rewritten from scratch when it cant be read, the backup must succeed before anything is written, and nothing is written if the file changed since the preview——这条规则经历了真实事故无法读取的文件被从零重建后打上了补丁。这正是铁律 5 活的版本历史。铁律 6无点击不执行——把人审做成物理定律Never send an email or approve a Claude Code or Codex permission without an explicit click.权限审批的完整性设计贯穿三层socket 即授权凭证macOS 端收到PermissionRequest后不急于应答而是把连接 fd 一直握在手里pendingApprovalFD只有用户在岛上点击 Allow/Deny/Always 后sendApprovalDecision(_:)才把{permissionDecision:allow}写回 fd——fd 是这场审批还活着的唯一凭证两条退路都不放权无论是超时115 秒Copilot/Muse 因自家 relay 预算更紧而压缩到 110 秒还是卡片被折叠回写的都是ask——把决定权交还给终端里的代理而不是自作主张批准Windows 端的两段式等待pipe.rs 里wait_for_decision先等岛确认卡片上屏Reply::Ack再进入 108 秒的决策等待没有 ack 就返回None管道不写任何字节代理按Coucou 没装的原样在终端重新提问。邮件同理IslandViewContent.swift 里拖拽文件发邮件的路径在 App Store 版必须经过NSSharingService(.composeEmail)让用户亲眼确认GitHub 版用 AppleScript 操作 Mail.app 也是在用户点下发送按钮之后——没有任何静默发送的代码路径。铁律 70% CPU——把隐形即休眠做进状态机0 % CPU when the island is hidden不是营销话术而是一整套可验证的实现。岛隐藏时动画心跳整体暂停TimelineView 驱动只在岛可见时运行指针探测从 60 次/秒降到 8 次/秒CHANGELOG 0.2.2 明确记录the island checks the pointer 8 times a second instead of 60 while it is hidden服务轮询全部可暂停——StripePoller.swift 的poll()第一行就是guard !DemoEngine.isPollerPaused每个 poller 都遵循没人看就不跑的原则音效在启动时预加载成AVAudioPlayer池SoundEngine.swift每音效 3 个实例、默认音量 0.12播放时零 IO。这条铁律防的事故是常驻工具变成电老虎一个自称守护者的应用如果吃 10% CPU用户的第一反应就是卸载。把空闲成本压到零是监控类工具获得长期居住权的入场券。铁律 8bundle ID 是系统身份的锚点Keep the bundle identifierfr.louisraille.NotchBuddy(Keychain items, preferences and permissions depend on it).project.yml 里PRODUCT_BUNDLE_IDENTIFIER: fr.louisraille.NotchBuddy与bundleIdPrefix: fr.louisraille被显式声明且所有涉及系统凭据的路径都以它命名空间——nb.sock、Keychain 条目、UserDefaults 域、沙盒容器App Store 版是fr.louisraille.Coucou。改 bundle ID 的代价是用户钥匙串里的所有密钥全部失联macOS 的 TCC 权限辅助功能、自动化全部重置等于对存量用户执行一次强制重装。铁律 9永不重排已上架的 UI——把 App Store 构建钉成基线existing views stay exactly as they are inmain, which is the App Store build.这条规则承认了一个残酷事实视觉回归是最难测试、最容易在 AI 重构中悄悄发生的损坏。AI 代理顺手优化一个按钮位置或配色在开发分支看起来人畜无害发布后却是用户反馈海啸。把main定义为 App Store 基线等于宣布没有明确需求任何视觉变更都是 bug——这是给擅长自由发挥的 AI 代理上的最紧的缰绳。铁律 10pill ID 是跨系统契约Pill IDs are stable contract values (Keychain, UserDefaults, hook routing): never rename an existing pill ID.PillCatalog.swift 被注释为 single source of truth for all declared pillsintegration_claude、agent_cursor、agent_codex、integration_stripe这些 ID 既是 UI 标识也是 hook 路由键、RecapStore 的统计键、iPhone 同步的记录键。重命名一个 ID会让 Keychain 里的偏好失联、历史 recap 断档、iPhone 上的会话对不上号——docs/AGENTS.md 里第三方 agent 接入的coucou_agent字段校验规则^[a-z0-9-]{1,24}$且claude被保留拒绝以防冒名同样建立在ID 一经发布就是契约之上。三、从 Unix Socket 到构建流程铁律背后的工程观十条铁律看起来零散背后其实是一以贯之的工程观凡是能由机制强制的事就不依赖人的自觉。三个例子足以说明。通道设计进程间通信先谈安全再谈效率。macOS 端在 HookServer.swift 里用 Unix 域套接字接收事件但绝不是建个 socket 就完事目录权限0700、socket 文件chmod 0600、每次accept后用getpeereid校验对端 UID 必须等于本进程 UID——其他人写进来的事件直接拒绝。Windows 端对应的是命名管道\\.\pipe\coucou-user-SIDpipe.rs用 SID 天然隔离用户Linux 端 socket 落在$XDG_RUNTIME_DIR同样以 0600 权限 peer credential 校验收口。跨平台一致的安全基线比任何传输层加密都更本质。审批链路把人在回路的时间预算精确到毫秒。审批是最需要人等的环节也是延迟最容易失控的环节。Coucou 把它拆成两段先让岛用 800 ms 确认卡片真的上屏了确认失败立即让位给终端确认成功后才允许人用最长 108 秒慢慢决定。这样的设计让岛挂了的代价从两分钟骤降到几百毫秒——监控者的故障成本被显式地限制在可接受范围内这正是铁律 4 的工程化落地。数据管线给 AI 代理的噪音设闸。main.rs 对转发的每个字段设置了上限DROPPED_FIELDS直接丢弃tool_response、tool_output、transcript_path这类可能巨大的字段普通字符串截到 2,000 字符只有 live diff 需要的编辑文本Edit/MultiEdit/Write 的old_string/new_string/content放宽到 256 KB 但全事件总量封顶 512 KB保证转发行不超过管道 1 MiB 读取上限。代理每步都可能吐出几十 KB 的输出不让这些噪音撑爆监控通道监控才能做到0% CPU。构建流程同样是契约。project.yml 是 XcodeGen 的声明式工程文件注释明文写着never edit the.xcodeprojby hand——.xcodeproj这种不可 diff 的二进制产物被降级为生成物工程配置的一切变更都能走 review。同一个 yml 里APPSTORE与PHONE_LINK编译条件区分了沙盒构建与 GitHub 构建、ReleaseCloud的 CloudKit 签名把App Store 版少哪些功能也从代码里显式声明出来而不是靠两个工程副本悄悄漂移。四、对自建 AI 工作流的启示把事故翻译成规则把规则翻译成代码Coucou 的 CLAUDE.md 之所以值得当范本不在于规则本身多么新颖而在于它的可验证性十条规则里绝大多数都有对应的代码强制、测试脚本scripts/下 20 多个test-*.sh从屏幕几何到 diff 引擎全覆盖或 CHANGELOG 事故记录。这给所有打算让 AI 代理长期维护自己仓库的团队提供了四条可复制的经验写给代理的文档必须能被机器执行。不要说请保持代码整洁要说依赖必须经过 review、密钥只能走 Keychain、文件先备份再改写。规则越接近代码越难被忽略。把故障预算写进协议。监控、hook、插件这类伴生组件必须回答一个问题我宕机时主流程怎么办Coucou 的答案是立即退出、把决定权交还终端。任何接入 AI 工作流的中间件都应该有同样的 fail-open 设计——代理可以等但绝不允许因为辅助工具故障而停摆。权限审批要证据链化。一次批准 一次显式点击 一个对应的 socket 连接 一个匹配的会话 ID。没有这条证据链所谓人在回路就是空话。自建审批流时务必让人审成为不可绕过的物理环节而不是 UI 上的一个可选按钮。稳定的 ID 与稳定的基线是 AI 重构时代最后的护栏。当代理可以在一夜之间重命名几百个符号、重排几十个视图时像 bundle ID、pill ID、main分支视觉基线这种动了就要赔钱的锚点是唯一能对抗自动化式破坏的机制。说到底这份十条工程铁律真正的潜规则只有一条AI 代理可以获得最大限度的自主权但绝不能获得对用户系统、用户配置、用户审批的默示控制权。所有的规则、预算、校验、备份都在捍卫同一个边界——工具可以聪明但决定永远属于人。这也是 Coucou 在 GitHub 趋势榜上被反复讨论时最容易被忽略、却最值得被复制的部分。【免费下载链接】coucouA tiny friend in your Macs notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.项目地址: https://gitcode.com/gh_mirrors/co/coucou创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 写给 AI 编码代理的「十条工程铁律」Coucou 的 CLAUDE.md 里藏着人机协作的潜规则【免费下载链接】coucouA tiny friend in your Macs notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.项目地址: https://gitcode.com/gh_mirrors/co/coucou2026 年第三季度Coucou 以刘海守护者的姿态连续多日冲上 GitHub 趋势榜——一只叫 Mochi 的小方块住在 MacBook 的刘海以及 Windows/Linux 的屏幕顶端里实时盯梢 Claude Code、Codex、Cursor、Gemini CLI 等 AI 编码代理的每一次文件读写、命令执行与权限请求甚至能在你锁屏后搬到 iPhone 的动态岛上。社区教程从5 分钟上手写到0% CPU 的隐藏性能细节热度背后真正值得深挖的却是仓库根目录那份不足三十行的小文档——CLAUDE.md。它名义上是写给 AI 编码代理的项目指南实质是一部浓缩的人机协作事故史每一条铁律都能在源码里找到对应的强制实现而每一段强制实现又都对应着一类真实的工程事故。这篇文章把十条铁律逐条拆开追到 HookServer.swift、ClaudeSettingsFile.swift、pipe.rs 与 main.rs 里去看看这份潜规则到底在守护什么。一、先说清楚这份文档是写给谁看的Coucou 是双端项目NotchBuddy/是原生 Swift 6 / SwiftUI 的 macOS 应用windows/是 Tauri 2Rust TypeScript的 Windows/Linux 版本。这样一个横跨三种操作系统、十多种 agent 接入的项目靠人肉维护上下文显然不现实——它的真实同事正是 Claude Code 本身README 的 Credits 里坦率写着 Built by Louis Raillé with Claude Code。于是 CLAUDE.md 扮演了入职手册它不教语法而是把不许做的事列成规则。与它同源的还有 CONTRIBUTING.md 里的 Rules of the house面向人类贡献者的简化版两条文档共享同一套价值观只是受众不同。这种双文档同规则的做法本身就是一种工程纪律人类和 AI 代理在同一套约束下工作规则才不会被绕过。把 CLAUDE.md 的 Rules 数一遍正好十条Swift 6 SwiftUI/AppKit零第三方依赖角色纯代码绘制密钥只在 Keychain绝不落盘或进 git零遥测网络调用只面向用户配置的服务永不阻塞 Claude Code应用不响应hook 立即退出永不覆盖~/.claude/settings.json备份、合并、展示 diff、用户确认后才写无显式点击绝不发邮件或批准权限性能铁律岛隐藏时 0% CPU保持 bundle IDfr.louisraille.NotchBuddy不变永不重排已上架的 UIpill、卡片、设置、聊天…pill ID 是稳定契约永不重命名。下面逐条对号入座——每一条都能在源码里找到它的执法者。二、逐条拆解每条铁律背后都是一类真实事故铁律 1零依赖与纯代码绘制堵住供应链与体积两个口子Character is drawn in code (CanvasTimelineView), no Rive/Lottie/images——这条在 macOS 端由 BotCanvasView.swift 执行Mochi 的圆角方块身体、投影在球面上的眼睛、弹跳动画全部是 SwiftUI 绘制出来的不携带任何图片资源Windows 端则由 engine.ts 用 Canvas 2D 复刻同一套形状与时间轴。这条规则防的是两类事故其一是第三方依赖的供应链风险——一个插在 GUI 框架和渲染引擎之间的第三方库本身就是遥测、密钥窃取和崩溃的潜在来源其二是二进制资源的不可审查性——代码可以 reviewPNG 里的像素不能。零依赖换来的是整个仓库可以被人逐行读完的可审计性这在隐私敏感工具上是近乎宗教级的坚持。铁律 2密钥只在 Keychain——防止开源即裸奔Secrets live in the Keychain, never on disk or in git.在 Windows 是 Credential Manager在 Linux 是 Secret ServiceGNOME Keyring / KWallet。以 StripePoller.swift 为例Stripe API key 通过KeychainStore.shared.get(stripe-api-key)取用poll()里第一行就是guard let key ... else { return }——没有密钥就直接放弃轮询而不是降级成明文缓存。开源项目的密钥管理是事故高发区一旦 key 落盘等于把生产凭据写进每一个 clone 者的硬盘。把密钥强制放进系统级保管箱是从机制上让忘记删除密钥这种事变得不可能。铁律 3零遥测——隐私事故的预防性立法Network calls only to services the user configured.这句话在代码层面同样可验证全仓库的网络出口只有三类——用户主动配置的服务 APIGitHub、Notion、Stripe、Vercel、Resend、Cal.com 的 poller、用户自己填的聊天模型 API以及 iPhone 同步时走用户自己的私有 CloudKit 数据库。没有任何埋点上报 SDK没有任何统计一下有多少人用了的匿名收集。社区评论反复强调的全程无遥测、不上传数据正是这条铁律的对外承诺。铁律 4永不阻塞代理——监控工具的生死线这是十条里最重的一条也是整个架构设计的原点。Coucou 的本质是盯梢盯梢者绝不能反客为主拖垮被盯梢者。C 端和 Rust 端各有一套独立的止损机制macOS 端HookServer.swift 为每个客户端 socket 设置 5 秒的SO_RCVTIMEO把单次 payload 上限卡在 1 MBmaxPayload 1_048_576并发连接封顶 32解析失败时立即回写{ok:true}并关闭连接——Claude Code 永远能得到一个正常的应答而不是被挂起。Windows/Linux 端pipe.rs 的注释直接写明了三级保障coucou-hook300 ms 连不上管道就干净退出只有岛确认审批卡片已上屏ACK 800 ms之后才进入等人的长等待无论发生什么决策超时一到就断开连接把决定权交还终端。main.rs 把这一思想执行得更彻底每个 hook 事件都有一条硬预算——连接 300 ms、无人在等的 fire-and-forget 事件 2 秒、权限请求 110 秒。worker 线程超预算就直接process::exit(0)进程死亡会带走管道句柄代理毫发无损。这套预算-超时-让位机制回答了一个所有 agent 监控工具都会遇到的根本问题当监控器宕机时被监控的 AI 是停下等待还是继续干活Coucou 的答案是永远继续。铁律 5settings.json 的备份-合并-diff-确认四段式——配置文件事故的标准疗法Never overwrite~/.claude/settings.json是贡献者最容易踩的坑也是事故率最高的场景一个安装钩子的工具随手把用户精心配置的 settings 文件覆盖成自己的格式等于毁掉用户的整个 agent 工作流。Coucou 用 ClaudeSettingsFile.swift 把它做成了不可跳过的流水线读取即取证read(at:)返回(object, bytes)二元组把解析结果和原始字节一起保留——文件不存在与文件存在但读不了被严格区分读不了就抛错并明示nothing was written写入前校验write(_:to:expecting:)首先比对磁盘上的当前字节与当初展示给用户的字节不一致就抛.changed——防止安装期间用户或另一个工具改动了文件导致用旧快照覆盖新内容原子写先写到同目录的临时文件settings.json.coucou-pidrename()覆盖目标崩溃或磁盘写满只会留下原文件完好带日期备份freeBackupURL(for:)生成settings.json.bak-20261011-0107式命名同一秒内重装也不覆盖上一份备份权限继承与 symlink 尊重备份保留原文件权限位且通过resolvingSymlinksInPath()跟随 dotfiles 常见的符号链接。CHANGELOG 0.2.2 还专门补了一条加固记录~/.claude/settings.jsonis never rewritten from scratch when it cant be read, the backup must succeed before anything is written, and nothing is written if the file changed since the preview——这条规则经历了真实事故无法读取的文件被从零重建后打上了补丁。这正是铁律 5 活的版本历史。铁律 6无点击不执行——把人审做成物理定律Never send an email or approve a Claude Code or Codex permission without an explicit click.权限审批的完整性设计贯穿三层socket 即授权凭证macOS 端收到PermissionRequest后不急于应答而是把连接 fd 一直握在手里pendingApprovalFD只有用户在岛上点击 Allow/Deny/Always 后sendApprovalDecision(_:)才把{permissionDecision:allow}写回 fd——fd 是这场审批还活着的唯一凭证两条退路都不放权无论是超时115 秒Copilot/Muse 因自家 relay 预算更紧而压缩到 110 秒还是卡片被折叠回写的都是ask——把决定权交还给终端里的代理而不是自作主张批准Windows 端的两段式等待pipe.rs 里wait_for_decision先等岛确认卡片上屏Reply::Ack再进入 108 秒的决策等待没有 ack 就返回None管道不写任何字节代理按Coucou 没装的原样在终端重新提问。邮件同理IslandViewContent.swift 里拖拽文件发邮件的路径在 App Store 版必须经过NSSharingService(.composeEmail)让用户亲眼确认GitHub 版用 AppleScript 操作 Mail.app 也是在用户点下发送按钮之后——没有任何静默发送的代码路径。铁律 70% CPU——把隐形即休眠做进状态机0 % CPU when the island is hidden不是营销话术而是一整套可验证的实现。岛隐藏时动画心跳整体暂停TimelineView 驱动只在岛可见时运行指针探测从 60 次/秒降到 8 次/秒CHANGELOG 0.2.2 明确记录the island checks the pointer 8 times a second instead of 60 while it is hidden服务轮询全部可暂停——StripePoller.swift 的poll()第一行就是guard !DemoEngine.isPollerPaused每个 poller 都遵循没人看就不跑的原则音效在启动时预加载成AVAudioPlayer池SoundEngine.swift每音效 3 个实例、默认音量 0.12播放时零 IO。这条铁律防的事故是常驻工具变成电老虎一个自称守护者的应用如果吃 10% CPU用户的第一反应就是卸载。把空闲成本压到零是监控类工具获得长期居住权的入场券。铁律 8bundle ID 是系统身份的锚点Keep the bundle identifierfr.louisraille.NotchBuddy(Keychain items, preferences and permissions depend on it).project.yml 里PRODUCT_BUNDLE_IDENTIFIER: fr.louisraille.NotchBuddy与bundleIdPrefix: fr.louisraille被显式声明且所有涉及系统凭据的路径都以它命名空间——nb.sock、Keychain 条目、UserDefaults 域、沙盒容器App Store 版是fr.louisraille.Coucou。改 bundle ID 的代价是用户钥匙串里的所有密钥全部失联macOS 的 TCC 权限辅助功能、自动化全部重置等于对存量用户执行一次强制重装。铁律 9永不重排已上架的 UI——把 App Store 构建钉成基线existing views stay exactly as they are inmain, which is the App Store build.这条规则承认了一个残酷事实视觉回归是最难测试、最容易在 AI 重构中悄悄发生的损坏。AI 代理顺手优化一个按钮位置或配色在开发分支看起来人畜无害发布后却是用户反馈海啸。把main定义为 App Store 基线等于宣布没有明确需求任何视觉变更都是 bug——这是给擅长自由发挥的 AI 代理上的最紧的缰绳。铁律 10pill ID 是跨系统契约Pill IDs are stable contract values (Keychain, UserDefaults, hook routing): never rename an existing pill ID.PillCatalog.swift 被注释为 single source of truth for all declared pillsintegration_claude、agent_cursor、agent_codex、integration_stripe这些 ID 既是 UI 标识也是 hook 路由键、RecapStore 的统计键、iPhone 同步的记录键。重命名一个 ID会让 Keychain 里的偏好失联、历史 recap 断档、iPhone 上的会话对不上号——docs/AGENTS.md 里第三方 agent 接入的coucou_agent字段校验规则^[a-z0-9-]{1,24}$且claude被保留拒绝以防冒名同样建立在ID 一经发布就是契约之上。三、从 Unix Socket 到构建流程铁律背后的工程观十条铁律看起来零散背后其实是一以贯之的工程观凡是能由机制强制的事就不依赖人的自觉。三个例子足以说明。通道设计进程间通信先谈安全再谈效率。macOS 端在 HookServer.swift 里用 Unix 域套接字接收事件但绝不是建个 socket 就完事目录权限0700、socket 文件chmod 0600、每次accept后用getpeereid校验对端 UID 必须等于本进程 UID——其他人写进来的事件直接拒绝。Windows 端对应的是命名管道\\.\pipe\coucou-user-SIDpipe.rs用 SID 天然隔离用户Linux 端 socket 落在$XDG_RUNTIME_DIR同样以 0600 权限 peer credential 校验收口。跨平台一致的安全基线比任何传输层加密都更本质。审批链路把人在回路的时间预算精确到毫秒。审批是最需要人等的环节也是延迟最容易失控的环节。Coucou 把它拆成两段先让岛用 800 ms 确认卡片真的上屏了确认失败立即让位给终端确认成功后才允许人用最长 108 秒慢慢决定。这样的设计让岛挂了的代价从两分钟骤降到几百毫秒——监控者的故障成本被显式地限制在可接受范围内这正是铁律 4 的工程化落地。数据管线给 AI 代理的噪音设闸。main.rs 对转发的每个字段设置了上限DROPPED_FIELDS直接丢弃tool_response、tool_output、transcript_path这类可能巨大的字段普通字符串截到 2,000 字符只有 live diff 需要的编辑文本Edit/MultiEdit/Write 的old_string/new_string/content放宽到 256 KB 但全事件总量封顶 512 KB保证转发行不超过管道 1 MiB 读取上限。代理每步都可能吐出几十 KB 的输出不让这些噪音撑爆监控通道监控才能做到0% CPU。构建流程同样是契约。project.yml 是 XcodeGen 的声明式工程文件注释明文写着never edit the.xcodeprojby hand——.xcodeproj这种不可 diff 的二进制产物被降级为生成物工程配置的一切变更都能走 review。同一个 yml 里APPSTORE与PHONE_LINK编译条件区分了沙盒构建与 GitHub 构建、ReleaseCloud的 CloudKit 签名把App Store 版少哪些功能也从代码里显式声明出来而不是靠两个工程副本悄悄漂移。四、对自建 AI 工作流的启示把事故翻译成规则把规则翻译成代码Coucou 的 CLAUDE.md 之所以值得当范本不在于规则本身多么新颖而在于它的可验证性十条规则里绝大多数都有对应的代码强制、测试脚本scripts/下 20 多个test-*.sh从屏幕几何到 diff 引擎全覆盖或 CHANGELOG 事故记录。这给所有打算让 AI 代理长期维护自己仓库的团队提供了四条可复制的经验写给代理的文档必须能被机器执行。不要说请保持代码整洁要说依赖必须经过 review、密钥只能走 Keychain、文件先备份再改写。规则越接近代码越难被忽略。把故障预算写进协议。监控、hook、插件这类伴生组件必须回答一个问题我宕机时主流程怎么办Coucou 的答案是立即退出、把决定权交还终端。任何接入 AI 工作流的中间件都应该有同样的 fail-open 设计——代理可以等但绝不允许因为辅助工具故障而停摆。权限审批要证据链化。一次批准 一次显式点击 一个对应的 socket 连接 一个匹配的会话 ID。没有这条证据链所谓人在回路就是空话。自建审批流时务必让人审成为不可绕过的物理环节而不是 UI 上的一个可选按钮。稳定的 ID 与稳定的基线是 AI 重构时代最后的护栏。当代理可以在一夜之间重命名几百个符号、重排几十个视图时像 bundle ID、pill ID、main分支视觉基线这种动了就要赔钱的锚点是唯一能对抗自动化式破坏的机制。说到底这份十条工程铁律真正的潜规则只有一条AI 代理可以获得最大限度的自主权但绝不能获得对用户系统、用户配置、用户审批的默示控制权。所有的规则、预算、校验、备份都在捍卫同一个边界——工具可以聪明但决定永远属于人。这也是 Coucou 在 GitHub 趋势榜上被反复讨论时最容易被忽略、却最值得被复制的部分。【免费下载链接】coucouA tiny friend in your Macs notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.项目地址: https://gitcode.com/gh_mirrors/co/coucou创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考