Obsidian Vault Feed https://reader-feed.pages.dev Markdown notes from Obsidian-Valut, excluding .trash zh-CN Sat, 30 May 2026 15:22:15 GMT obsidian:96667ac78b:workflow/agent/Post by @dillon_mulroy on X.md Post by @dillon_mulroy on X here's my pi session for those asking how i get to this point https://pi.dev/session/#5ddc8747b98a80ad993c18e95270038e… **Dillon Mulroy @dillon\_mulroy** · 2026-05-28 > > my "plans" largely look like pseudo code composed of mostly types/interfaces, how they compose, and their boundaries > > ive recently started including call stacks - been very helpful for both me and agents when implementing > > ![图像](https://pbs.twimg.com/media/HJaKEh8WEAEWv4h?format=jpg&name=large) ![[Pasted image 20260528232830.png]] ]]> Thu, 28 May 2026 15:28:16 GMT https://reader-feed.pages.dev/posts/96667ac78b-Post%20by%20%40dillon_mulroy%20on%20X.md obsidian:1dd6f2ffb8:prompts/fix-bug.md fix-bug 几乎总是，正确的修复不是处理坏状态，而是让坏状态不可能发生。 Mon, 25 May 2026 06:54:02 GMT https://reader-feed.pages.dev/posts/1dd6f2ffb8-fix-bug.md obsidian:7f31b22ca2:Clippings/Cross-Repo Handoff Protocol Coordinating AI Coding Agents Across Separate Repositories.md Cross-Repo Handoff Protocol: Coordinating AI Coding Agents Across Separate Repositories AI coding agents are getting incredibly good at working inside a single repository. They can inspect... Tagged with agents, ai, architecture, softwaredevelopment. Mon, 25 May 2026 06:53:47 GMT https://reader-feed.pages.dev/posts/7f31b22ca2-Cross-Repo%20Handoff%20Protocol%20Coordinating%20AI%20Coding%20Agents%20Across%20Separate%20Repositories.md obsidian:1ee3cf4a1b:Clippings/从 github cli 学习如何设计 agent friendly cli.md 从 github cli 学习如何设计 agent friendly cli GitHub 的 gh 应该是 vibe coding 里非常高频的命令了，而且它 CLI 本身也设计得很 agent-friendly，很适合拿来学习研究。我觉得 gh 最值得学的，不是某几个具体 command，而是它处理了两个很关键的问题：一个是 GitHub 能力面太大，... Sat, 23 May 2026 14:22:58 GMT https://reader-feed.pages.dev/posts/1ee3cf4a1b-%E4%BB%8E%20github%20cli%20%E5%AD%A6%E4%B9%A0%E5%A6%82%E4%BD%95%E8%AE%BE%E8%AE%A1%20agent%20friendly%20cli.md obsidian:1f39138277:Clippings/How's Linear so fast A technical breakdown.md How's Linear so fast? A technical breakdown breakdown of the architecture behind Linear's speed: local-first sync, MobX observables, instant first loads, and a keyboard-first design. ~3 KB. Cache invalidation // becomes per-library instead of per-app-revision. manualChunks(id) { if (id.includes("node_modules")) { const pkg = id.match(/node_modules\/([^/]+)/)?.[1]; if (pkg) return \`vendor-${pkg}\`; } }, }, }, }, }); ``` The lesson isn't which bundler to pick but the importance of dropping legacy browsers, going native ESM, and code splitting like crazy. Each step is small. Stacked, they cut Linear's first-load JavaScript roughly in half and their build time by an order of magnitude. So, the first secret to instant load times is reducing the amount of JavaScript and CSS needed to render something for the user. ### Preloading after initial load **Once you've split your JavaScript into the smallest chunks possible you can start doing work in the background.** But hold on, splitting the bundle into hundreds of chunks creates a new problem. Each chunk imports other chunks, and the browser doesn't know what those are until it parses the entry script. Without help, the load timeline becomes a waterfall: fetch the entry, parse it, fetch its imports, parse those, fetch their imports. Every level adds a network round-trip, which you want to avoid at all costs. What Linear does is before any JavaScript runs, the browser sees the entire list and fires off the requests in parallel. By the time the entry script reaches its first `import`, the chunks are already in cache. Here's what it looks like in the `` if their `index.html` ```html ``` The `crossorigin` attribute on each preload matches the `crossorigin` on the entry script, so the browser reuses the cached fetch instead of treating preload and import as separate resources. Same trick as the font preload, applied to every chunk on the critical path. The cold-load timeline collapses from a sequential waterfall into a single parallel batch. The network still does the work. It just does it all at once. The beauty of this technique is you're able to do all this work in the background when the user first hits the login page. In a few seconds the full app is stored in cache and served instantly. It's extremely important to understand how people will use your app. Once you have this understanding you can start using it to your advantage, such as preloading scripts in the background as Linear does. ### The service worker for even more speed and offline capabilities The rest of the Linear, the route-level chunks for views the user hasn't visited yet, gets cached in the background by a service worker. The worker has a precache manifest baked into its source, around 1,200 hashed assets covering route chunks, icons, and fonts, and pulls them down lazily after the first page load. Within a few seconds of hitting the login screen, the full app is sitting in cache. Preloading all the chunked javascript files to ensure instant loads from cache This buys two things. Subsequent navigations skip the network entirely; the service worker answers directly from its cache without even going through HTTP cache. And the app keeps working when the network doesn't. Combined with the local-first sync engine (which already has the user's data in IndexedDB), Linear is usable offline. You can read issues, create new ones, edit titles and descriptions, change statuses. Everything queues in the local transaction store and flushes the next time the connection comes back. Modulepreload is for what the app needs now, parallel-fetched so the browser never blocks on a serial import chain. The service worker is for what the app needs next. So, to get load times fast the steps for Linear is to elminate as much code as possible, split it into small pieces, and precache it in the background. Again, the goal of all this work is to make network requests as fast as possible or, even better, eliminate them completely. ### Vendor bundle composition I found it interesting that every package Linear uses gets its own chunk, cached independently. A traditional `vendor.js` invalidates the entire dependency graph on any bump. Linear's chunking turns vendor caching from a single massive file to fine-grained. Bumping a single dependency invalidates one chunk; the rest stay cached. Seems like a no-brainer and yet another detail to ensure fast load times. ![](https://media.performance.dev/cdn-cgi/image/width=2400,quality=100,format=auto,fit=scale-down/posts/p_gAMR6Z7y49Fp/b5RGjc_nI54O.jpg) Each individual package split into its own js file ### Loading massive font files Font loading is one of those details a lot of apps get wrong. The failure modes are visible: invisible text for half a second, layout shifts as the real font swaps in, double-fetched resources because the preload didn't match. Linear's setup avoids all three: ```html ``` ```css @font-face { font-family: "Inter Variable"; font-weight: 100 900; font-display: swap; src: url(https://static.linear.app/fonts/InterVariable.woff2?v=4.1) format("woff2"); } /* Italic and Berkeley Mono follow the same shape, single woff2 each. */ ``` Variable fonts cover the full 100–900 weight axis in a single woff2, eliminating per-weight requests. `font-display: swap` renders the fallback stack immediately and swaps to Inter when it loads. The trick that's easy to miss: `crossorigin="anonymous"` on the preload tag. Without it, the browser preloads the font, then fetches it again when CSS later references it, because the two requests have different CORS modes. `crossorigin` on the preload makes the browser reuse the cached one. This all seems simple, but I'm always surprsied at how many apps load fonts incorrectly. Linear is a great example of thinking through the details and ensuring font loading is as fast and accurate as possible. ### Inlined app shell Another key tehcnique to make the first load feel fast: Inlined in `` is just enough CSS to paint the loading state with no external stylesheet fetched. Remember, the network is the bottleneck and what you'll always be fighting to make your app feel fast. In this case, Linear elminates a network request by inlining the critical CSS required to show the user an app shell. ```css ``` Beyond CSS there is also a bunch of inlined JavaScript that's critical to loading the initial experience. ```typescript ``` Before any bundle has parsed, the JavaScript from `index.html` reads `localStorage.splashScreenConfig`, merges any `sessionStorage` override on top, and applies the user's remembered shell tokens directly to `document.documentElement.style`: sidebar background, base color, border color, sidebar width, agent toolbar height. It detects color-scheme preference and Electron context. It checks whether `localStorage.ApplicationStore` exists, and if not, adds a logged-out class that switches the shell to the auth layout. By the time the first JavaScript bundle comes from the network the loading screen is already correctly themed, sized, and positioned for whether the user is logged in. This gives the user the feeling that the app is ready to go as soon as they hit enter in the URL bar. There's no faster way around this than sending down the initial app shell in the initial `index.html` response. An example of how fast Linear's initial load is ### Render first, authenticate second Authentication is another step where most apps give up their performance budget. The conventional flow: fetch the HTML, load the bundle, validate the session, fetch the user, fetch the workspace, then render. One to three seconds before the user sees anything. Linear treats auth the same way it treats mutations. Assume the happy path and verify in the background. This is probably one of my favorite parts of their architecture because it allows them to almost immediately render the full experience on load. Most CRUD apps keep the real session in an HttpOnly cookie, then add a second JS-readable cookie or `/me` request so the frontend can tell whether the user is logged in during startup. Linear does something simpler. Instead of maintaining a parallel auth signal, the inline boot script just checks whether `localStorage.ApplicationStore` exists: ```javascript if (localStorage.getItem("ApplicationStore") === null) { document.documentElement.classList.add("logged-out"); } ``` If it's there, the user has used Linear in this browser before, which means their workspace is already sitting in IndexedDB. This goes back to the first section we covered where the database lives in the browser. If it's missing, there's nothing to render anyway, so the shell flips to its logged-out layout and the login flow takes over. The initial flow for Linear isn't "do you have a valid session." It's "do we have anything to show you." Their actual session token sits in a cookie. The bundle never tries to be smart about it. It just renders what it has and lets the next request (the WebSocket handshake, a sync delta, any HTTP call) be the thing that fails with a 401 if the session has gone stale. When that happens, the client redirects to login. The whole pattern is consistent with the rest of the architecture: the client trusts what's local, the server is the source of truth for correctness, and the two reconcile asynchronously. Just like a mutation. Just like their sync engine. Manually deleting the auth session and refreshing the desktop app This is maybe one of my favorite details about Linear that I wish more apps behaved this way. For authentication, assume happy path, and fallback if not. If there's data to be shown: show it! And leverage your browser's datastores to render immediately. --- ## The sync engine Most of what makes Linear fast lives downstream of one decision: the server is a sync target, not a source of truth for the UI. The internals of their sync engine been thoroughly reverse-engineered already, and Tuomas has given multiple excellent talks on the architecture. I'm not going to retrace them. What I want to do is name the three pillars that actually produce the speed, because the speed is a property of how they fit together, not of any single one. ### 1\. The data is already there When the app boots, it doesn't fetch the workspace from the server. It hydrates from IndexedDB into an in-memory MobX object pool, and every query from the UI goes to the pool first. There's no "loading issues" state because the issues are already on the user's machine. Something I found interesting is as they've scaled they've chunked the data in the sync enginer using the similar fundamentals as their JavaScript bundles. Not everything is fetched at once: the two heaviest tables, Issue and Comment, lazy-hydrate on demand. This is data-level code splitting, and it's what lets the engine scale: startup cost tracks the workspace structure, not the workspace size. A 10,000-issue workspace boots about as fast as a 100-issue one. Click into a project, the issues are there. Filter by assignee, the index is already built. There's nothing to fetch because there's nothing missing. It's either been immidately loaded from your browser or shortly after in a codesplit lazy chunk. ![](https://media.performance.dev/cdn-cgi/image/width=2400,quality=100,format=auto,fit=scale-down/posts/p_gAMR6Z7y49Fp/IdWPGINS86Ge.png) IndexedDB: the database is in your browser ### 2\. Mutations don't wait for the network When you change an issue's status, three things happen almost at once: the MobX observable updates so the UI reflects the change, the mutation is written to a durable transaction queue in IndexedDB, and it's queued for the server. The network hasn't been touched yet. The user never waits to see their own change. The retry, the rollback, the durability across reloads, all background. If the server rejects, the observable reverts and there's a brief flicker, but in practice that almost never happens because most invalid mutations are caught before the transaction is even created. As I keep saying: the network is the enemy and you must do everything you can to avoid it. Linear's flow starts with the local mutation and treats the server as a confirmation step, not a permission step. ### 3\. One delta, one cell When the server confirms a mutation (yours or someone else's), the change comes back as a small JSON envelope describing what moved. The client applies it by writing to the corresponding MobX observable. Because every property on every model in Linear is its own observable, and every component that reads one is wrapped in `observer()`, MobX knows exactly which components depend on which fields. A change that updates one field of one issue re-renders exactly the components that read that field. Not the parent list, not the sidebar, one cell. A 50-issue update is 50 cell re-renders, not a list re-render. This is what lets a busy workspace stay smooth when ten people are editing things at once: the cost of receiving updates scales with what changed, not with what's on screen. I've built real-time apps streaming in stock data and fundamentals and having atomic updates of individual components it key to making an app feel performant. You want to avoid cascading updates as much as possible and Linear does exactly that. Updating an issue in the list and single issue row re-renders ### Why the three fit together Take any one away and the app starts to feel slow. A local database without optimistic writes still spins on save. Optimistic writes without granular observables still jank on every update. Granular observables without a local database still wait on initial load. Linear's speed isn't a property of any single layer. It's a property of the system. The bundler and loader shell are what make the app feel fast on first paint. The sync engine is what keeps it feeling fast once you start using it. --- ## Designed for speed Speed isn’t just an engineering problem. It’s a design problem too. A perfectly built sync engine still loses to a slow input model: if the fastest path to an action requires a mouse, three menus, and a click, the user pays for those steps regardless of how fast the underlying engine runs. Another cornerstrone to Linear's speed is how they've intergarated the keyobard as a priamry tool to navigate and complete your work. Every common action has a shortcut. The command palette is one keystroke away. The right-click menu is custom-built. None of these are accidents but instead thoughtful design decision from day one. ### Every action has a shortcut Single letters edit the focused issue. Two-letter combos navigate. Modifiers act globally. Listening to the founders talk about Linear’s early days, it’s clear that shortcuts were foundational from the start. The sync engine was designed in part so that any action could be performed at any time. It feels like this combination of design and engineering is continues to be behind every feature. If you look through their UI you'll notice shortcuts visible everywhere. The most frequent ones are single characters as they're used the most often. Furthermore, every action can be done with a mouse as not to alienate beginners. ![](https://media.performance.dev/cdn-cgi/image/width=1584,quality=100,format=auto,fit=scale-down/posts/p_gAMR6Z7y49Fp/2Jd6ZXiwNCwp.jpg) ![](https://media.performance.dev/cdn-cgi/image/width=1584,quality=100,format=auto,fit=scale-down/posts/p_gAMR6Z7y49Fp/2__J_PuPKayE.jpg) ![](https://media.performance.dev/cdn-cgi/image/width=1584,quality=100,format=auto,fit=scale-down/posts/p_gAMR6Z7y49Fp/MuG3qxjnzrQq.jpg) ![](https://media.performance.dev/cdn-cgi/image/width=1584,quality=100,format=auto,fit=scale-down/posts/p_gAMR6Z7y49Fp/KgHIdD85Bfr5.jpg) ![](https://media.performance.dev/cdn-cgi/image/width=1584,quality=100,format=auto,fit=scale-down/posts/p_gAMR6Z7y49Fp/jvagQZ3l8V3y.jpg) ![](https://media.performance.dev/cdn-cgi/image/width=1584,quality=100,format=auto,fit=scale-down/posts/p_gAMR6Z7y49Fp/Y6mUzOgZJJHW.jpg) ### The command palette is always one keystroke away `⌘ k` opens a command palette that lets users search over almost any action in Linear. Issues, projects, labels, status changes, navigation, issue creation, settings, theme toggles. The command is incredibly fast because it's searching the local MobX object pool, not a server. Remember, avoid the network. The architectural payoff is that the entire app is accessible from a single pane. Navigation is search. Issue creation is search. Status changes are search scoped to statuses. Moreoever, the command is contextual and adapts to the what you're working on. A great way to teach key actions and shortcuts for any view. One primitive, used everywhere, running on data that's already in memory. A fast app needs both incredible engineering and design. You can build a perfect sync engine and a flawless rendering pipeline, and still ship something that feels slow if the design is wrong. Engineering speed makes a single interaction fast. Design speed makes the path to each interaction short. For a tool used all day, the difference between a shortcut and a two-second mouse path compounds over every action. Combine shortcuts with a global commmand palette and you've got yourself an app that's incredibly fast to use. --- ## Animations All the work up to now can still be undone by bad animations. Teams spend enormous effort making every part of their app fast. Initial load, updates, database queries, all of it. They shave off milliseconds so users never have to wait. Then, at the very last step, someone adds a 500ms height animation to an element. ### There are only a handful of properties you should animate Browsers have three tiers of property changes, and the cost scales with how high each one is on the rendering pipeline. Composited properties (`transform`, `opacity`) hand the work to the GPU and run independent of the main thread. Paint-triggering properties (`color`, `background-color`, `border-color`, `fill`) skip layout but still redraw pixels. Layout-triggering properties (`width`, `height`, `top`, `left`, `margin`, `padding`) force the browser to recompute the position of every subsequent element on the page. Never animate those. I mean never. ```css /* What Linear does */ .row:hover { background-color: var(--color-bg-hover); transition: background-color 0.12s; } .icon-arrow { transform: translateX(0); transition: transform 0.15s; } /* What you'd write if you didn't know better */ .row:hover { margin-left: 2px; /* triggers layout for every row beneath */ transition: all 0.2s; /* and now you're animating margin */ } ``` The `margin-left` version recomputes the layout of every row beneath the hovered one, on every frame, for the full 200ms of the transition. On a long issue list that's the difference between buttery and jank. If you go over every single property Linear animates in their app it's reserved to a handful, mostly those composited properties (`transform` and `opacity`) and sometimes properties like `background-color` and `border-color`. ### Know when to hold back In my opionion, what's almost as important as only animating composite properties is knowing when to not animate at all. It's easy to get carried away with animations. But in a tool used every day, the animations you'd love on a marketing site start to get in the way. Even a small hover delay, in the wrong place, becomes the thing the user notices. Linear nails most of this. The command palette is the one I'd argue is too slow, but I've become a cranky old man over the years. There are no transitions on list tiems to keep things snappy The reason a lot of their animations work is that they reference their origin. The status popover scales out of the status pill. The agent panel slides in from its toggle. The motion is doing spatial work, telling the user where the new element came from, rather than fading in from nowhere as decoration. ### Keep durations short and snappy ```css /* variables form Linear's stylesheet */ --speed-highlightFadeIn: 0s; --speed-highlightFadeOut: .15s; --speed-quickTransition: .1s; --speed-regularTransition: .25s; --speed-slowTransition: .35s; ``` Most design systems default longer than they should. Material's standard duration is 200ms, iOS's spring closer to 350ms. Defaulting to shorter transitions is one of the easiest ways to make an app feel faster, and Linear's defaults sit well below the industry norm. Linear takes this one step further with asymmetric timing on enter and exit. Hover highlights, popovers, and the agent panel appear instantly when you summon them, then fade out over 150ms when you dismiss them. The agent window appears instantly but fades out similar to macOS --- ## How Linear is so fast There are so many more details I could cover that make Linear feel fast. The reality is there's no single thing that makes an app performant. It's the culmination of hundreds of decisions made correctly. What I love about Linear's approach is how simple most of it is. No Next, no Tanstack, no fancy framework. They decided early on what architecture would serve their users best and have stayed true to it. The result is a client-side rendered app that's faster than server-rendered ones (and without the complexity)! The shape of it is roughly this. The server is a sync target rather than a source of truth. The database lives in the browser. Mutations apply locally first and reconcile in the background. The first load ships less code in more pieces, with a service worker precaching the rest while the user is still on the login page. Auth is assumed based off state and verified later. The sync engine hydrates from IndexedDB into per-property MobX observables, so a 50-issue update is 50 cell re-renders rather than a list re-render. The input model is keyboard-first. Every common action has a shortcut with a global command palette. Animations stay on the GPU, durations sit below the 100ms cause-and-effect threshold, and layout-triggering properties are never animated. The hard part isn't the implementation. It's the dedication to the craft over years, as the codebase matures, expands, and pushes up against new constraints. If you haven't, I'd recommend checking out [Linear](https://linear.app/) to see it all in action. --- Hope you learned a thing or two! It was fun writing this and diving into the details that make Linear what it is. I just love building the best web apps in the world and see how other people do it. If you have any feedback, suggestions, or want to connect you can [find me on X.](https://x.com/brotzky) ]]> Sat, 23 May 2026 12:51:39 GMT https://reader-feed.pages.dev/posts/1f39138277-How%27s%20Linear%20so%20fast%20A%20technical%20breakdown.md obsidian:245b68ca35:Clippings/How to use evals and prompt engineering to ship a local model that matches frontier performance.md How to use evals and prompt engineering to ship a local model that matches frontier performance Most production AI features don't need a frontier model. Here's how I used capability evals and prompt engineering to ship a local 3B model ... Sat, 23 May 2026 06:51:21 GMT https://reader-feed.pages.dev/posts/245b68ca35-How%20to%20use%20evals%20and%20prompt%20engineering%20to%20ship%20a%20local%20model%20that%20matches%20frontier%20performance.md obsidian:32920a2eb7:art/MMD渲染配方-Unity可行性分析.md MMD 渲染配方 —— Unity 实现可行性分析 > 原文：https://www.bilibili.com/opus/1178669996791824392 原文：https://www.bilibili.com/opus/1178669996791824392 > 作者分享了一套完整的 MMD 渲染管线，用于制作高质量静画/视频。 --- ## 一、使用的 MME 效果清单与技术分析 ### 🎨 色彩与材质 | MME 名称 | 功能 | Unity 实现 | |----------|------|------------| | **nbHSV** | 色相/饱和度/明度调节，分材质控制（hair/face/body） | ✅ 很轻松。用 Shader Graph 写 HSV 调整节点，或直接使用 Post Processing 的 Color Grading + Material Property 区分 | | **lv2shader** | 主渲染着色器，提供精细阴影、柔和阴影（第13行调阴影柔和度）、可分离唇部材质阴影 | ✅ Unity 中这就是 Toon Shader。用 Shader Graph 自定义卡通渲染，half-lambert + ramp texture 即可实现，阴影柔和度通过 ramp 图控制 | | **SPA 贴图** | 高光贴图（Specular），仅给前发上 | ✅ 标准 PBR/Toon shader 中直接使用 Specular/Smoothness 贴图，或自定义高光遮罩 | | **発光コンタクト** | 金属提亮效果 | ✅ Emission map + metallic/smoothness 控制 | | **m4layer 叠加** | 混合多种渲染器结果（如 ps 渲 + dg 渲），增强质感 | ✅ Unity 中可以用多个 Camera + RenderTexture 叠加，或 Shader 中多 Pass 混合 | ### ✨ 后处理效果 | MME 名称 | 功能 | Unity 实现 | |----------|------|------------| | **motionblur3L** | 运动模糊 | ✅ URP/HDRP 内置 Motion Blur，或 Post Processing Stack | | **lightbloom SJ** | 泛光（Bloom），支持 Mask（除眼睛高光外全遮罩） | ✅ 内置 Bloom，用 Custom Pass / Render Feature 做 Bloom Mask | | **g ALB** | 自发光（眼睛高光），可做"关灯"效果 | ✅ Emission material property，用 MaterialPropertyBlock 动态控制强度做开关灯 | | **SSAA 4xL2** | 超采样抗锯齿 | ✅ MSAA 或 SSAA（Render Scale > 1.0）| | **sdFxaa** | FXAA 抗锯齿 | ✅ 内置 FXAA | | **sdUnsharpMask** | USM 锐化 | ✅ Post Processing 中无内置，但可写自定义 Shader 或下载社区方案 | | **sdSSGI** | 屏幕空间全局光照，可调色相/饱和度/阈值，支持遮罩 | ✅ 这是最复杂的。可以用 SDFGI（HDRP）、SSGI 插件、或自己写 Screen Space GI Shader。URP 中可用 Renderer Feature + Compute Shader 近似实现 | | **PostRimLightToon** | 边缘光，可调粗细，替代头发高光 | ✅ Toon Shader 中加 Fresnel/Rim Light 节点即可，非常标准 | | **PostDropHair** | 头发在前额的投影（阴影），精度比 lv2 更高 | ✅ Unity 中可用 Projector 或 Decal 系统，或用第二个 Pass 渲染阴影。URP 中 Custom Render Feature 也适用 | | **ikboken** | 景深（DOF），可随镜头远近 K 帧 | ✅ 内置 Depth of Field（Bokeh 模式） | | **msGradation1/2** | 渐变叠加（增加对比 + 上方渐变光），模拟动画摄影打光 | ✅ UI 层叠加渐变图，或用 Post Processing 自定义 Color Lookup / Gradient Overlay | | **Cheaplens** | 暗角（Vignette） | ✅ 内置 Vignette | | **PostAlphaMask** | 眼睛透过头发（Alpha 排序/遮罩） | ✅ Shader 中控制 Render Queue + Alpha Clip / ZWrite，或用 Stencil Buffer 精确控制 | | **ikEdgeBlur** | 边缘模糊加深，增加质感 | ✅ 可用 Sobel 边缘检测 + 模糊 + 加深，自定义后处理 Shader | | **SwapScreen/SplitView** | 渲染前后对比 | ✅ Editor 工具，Unity 中可用 A/B 对比或 Custom Render Feature 显示 | ### ✏️ 轮廓线 | MME 名称 | 功能 | Unity 实现 | |----------|------|------------| | **krtoon2**（3个） | 轮廓线，分材质控制粗细、五官 noedge、后发 halfedge | ✅ Inverted Hull 方法（经典）、Sobel 后处理描边、或 Unity Toon Shader (UTS) | | **Dippen Natural + 控制器** | 另一套轮廓线系统，分材质调强度（五官 0.0，前发 0.25） | ✅ 同上。Unity 中不同材质用不同描边参数即可 | ### 💡 打光 | 光源 | 功能 | Unity 实现 | |------|------|------------| | **PostPointLight ×4** | 不同颜色/角度的点光源绑定头部：白色提亮、紫色轮廓光、暖色渐变光、发尾提亮。每个光源都有独立的头发/五官/皮肤遮罩 | ✅ Unity 内置 Point Light + 自定义 Light Layer/Culling Mask 精确控制每个光源照哪些物体。遮罩用 Light Cookies 或 Light Layers（URP/HDRP） | | 绑定头部 | 光源 Follow 头部骨骼 | ✅ 直接将 Light 设为头部的子物体，或脚本跟随 | --- ## 二、核心技术栈总结 ``` 📦 渲染管线层次： ├── 材质层 (Material) │ ├── 卡通主渲（lv2shader / Toon Shader） │ ├── HSV 调色（nbHSV） │ ├── 高光贴图（SPA） │ ├── 自发光（g ALB） │ ├── 轮廓线（krtoon2 + Dippen） │ ├── 边缘光（PostRimLightToon） │ ├── 头发投影（PostDropHair） │ └── Alpha 透过（PostAlphaMask） ├── 光照层 (Lighting) │ ├── 多点光源（PostPointLight ×4+） │ └── 屏幕空间 GI（sdSSGI） ├── 后处理层 (Post Processing) │ ├── Bloom（lightbloom SJ） │ ├── 运动模糊（motionblur3L） │ ├── 景深（ikboken） │ ├── 抗锯齿（SSAA + FXAA） │ ├── 锐化（sdUnsharpMask） │ ├── 渐变叠加（msGradation） │ ├── 暗角（Cheaplens） │ └── 边缘模糊（ikEdgeBlur） └── 调试层 └── 渲染对比（SwapScreen） ``` --- ## 三、Unity 中实现的可行性评估 | 方面 | 评估 | |------|------| | **总体可行性** | ✅ **完全可以实现**，所有效果 Unity 都支持 | | **推荐渲染管线** | **URP**（平衡效果与性能）或 **HDRP**（最佳画质）。Built-in 也行但需要更多手写 | | **推荐工具** | Shader Graph + VFX Graph + Post Processing + Custom Render Features | | **难度分布** | 90% 效果 = 简单（内置/社区方案）；sdSSGI = 中等（需手写或找插件）；分材质遮罩系统 = 需要仔细设计 Render Feature / Stencil | | **关键依赖** | Unity Toon Shader (UTS3)、Post Processing、Custom Renderer Features | ### 🎯 在 Unity 中实现这个配方的推荐路线 1. **基础渲染**：用 **UTS (Unity Toon Shader)** 或 **Shader Graph 自建 Toon Shader** 作为主渲，实现 ramp 阴影、轮廓线、边缘光 2. **材质控制**：通过 Material Property Block 或不同 Material 实例，实现分材质控制 HSV、描边粗细、自发光等 3. **光照**：多点光源 + Light Layers / Culling Mask 实现精确遮罩。光源跟随骨骼用脚本绑定 4. **后处理**：URP 内置 Volume 组件一键实现 Bloom、DOF、Motion Blur、Vignette、Color Grading 5. **高级效果**：sdSSGI 和 PostDropHair 用 Custom Render Feature 实现，或找 Asset Store 插件 6. **调试对比**：写一个简单的 Editor 脚本做 SplitView 即可 --- ## 四、结论 这篇文章本质上是一套完整的 **三渲二（NPR/Toon）渲染管线**，涵盖了： - **Toon Shader**（卡通阴影 + ramp 控制） - **多套轮廓线系统**（krtoon2 + Dippen，分材质控制粗细和开关） - **完整的后处理链**（Bloom、DOF、Motion Blur、Vignette、Color Grading、锐化、SSGI） - **精细的多光源打光**（4 个以上点光源，各自有独立遮罩，跟随头部骨骼） - **材质分层控制**（头发、皮肤、五官各自独立的 HSV / 发光 / 描边参数） - **高级 NPR 技巧**（眼睛透过头发、头发投影、边缘模糊质感、渐变叠加） 所有这些技术在 Unity 中都有成熟的实现方案。核心投入在 **Toon Shader 的自定义** 和 **遮罩系统的设计** 上，其余后处理效果 Unity 基本都有开箱即用的支持。 原始配布链接汇总： - nbHSV：https://www.nicovideo.jp/watch/sm39274461 （作者：のべ男） - lv2shader：https://www.bilibili.com/video/BV1DqkSBbEF8/ （作者：winglayer） - motionblur3L：https://seiga.nicovideo.jp/seiga/im3061709 （作者：そぼろ） - lightbloom SJ：https://www.aplaybox.com/details/model/RKjvijIaYsVX （作者：三金络合物） - g ALB：https://bowlroll.net/file/182490 （作者：呉石） - krtoon2：https://kagitaba.fanbox.cc/posts/4962246 （作者：鍵束） - Dippen：https://fujisunflower.fanbox.cc/posts/1422906 （作者：サンフラワーふじ） - sdSSGI：https://www.nicovideo.jp/watch/sm43948524 （作者：サンドマン） - PostRimLightToon：https://bowlroll.net/file/146255 （作者：P.I.P） - PostDropHair：https://bowlroll.net/file/178761 （作者：P.I.P） - ikboken（三金改造版）：https://www.bilibili.com/opus/658890877048979479 - msGradation：https://bowlroll.net/file/210901 （作者：ましまし） - Cheaplens：https://bowlroll.net/file/337397 （作者：そぼろ） - PostAlphaMask：https://bowlroll.net/file/152266 （作者：P.I.P） - SwapScreen/SplitView：https://ux.getuploader.com/Elle_DataPort/download/19 （作者：データ P） - PostPointLight (tn)：https://bowlroll.net/file/188141 （作者：呉石） - PostPointLight：https://www.nicovideo.jp/watch/sm14626601 （作者：ビームマンP） - 発光コンタクト：https://bowlroll.net/file/169064 （作者：996） ]]> Fri, 22 May 2026 04:39:13 GMT https://reader-feed.pages.dev/posts/32920a2eb7-MMD%E6%B8%B2%E6%9F%93%E9%85%8D%E6%96%B9-Unity%E5%8F%AF%E8%A1%8C%E6%80%A7%E5%88%86%E6%9E%90.md obsidian:323ba94efa:art/个人向2d风格渲染分享.md 个人向2d风格渲染分享 半斤悠哉糖 Fri, 22 May 2026 04:37:01 GMT https://reader-feed.pages.dev/posts/323ba94efa-%E4%B8%AA%E4%BA%BA%E5%90%912d%E9%A3%8E%E6%A0%BC%E6%B8%B2%E6%9F%93%E5%88%86%E4%BA%AB.md obsidian:bfc3744a0d:workflow/project/unity工程优化建议.md 先给结论 你说得对，前一版建议更多是基于你给的两篇文章做工程推理。重新查 Unity 官方文档、Unity 官方发布页和 Gitea 官方文档后，我会把建议调整成下面这版。重点变化是：**Unity 6.2+ 的验证脚本、Gitea Actions、本地 Gitea LFS、分支保护、Build Profile、测试命令细节，都要更实际一些。** **跑 Unity Test Framework 的 `-runTests` 时，不要加普通 `-quit`。** Unity 6.2 Test Framework 文档明确给出的命令是 `Unity.exe -runTests -batchmode -projectPath ... -testResults ... -testPlatform ...`，并且命令行参考里写了：Editor 的普通 `-quit` 在测试运行时不受支持。([docs.unity.cn](https://docs.unity.cn/6000.2/Documentation/Manual/test-framework/run-tests-from-command-line.html)) 所以我建议这样拆： ```bash tools/ validate-fast.sh # EditMode tests + project validation validate-full.sh # PlayMode tests + build/profile validation unity-env.sh # 统一找 Unity 路径 ``` ### `tools/unity-env.sh` ```bash #!/usr/bin/env bash set -euo pipefail : "${UNITY_PATH:=}" if [ -z "$UNITY_PATH" ]; then if command -v Unity >/dev/null 2>&1; then UNITY_PATH="Unity" else echo "UNITY_PATH is not set and Unity was not found in PATH." >&2 echo "Example:" >&2 echo " export UNITY_PATH=/home/build/Unity/Hub/Editor/6000.2.xf1/Editor/Unity" >&2 exit 1 fi fi export UNITY_PATH export PROJECT_PATH="${PROJECT_PATH:-$(pwd)}" export LOG_DIR="${LOG_DIR:-$PROJECT_PATH/Logs}" mkdir -p "$LOG_DIR" ``` ### `tools/validate-fast.sh` ```bash #!/usr/bin/env bash set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" source "$SCRIPT_DIR/unity-env.sh" echo "Unity version:" "$UNITY_PATH" -version || true echo "Running EditMode tests..." "$UNITY_PATH" \ -batchmode \ -projectPath "$PROJECT_PATH" \ -runTests \ -testPlatform EditMode \ -testResults "$LOG_DIR/editmode-results.xml" \ -logFile "$LOG_DIR/editmode.log" echo "Running project validation..." "$UNITY_PATH" \ -quit \ -batchmode \ -projectPath "$PROJECT_PATH" \ -executeMethod Project.Editor.Validation.ProjectValidationCommand.RunAll \ -logFile "$LOG_DIR/project-validation.log" ``` ### `tools/validate-full.sh` ```bash #!/usr/bin/env bash set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" source "$SCRIPT_DIR/unity-env.sh" echo "Running PlayMode tests..." "$UNITY_PATH" \ -batchmode \ -projectPath "$PROJECT_PATH" \ -runTests \ -testPlatform PlayMode \ -testResults "$LOG_DIR/playmode-results.xml" \ -logFile "$LOG_DIR/playmode.log" echo "Running build validation..." "$UNITY_PATH" \ -quit \ -batchmode \ -projectPath "$PROJECT_PATH" \ -executeMethod Project.Editor.Build.BuildValidationCommand.RunAll \ -logFile "$LOG_DIR/build-validation.log" ``` `-executeMethod` 适合 CI、构建、数据准备、项目验证这类任务；Unity 文档也说明该方法必须是 static，脚本要放在 Editor 代码路径里，失败时可以抛异常或 `EditorApplication.Exit` 返回非零退出码。([docs.unity.cn](https://docs.unity.cn/6000.2/Documentation/Manual/EditorCommandLineArguments.html)) --- # 2. Unity 6.2+ 要把 Build Settings 建议升级成 Build Profiles 建议 你的 Unity 版本是 6.2+，所以我建议文档里不要只写传统 Build Settings。Unity 6.2 的命令行参数已经有 `-activeBuildProfile ` 和 `-build `，可以直接从命令行指定 Build Profile 后构建。([docs.unity.cn](https://docs.unity.cn/6000.2/Documentation/Manual/EditorCommandLineArguments.html)) 因此 `docs/build-and-release.md` 建议写成： ```markdown ## Build Profiles Build profiles live under: Assets/_Project/BuildProfiles/ Known profiles: - WindowsDev.asset - WindowsRelease.asset - AndroidDev.asset - AndroidRelease.asset Agents must not create or modify Build Profiles unless the task explicitly requires build configuration changes. ## CI Build Example Unity \ -quit \ -batchmode \ -projectPath . \ -activeBuildProfile "Assets/_Project/BuildProfiles/WindowsRelease.asset" \ -build "Builds/Windows/Game.exe" \ -logFile Logs/build-windows.log ``` 如果你的项目已经有自定义 `BuildPipeline.BuildPlayer` 脚本，也可以继续保留。但在 Unity 6.2+ 文档里，我会明确补一句： > Build Profile 是一等配置资产，修改它等同于修改构建策略，属于高风险变更。 --- # 3. Gitea 本地部署下，Git LFS 是 P0，不是可选项 Unity 项目有大量 `.psd`、`.fbx`、`.png`、`.wav`、`.mp4`、`.blend`、贴图、音频、模型等二进制资源。用本地 Gitea 时，要先确认 Gitea 服务器启用了内置 LFS。Gitea 官方文档要求在 `app.ini` 中启用 `LFS_START_SERVER = true`，并设置 `[lfs] PATH`；文档也注明 LFS server 支持需要服务器安装至少 Git v2.1.2。([docs.gitea.com](https://docs.gitea.com/next/administration/git-lfs-setup)) Gitea `app.ini` 建议： ```ini [server] LFS_START_SERVER = true [lfs] PATH = /var/lib/gitea/data/lfs ``` 仓库里建议执行： ```bash git lfs install git lfs track "*.psd" git lfs track "*.fbx" git lfs track "*.blend" git lfs track "*.png" git lfs track "*.tga" git lfs track "*.wav" git lfs track "*.mp3" git lfs track "*.mp4" git lfs track "*.mov" git lfs track "*.zip" git lfs track "*.unitypackage" ``` 并提交 `.gitattributes`。 如果你们 Gitea 走 SSH，而且想用 LFS pure SSH，需要额外谨慎。Gitea 官方文档说 pure SSH LFS 支持可以开启，但默认关闭，并提到 git-lfs 客户端存在会导致 SSH transfers hang 的 open bug， workaround 是客户端设置 `git config --global lfs.ssh.automultiplex false`。除非你非常确定需要纯 SSH LFS，否则建议先用 HTTPS LFS 或常规配置。([docs.gitea.com](https://docs.gitea.com/next/administration/git-lfs-setup)) --- # 4. `.meta`、Force Text、UnityYAMLMerge：建议保留，但要更精确 Unity 官方文档确认：Visible Meta Files 是给 Unity 不直接支持的版本控制系统使用的模式，可以用你选择的 VCS 管理源资产和 metadata。([docs.unity.cn](https://docs.unity.cn/6000.0/Documentation/Manual/class-VersionControlSettings.html)) Unity Editor 设置里，Asset Serialization 的 `Force Text` 会把所有资产转成 Text 模式，包括新资产；文档也说明 Unity 可以用文本格式保存 Scene 来帮助版本控制合并。([docs.unity.cn](https://docs.unity.cn/Manual/class-EditorManager.html)) 因此这几条要保留在 `AGENTS.md`： ```markdown ## Unity Version Control Rules - Version Control Mode must be Visible Meta Files. - Asset Serialization Mode must be Force Text. - `.meta` files must be committed. - Do not manually edit `.meta` files. - Move and rename assets inside Unity Editor whenever possible. - Do not move or rename `.unity`, `.prefab`, `.asset`, `.meta`, `.asmdef` unless the task explicitly requires it. ``` Unity 官方的项目组织建议也强调 `.meta` 记录导入设置，应该提交；并提醒移动资产时最好在 Editor 内移动，这样 `.meta` 会随资产一起移动。官方还提到 Git 默认忽略空目录，空目录的 `.meta` 可能导致协作问题，所以空目录要么避免，要么放 `.keep`。([unity.com](https://unity.com/how-to/organizing-your-project?ampDeviceId=bd73ee3b-a36f-4585-8d3e-967cba74f006&SessionId=1771632000345&Timestamp=1771718400359)) UnityYAMLMerge 这块也要保留，但要补一句： > `.gitattributes` 只是声明某些文件用 `unityyamlmerge`，每个开发机和 runner 还要配置 Git merge driver。 Unity 官方 Smart Merge 文档说明 UnityYAMLMerge 随 Unity Editor 提供，可用于语义正确地合并 scene 和 prefab，并给出了 Git mergetool 配置方式。([docs.unity.cn](https://docs.unity.cn/2021.1/Documentation/Manual/SmartMerge.html)) 建议 `.gitattributes`： ```gitattributes *.cs text eol=lf *.asmdef text eol=lf *.asmref text eol=lf *.unity text eol=lf merge=unityyamlmerge *.prefab text eol=lf merge=unityyamlmerge *.asset text eol=lf merge=unityyamlmerge *.meta text eol=lf merge=unityyamlmerge *.controller text eol=lf merge=unityyamlmerge *.anim text eol=lf merge=unityyamlmerge *.mat text eol=lf merge=unityyamlmerge *.psd filter=lfs diff=lfs merge=lfs -text *.fbx filter=lfs diff=lfs merge=lfs -text *.blend filter=lfs diff=lfs merge=lfs -text *.png filter=lfs diff=lfs merge=lfs -text *.tga filter=lfs diff=lfs merge=lfs -text *.wav filter=lfs diff=lfs merge=lfs -text *.mp3 filter=lfs diff=lfs merge=lfs -text *.mp4 filter=lfs diff=lfs merge=lfs -text *.mov filter=lfs diff=lfs merge=lfs -text ``` --- # 5. Gitea Actions：建议用专门 Unity runner，不要和 Gitea 服务混跑 Gitea Actions 需要 act runner 执行任务，Gitea 官方 quick start 明确建议 runner 跑在和 Gitea instance 分开的机器上，避免消耗过多资源影响 Gitea 本体。Unity CI 会吃 CPU、内存、磁盘 IO、Library cache 和许可证，所以这条对 Unity 项目尤其重要。([docs.gitea.com](https://docs.gitea.com/1.24/usage/actions/quickstart)) Gitea runner 注册时，不要用 `localhost` 或 `127.0.0.1` 作为 instance 地址。Gitea 文档特别提醒，runner 和 job containers 会连接这个地址，使用 loopback 地址通常是坏主意，LAN 地址通常才是正确选择。([docs.gitea.com](https://docs.gitea.com/1.24/usage/actions/quickstart)) 建议 runner 标签按 Unity 版本区分，例如： ```bash ./act_runner register \ --no-interactive \ --instance "http://gitea.lan:3000" \ --token "$GITEA_RUNNER_TOKEN" \ --name "unity-6000-2-runner-01" \ --labels "unity-6000-2,self-hosted" ``` Gitea act runner 可以 Docker 容器模式或 host 模式运行；官方推荐 Docker 更安全、更好管理，但也说明可以直接在 host 跑。Unity Editor + license + platform modules 往往更适合固定 host runner。注意：如果把 runner 用户加入 docker group，Gitea 文档提醒这实际上给了该用户 root 级别系统权限，所以 runner 机器应该隔离，不要和代码仓库主服务混在一起。([docs.gitea.com](https://docs.gitea.com/usage/actions/act-runner)) --- # 6. Gitea 工作流文件建议放 `.gitea/workflows/` Gitea 文档说明 workflow YAML 放在仓库的 `.gitea/workflows/` 目录，例如 `.gitea/workflows/demo.yaml`；Gitea Actions 设计上尽可能兼容 GitHub Actions，但官方也提醒某些 actions 在 SHA256 仓库或 Gitea 运行在 subpath 时可能不正常，包括 `actions/checkout`。([docs.gitea.com](https://docs.gitea.com/1.24/usage/actions/quickstart)) 建议最小 CI： ```yaml # .gitea/workflows/unity-validate.yaml name: Unity Validate on: pull_request: push: branches: - main - develop jobs: unity-fast: runs-on: unity-6000-2 steps: - name: Checkout uses: actions/checkout@v4 with: lfs: true - name: Ensure LFS files are present run: | git lfs install git lfs pull - name: Validate Unity version pin run: | cat ProjectSettings/ProjectVersion.txt "$UNITY_PATH" -version - name: Run fast validation run: | chmod +x tools/*.sh ./tools/validate-fast.sh unity-full: runs-on: unity-6000-2 needs: unity-fast if: gitea.event_name == 'pull_request' steps: - name: Checkout uses: actions/checkout@v4 with: lfs: true - name: Ensure LFS files are present run: | git lfs install git lfs pull - name: Run full validation run: | chmod +x tools/*.sh ./tools/validate-full.sh ``` 如果你的 Gitea 是纯内网、不能访问 GitHub，那么 `actions/checkout@v4` 需要镜像到本地，或者换成你们内部可访问的 checkout action。Gitea 官方示例使用 `actions/checkout@v4`，但也明确说“尽可能兼容”，不是所有场景都保证无差异。([docs.gitea.com](https://docs.gitea.com/1.24/usage/actions/quickstart)) --- # 7. Gitea 分支保护要作为 AI Agent 的硬护栏 这点我会比前一版说得更强：如果用 Gitea，本地 pre-commit 不够，必须用 Gitea 的 protected branches。 Gitea 官方文档说明 protected branches 可以对 push、merge、review、status check 做策略限制；还可以禁用直接 push、禁用 force push、要求审批、dismiss stale approvals、阻止 rejected review 的 PR 合并、要求 PR 分支保持最新、要求状态检查成功后才能合并。([docs.gitea.com](https://docs.gitea.com/1.26/usage/access-control/protected-branches)) 建议 `main` / `release/*`： ```plaintext Protected branch: main Push: - Disable push Force push: - Disable force push Pull request: - Required approvals: 1 or 2 - Dismiss stale approvals: enabled - Block merge on rejected reviews: enabled - Block merge if pull request is outdated: enabled - Administrators must follow branch protection rules: enabled Status checks: - Enable status check - Required patterns: - actions/unity-fast - actions/unity-full ``` Gitea 支持 status check patterns，要求匹配的 CI context 在 PR head commit 上成功后才能合并。这个适合把 `validate-fast`、`validate-full` 变成硬门槛。([docs.gitea.com](https://docs.gitea.com/1.26/usage/access-control/protected-branches)) 注意：Gitea 的 protected file patterns 是“阻止修改敏感文件”，不是“要求额外审核”。所以不要轻易把 `ProjectSettings/**`、`Packages/**` 全部加成 protected file pattern，否则以后合法改构建设置也合不了。更好的做法是：这些文件改动时由 PR 模板和 reviewer 检查，同时用 CI 状态检查拦截。Gitea 文档说明 protected file patterns 会阻止触碰这些文件的 commit 或 merge。([docs.gitea.com](https://docs.gitea.com/1.26/usage/access-control/protected-branches)) --- # 8. asmdef 建议是正确的，但要补两条官方依据 Unity 官方 asmdef 文档确认：`.asmdef` 会把所在文件夹及子文件夹脚本编译进独立 assembly，除非子文件夹有自己的 asmdef 或 asmref；不同 assembly 之间依赖必须显式声明引用；循环 assembly 引用不允许。([docs.unity.cn](https://docs.unity.cn/Manual/ScriptCompilationAssemblyDefinitionFiles.html)) 所以原文里“用 asmdef 控制爆炸半径”的建议是成立的。但我建议补两条： ### 第一，Editor assembly 不一定非要所有脚本放顶层 `Editor/` Unity 官方说明，Editor assembly 允许把 Editor 脚本放在项目任意位置，不只限于顶层 `Editor` 文件夹；做法是创建平台特定 assembly，并只包含 Editor 平台。([docs.unity.cn](https://docs.unity.cn/6000.0/Documentation/Manual/assembly-definitions-creating.html)) 建议： ```plaintext Assets/_Project/Scripts/Runtime/Core/Project.Core.asmdef Assets/_Project/Scripts/Runtime/Gameplay/Project.Gameplay.asmdef Assets/_Project/Scripts/Runtime/UI/Project.UI.asmdef Assets/_Project/Scripts/Editor/Project.Editor.asmdef ``` `Project.Editor.asmdef`： ```json { "name": "Project.Editor", "rootNamespace": "Project.Editor", "includePlatforms": ["Editor"], "references": [ "Project.Core", "Project.Gameplay", "Project.UI" ] } ``` ### 第二，测试 assembly 要按 Unity Test Framework 的规则配置 Unity 官方说明 test assembly 可以把测试代码和 shipped application code 分开；并说明 Unity 会通过 `nunit.framework.dll`、`UnityEngine.TestRunner`、`UnityEditor.TestRunner` 等引用识别测试 assembly。([docs.unity.cn](https://docs.unity.cn/6000.0/Documentation/Manual/assembly-definitions-creating.html)) 所以建议文档里明确： ```plaintext Project.Tests.EditMode.asmdef Project.Tests.PlayMode.asmdef ``` 并在 `docs/testing.md` 写清楚每个 test asmdef 引用哪些 runtime assembly。 --- # 9. 序列化迁移协议要加强，这是官方文档支持的高风险点 Unity 官方序列化规则说明，Unity serializer 直接处理字段，不是属性；字段通常需要是 public 或 `[SerializeField]`，且不能是 static、const、readonly，还必须是 Unity 支持的类型。([docs.unity.cn](https://docs.unity.cn/6000.1/Documentation/Manual/script-serialization-rules.html)) 所以 AI Agent 的 Unity 规则里应该明确： ```markdown ## Serialization Rules - Prefer `[SerializeField] private` fields for Inspector wiring. - Do not rename serialized fields casually. - Do not convert serialized fields into properties unless migration is intentional. - Do not make serialized fields `static`, `const`, or `readonly`. - Do not assume properties are serialized. ``` 字段重命名必须用 `[FormerlySerializedAs]`。Unity 官方 API 文档明确说明这个 attribute 用于 rename 字段而不丢失 serialized value。([docs.unity.cn](https://docs.unity.cn/ScriptReference/Serialization.FormerlySerializedAsAttribute.html)) ```csharp using UnityEngine; using UnityEngine.Serialization; namespace Project.Gameplay { public sealed class PlayerMovement : MonoBehaviour { [FormerlySerializedAs("moveSpeed")] [SerializeField] private float movementSpeed = 5f; } } ``` `[SerializeReference]` 要列为高风险。Unity 官方文档说明它会让 Unity 按 reference 而不是 value 序列化，支持多态、null、循环图等，但也有额外开销；文档还说明 managed reference 会记录 ID、fully qualified class name 和字段值。因此类名、命名空间、程序集移动都会更敏感。([docs.unity.cn](https://docs.unity.cn/Documentation/ScriptReference/SerializeReference.html)) 建议在 `AGENTS.md` 加： ```markdown ## High-Risk Serialization Changes Treat these as high risk: - Renaming serialized fields - Moving MonoBehaviour or ScriptableObject classes between namespaces - Moving classes between asmdefs - Changing `[SerializeReference]` type names - Changing ScriptableObject schema - Changing prefab or scene serialized data Required: - Add `[FormerlySerializedAs]` for field renames. - Document affected prefabs, scenes, ScriptableObjects, and assets. - Run `./tools/validate-full.sh`. ``` --- # 10. `AGENTS.md` 里要加入 Unity 6.2 + Gitea 专属规则 我建议你的 Unity 版文章里把 `AGENTS.md` 改成更贴近实际环境： ```markdown # Project Unity Agent Rules ## Environment - Unity version is pinned by `ProjectSettings/ProjectVersion.txt`. - Do not upgrade Unity version or packages unless explicitly asked. - Repository is hosted on self-managed Gitea. - CI runs through Gitea Actions on dedicated Unity runners. - Large binary assets are stored with Git LFS. ## Required Validation For normal C# and editor-tooling changes: ./tools/validate-fast.sh For scene, prefab, ScriptableObject, Addressables, ProjectSettings, Packages, Build Profiles, input, animation, or asmdef changes: ./tools/validate-full.sh ## Version Control - Commit `.meta` files. - Do not manually edit `.meta`. - Do not move or rename Unity assets outside the Editor unless explicitly required. - Do not modify `ProjectSettings/`, `Packages/`, or Build Profiles unless the task requires it. - Do not add large binary files outside Git LFS tracking. ## Test Command Rule When running Unity Test Framework from command line, use `-runTests -batchmode`. Do not add normal `-quit` to test commands. ## Build Profile Rule Build Profiles are build configuration assets. Changing them is high risk and must be mentioned in the final response. ## Final Response Always state: - Files changed - Asset, prefab, scene, ScriptableObject, asmdef, Build Profile, or ProjectSettings impact - Validation command run - Whether Unity/Gitea CI still needs to verify anything ``` 这版比原文章更准确，尤其是测试命令和 Gitea CI 部分。 --- # 11. 我会调整原文中的落地优先级 ## P0：立即做 1. 锁定 Unity 精确版本，不写模糊 `6.2+` 2. Gitea 启用 LFS 3. 仓库提交 `.gitattributes` 4. Unity 设置 Visible Meta Files 5. Unity 设置 Force Text 6. 配置 UnityYAMLMerge 到开发机和 runner 7. 建立 `tools/validate-fast.sh` 8. 建立 Gitea Actions runner，独立机器运行 9. Gitea `main` 分支保护，禁止直接 push 10. CI 要求 `unity-fast` 状态检查通过 ## P1：一周内做 1. `validate-full.sh` 2. PlayMode smoke tests 3. Build Profile 验证命令 4. asmdef 依赖检查 5. 序列化字段迁移协议 6. PR 模板加入 Unity 风险清单 7. Gitea 要求 PR approval 和 stale approval dismiss ## P2：项目变大后做 1. Addressables Analyze / content build 验证 2. Dedicated build runner 3. Unity Accelerator 或共享 Library cache 方案 4. 资源体积预算 5. 自动生成 project index 给 Agent 读取 6. AI cleanup 先 report-only --- ## 最后一句总结 根据 Unity 官方文档和 Gitea 官方文档校准后，我会把你文章里的建议从： > “给 Agent 写规则” 升级成： > **Unity 6.2+ 项目在 Gitea 上通过 LFS、UnityYAMLMerge、asmdef、分层验证脚本、Gitea Actions、分支保护和序列化迁移协议，给 Agent 设置不能绕过的工程护栏。** 最重要的修正是这三条： 1. **Unity Test Framework 命令不要加普通 `-quit`。** 2. **Gitea 本地部署必须先把 LFS、runner、分支保护、状态检查打通。** 3. **Unity 6.2+ 要把 Build Profile 当成高风险配置资产纳入 Agent 规则。** ]]> Wed, 20 May 2026 17:50:42 GMT https://reader-feed.pages.dev/posts/bfc3744a0d-unity%E5%B7%A5%E7%A8%8B%E4%BC%98%E5%8C%96%E5%BB%BA%E8%AE%AE.md obsidian:460a264a23:workflow/project/unity工程优化建议2.md 基于证据复核后的 Unity 文档改进建议 在搜索 Unity 6.2 官方文档、Claude Code/AGENTS.md 现状、Gitea Actions 实践、game-ci 等关键来源后，下面是**基于事实而非推测**的修订建议。重点考虑你提到的 **Unity 6.2+** 和 **自建 Gitea** 这两个约束。 Build Settings`，这是 2022.3 LTS 的旧术语。 - Unity 6 引入了 Build Profiles，帮助跨平台和环境定义并复用构建配置。 - 每个 Build Profile 是一组配置设置，通过 `File > Build Profiles` 访问。 - Unity 将每个 Build Profile 保存为 `.asset` 文件（例如 `Assets/Settings/Build Profiles/AndroidDevelopment.asset`），并应提交到版本控制。 **建议**： - `docs/build-and-release.md` 必须围绕 Build Profile `.asset` 文件设计，而不是过去的 BuildSettings.asset。 - 把 Build Profile 资产明确加入 AGENTS.md 的"不要随意修改"清单——它们直接决定 CI 产物。 - Unity 6.2 还为 Web、Android、iOS、macOS、Windows 提供了 每个 Build Profile 的 Diagnostics 设置覆盖，需要在 AGENTS.md 提一下"不要在没有 release owner 同意下开关 Diagnostics"。 ### 2. Unity Test Framework 已成为核心包 文档里写"Add or update EditMode tests"和"PlayMode tests"暗示两者必须分开。Unity 6.2 已经不需要： - Unity Test Framework 已成为核心包，其用户手册已整合到 Unity 核心手册。 - UTF 2.0 通过引入 `RequiresPlayModeAttribute` 移除了必须把 EditMode 和 PlayMode 测试放在不同 assembly 的要求；Editor-only 测试 assembly 现在可以包含会运行在 Play Mode 的测试（带 `[RequiresPlayMode]`），平台特定 assembly 也可用 `[RequiresPlayMode(False)]` 让测试不在 Play Mode 运行。 - UTF 2.0 还支持用 .NET Task 异步编程模型编写异步测试。 **建议**： - 简化目录结构——不必再强制 `Tests/EditMode/` 和 `Tests/PlayMode/` 两个 asmdef。可以保留一个 `Project.Tests` asmdef，用属性区分测试模式。 - AGENTS.md 里建议用 `[RequiresPlayMode]` 而不是机械地把测试塞到 PlayMode asmdef。 ### 3. 关于异步：Awaitable 已是官方推荐，但 UniTask 仍更完整 文档里只是泛泛地说"Prefer cancellation-aware async flows when using UniTask or Tasks"。Unity 6 的现实更具体： - Unity 6 引入了 awaitable 类型 `Awaitable`，可以认为是 UniTask 的子集，并且 Awaitable 的设计受 UniTask 影响。 - 在 Unity 2023.1 及更新版本中，`await UniTask.WaitForEndOfFrame()` 不再需要 MonoBehaviour，因为它使用 `UnityEngine.Awaitable.EndOfFrameAsync`。 - Unity 内置的 Awaitable 很方便（尤其对想避免外部依赖的库），但 UniTask 仍是更完整、面向生产的工具包：frame-aware delays、WhenAll/WhenAny、细粒度 PlayerLoopTiming、一等公民的 CancellationToken 支持；对应用/游戏，UniTask 仍是不错的默认选择。 **建议**：在 `docs/conventions.md` 给出明确指引： - 项目内部异步代码：用 `Awaitable`（零依赖、官方）。 - 高频/对 GC 敏感的代码、需要 WhenAll/WhenAny 的：用 UniTask。 - 不要让代理在同一代码路径混用 `Task` 和 `UniTask`，否则容易产生隐式同步上下文切换。 --- ## 三、关于 Gitea CI 的修正（最大改动） 我之前给的 GitHub Actions YAML 直接放到你的 Gitea 上会踩坑。事实是： ### 1. Gitea Actions 与 GitHub Actions 兼容但有限制 - Gitea Actions 直接在 Gitea UI 中提供 GitHub Actions 兼容的 CI/CD，但 GitHub Marketplace 的第三方 actions 不能直接用——`actions/checkout`、`actions/setup-python`、`actions/cache` 等流行 action 在 gitea.com 有镜像并可正常工作；act_runner 首次从互联网获取并本地缓存。 - Gitea Actions 基于 nektos/act，act_runner 通过 spawn act 实例运行 workflow；act 试图尽可能兼容 GitHub Actions，但并非完美匹配。 **这意味着**： - `game-ci/unity-test-runner@v4` 和 `game-ci/unity-builder@v4` **在 Gitea Actions 上不一定开箱即用**——它们依赖 GitHub Marketplace。 - `anthropics/claude-code-action@v1`（我上一轮推荐的）同样不能直接在 Gitea 跑。 ### 2. 自建 Gitea 推荐走 GameCI 的 GitLab 路线（Docker 镜像直接调用） GameCI 提供两套体系：GitHub Actions 和 GitLab CI。前者依赖 marketplace，后者依赖 Docker 镜像。**对自建 Gitea，应该参考 GitLab 路线**： - GameCI 的 unity3d-gitlab-ci-example 使用 game-ci 发布的 unity3d Docker 镜像。 - 典型调用方式：用 `unityci/editor:-base-` 镜像，传入 `UNITY_EMAIL`、`UNITY_PASSWORD`、`UNITY_SERIAL` 环境变量，然后通过 `xvfb-run` 调用 `unity-editor -batchmode -nographics`。 **建议的 Gitea Workflow 雏形**（`.gitea/workflows/unity-validate.yml`）： ```yaml name: Unity Validate on: pull_request: workflow_dispatch: jobs: test: runs-on: ubuntu-latest container: image: unityci/editor:6000.2.16f1-base-3 # Unity 6.2 LTS image options: --user root steps: - uses: actions/checkout@v4 with: lfs: true - name: Activate Unity license run: | mkdir -p /root/.cache/unity3d /root/.local/share/unity3d/Unity/ echo "$UNITY_LICENSE" | base64 -d > /root/.local/share/unity3d/Unity/Unity_lic.ulf env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} - name: Run EditMode tests run: | xvfb-run --auto-servernum --server-args='-screen 0 640x480x24' \ unity-editor -batchmode -nographics -logFile /dev/stdout -quit \ -projectPath . -runTests -testPlatform EditMode \ -testResults Logs/editmode-results.xml - name: Run project validation run: | xvfb-run --auto-servernum --server-args='-screen 0 640x480x24' \ unity-editor -batchmode -nographics -logFile /dev/stdout -quit \ -projectPath . \ -executeMethod Project.Editor.Validation.ProjectValidationCommand.RunAll ``` 注意几点： - **不要**用 `game-ci/unity-test-runner@v4`——它会去 GitHub marketplace 拉。 - act_runner 要用 **DinD 或 Docker 模式**，而且要给 runner 配置足够大的镜像（Unity 镜像超 10GB）。Gitea act_runner 默认是 `ubuntu-22.04:docker://node:16-bullseye`，如果默认镜像不够用，可改为 `ubuntu-22.04:docker://<你需要的镜像>`。 - Unity 个人版/专业版的 license 流程不同：Unity Personal License 在 `.ulf` 中产生一个 serial token，需要先在本机 Unity Hub 激活然后定位 `.ulf` 文件。 ### 3. CI 缓存策略要本地化 `actions/cache@v4` 在 Gitea 上是默认禁用的：act_runner 配置文件里 `cache.enabled` 默认是 `false`，需要在配置中启用 cache server 才能使用 `actions/cache`。 - 在 act_runner 的 `config.yaml` 里把 `cache.enabled` 设为 `true`。 - 缓存 `Library/` 是 Unity CI 的关键——首次 import 一个中等项目就要 10–20 分钟，缓存命中后能降到 1–2 分钟。 ### 4. Claude Code 自动化在 Gitea 上的路径 我之前推荐的 `anthropics/claude-code-action` 是 GitHub Action。要在 Gitea 上做"垃圾回收"，更现实的方案是： - 在 act_runner 容器里直接安装 `claude` CLI（npm install @anthropic-ai/claude-code）。 - 用 cron 触发 workflow，workflow 里 shell 调用 `claude -p "..."`。 不要假设 `claude-code-action@v1` 可用，除非你愿意自己 fork 并镜像它的依赖。 --- ## 四、Roslyn Analyzer 落地的精确步骤 上一轮我笼统地建议"引入 Microsoft.Unity.Analyzers"。实际在 Unity 里安装方式与 .NET 项目**完全不同**： - Unity 不支持通过 NuGet 直接安装 Roslyn Analyzers。需要把 NuGet 包当作 `.zip` 下载、解压，找到 `.dll`。 - 把 `.dll` 拖入 Unity 后，需要在 Plugin Inspector 关闭 Any Platform、关闭 Editor 和 Standalone 平台，然后在 Asset Labels 创建并分配一个名为 `RoslynAnalyzer` 的标签（大小写必须完全匹配）。 - Unity 识别 `RoslynAnalyzer` 标签并把带此标签的资产作为 Roslyn Analyzer 或 source generator 处理。 - 从 Visual Studio Tools for Unity 4.3.2.0 起，Microsoft.Unity.Analyzers 会自动包含在 Unity 生成的所有 csproj 中——所以**在 VS/VS Code 里用 Game Development with Unity workload 时不需要手动装，但 CI 上跑 `dotnet format` 时要装**。 **建议补一份 SKILL**：`.agents/skills/unity-roslyn-analyzers/SKILL.md`，写清这套 "下载 → 拖入 → 关闭平台 → 加 `RoslynAnalyzer` 标签"的流程，避免代理用 `dotnet add package` 这种在 Unity 里无效的指令。 --- ## 五、.editorconfig 与 dotnet format 的实际限制 上一轮我说"加 `.editorconfig` 就能让代理统一格式"。实际有坑： - Unity 官方推荐用 `.editorconfig` 而不是 VS 设置导入导出，因为它跨 IDE 共享且能进版本控制。 - 在项目根目录创建 `.editorconfig` 文件并填入想要的配置——Unity 6 生成的 csproj 会自动应用。 - **但**：Unity 项目里每次新增/删除/重命名脚本都会重新生成 sln 和 csproj，覆盖手动改动。所以不能把 editorconfig 引用塞进 csproj 自定义部分，必须放在仓库根目录，让 Unity 重新生成时自动 pick up。 - `dotnet format` 在 Unity 项目上跑要先生成 sln/csproj，且 `dotnet format` 可能会 restore、编译并运行指定项目/方案中的 analyzer，只应在受信任的代码上调用。 **建议**的 pre-commit 调整： ```yaml - repo: local hooks: - id: dotnet-format-whitespace name: dotnet format whitespace # 使用 whitespace 子命令避免触发完整 analyzer 链 entry: bash -c 'dotnet format whitespace --verify-no-changes --include "$(git diff --cached --name-only --diff-filter=ACM | grep "\.cs$" | tr "\n" " ")" || true' language: system files: "\\.cs$" pass_filenames: false ``` 注意用 `dotnet format whitespace` 子命令而不是完整 `dotnet format`：`dotnet format whitespace` 只运行与空格格式化相关的规则，速度快、不依赖 analyzer 是否安装。 --- ## 六、UnityYAMLMerge 路径在 Unity 6 的实际位置 我之前给的路径是 `2022.3.0f1`。Unity 6.2 通过 Unity Hub 安装时的真实路径是： - Windows: `C:\Program Files\Unity\Hub\Editor\6000.2.xfx\Editor\Data\Tools\UnityYAMLMerge.exe` - macOS: `/Applications/Unity/Hub/Editor/6000.2.xfx/Unity.app/Contents/Tools/UnityYAMLMerge` Unity 6.0 官方文档的 SmartMerge 页面确认：要自定义 UnityYAMLMerge 合并行为，配置 `mergerules.txt` 文件，该文件在 Unity 安装的 Editor/Data/Tools 文件夹中。**这与文档里的写法一致**，但需要把示例版本号从 `2022.3.0f1` 换成 `6000.2.x`。 另外，官方推荐的 git 配置使用 `[mergetool "unityyamlmerge"] trustExitCode = false` 加上 `cmd = '' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED"`——你文档里的写法是对的，无需改动。 --- ## 七、Skills 的当前标准 Skills 部分我上一轮没指出来： - Anthropic 已在 2025 年 12 月 18 日把 Agent Skills 发布为跨平台便携性的开放标准。 - Skill 最简形式是一个包含 SKILL.md 文件的目录；该文件必须以 YAML frontmatter 开头，包含必需的 name 和 description 元数据；启动时 agent 把每个 skill 的 name 和 description 预加载到系统提示，这是渐进披露的第一层。 - Agent Skills 在 Claude.ai、Claude Code、Claude Agent SDK 和 Claude Developer Platform 上都已支持。 你当前的 SKILL.md 模板**已经符合规范**（有 frontmatter、有 name/description）。但建议在 AGENTS.md 里把 skill 路径写清楚：Cursor 用 `.cursor/rules/`、Codex 用项目根的 AGENTS.md + 嵌套 AGENTS.md，**Skills 主要是 Claude Code 的能力**，不要假设其他工具能直接读 `.agents/skills/`。 --- ## 八、最终落地优先级（按 ROI 排序） 1. **砍掉 AGENTS.md 80% 的内容**——保留项目独有约束（asmdef 边界、`[FormerlySerializedAs]`、入口脚本、不可碰目录），其余下放到 `docs/` 让 agent 按需阅读，并新增 symlink `ln -s AGENTS.md CLAUDE.md`。 2. **重写 CI 章节为 Gitea 方案**：删除所有 `game-ci/*@v4` 与 `anthropics/claude-code-action`，改用 `unityci/editor` 容器 + 直接 shell 调用 + DinD runner。 3. **更新 Unity 6.2 术语**：Build Settings → Build Profiles；Tests asmdef 简化为单一 asmdef + `[RequiresPlayMode]`；UnityYAMLMerge 路径改为 Hub 路径。 4. **新增 .editorconfig + Roslyn Analyzer Skill**：用确定性工具替代 AGENTS.md 中的风格规则，写清楚 Unity 特有的"下载 dll + RoslynAnalyzer 标签"安装步骤。 5. **明确 Awaitable vs UniTask 选型规则**：在 `docs/conventions.md` 给出场景化建议，而非笼统提一句。 修订完后，整份 Unity 文档会从"看起来全面"变成"agent 在 Gitea + Unity 6.2 上能真的跑起来"。 ]]> Wed, 20 May 2026 08:30:36 GMT https://reader-feed.pages.dev/posts/460a264a23-unity%E5%B7%A5%E7%A8%8B%E4%BC%98%E5%8C%96%E5%BB%BA%E8%AE%AE2.md obsidian:fec8cf414b:Clippings/How to Become a Hermes Agent Operator.md How to Become a Hermes Agent Operator learn how to operate and master Hermes Agent. set up the agent control room template, configure specialist agents, and grow from one agent t... 5月13日 > > Hermes Agent changed how I work it's the highest leverage agent framework you can set up right now what makes it different: > it routes tasks to the right model based on complexity and cost > learns your voice and preferences over time > handles context switching without if you have used claude code or openclaw, hermes is the same shape with a different philosophy. > hermes is rails. opinionated defaults, batteries included, productive on day one with minimal setup, the agent does more thinking for you. > openclaw is linux. primitives, guarantees, explicit control, the agent does exactly what you told it to and nothing more. both are valid. I run hermes because the bundled defaults compound. every project I start with hermes is one where the agent already knows how to do 100+ things before I write a line of configuration. that head start is worth it for me. I´ve also noticed that hermes doesn´t have where near the same issue with gateway disconnecting or bugging. proof is in the numbers Nous Research just hit: - **#1 on OpenRouter** for global token usage (out of every model and framework on the platform) - **150,000 github stars** on the hermes repo - **123 bundled skills** before the agent writes one of its own - **70+ built-in tools** in the gateway, plus 300+ models through one subscription - **6 deployment targets**: local, docker, ssh, daytona, singularity, modal - **20+ messaging surfaces**: telegram, discord, slack, email, voice if you are an AI marketer and you have not started running hermes yet, you are leaving compounding capability on the table every week. ## how it works (the reader-friendly version) every hermes agent has three things. **a brain.** memory lives at ~/.hermes/memories/. two files, MEMORY.md and USER.md, inject at session start. your voice rubric, your brand notes, your customer language, last week's corrections, all of it loads before the first prompt. sessions are stored in sqlite, recall across sessions is full-text searchable. **a personality.** soul.md is where the vibe lives. concise. sarcastic. blunt. formal. fast or thoughtful. you can spin up six agents and give each one a different soul, same brain underneath. one is your outbound rep with a closer's energy. another is your researcher who likes long sentences. another is your assistant who keeps everything short. ![图像](https://pbs.twimg.com/media/HIYD1qSW8AAVLf1?format=jpg&name=large) ## a skillset. 123 skills out of the box: github PRs, obsidian, google workspace, linear, notion, typefully, perplexity, deep research, browser control, web scraping, vision, voice, scheduling. and the closed learning loop: as the agent works, it writes new skills along the way. your own skills library grows on top of the 123 without you having to write any of them. then there is what the agent can talk to. - the **tool gateway**: one subscription, 300+ models, plus web scraping and browser automation built in - **MCP integration**: any external service that speaks Model Context Protocol becomes a tool your agent can use - **20+ messaging surfaces**: telegram, discord, slack, email, voice, plus the CLI itself ![图像](https://pbs.twimg.com/media/HIX_LFwXgAEmDW7?format=jpg&name=large) and where the agent can live. - your laptop (local) - a docker container (isolated, portable, the way I run mine) - an ssh session on a VPS (so it runs even when your laptop is closed) - daytona, singularity, modal (serverless if you don't want to manage infrastructure) the closed learning loop is what makes this different from a smart chatbot. the agent watches itself work, writes new skills as it learns the shape of your work, refines its memory periodically, and recalls past context across sessions using a mix of full-text search and LLM summarization. you do not have to re-teach it next week. > the rule I tell people new to hermes is this: do not try to write your own skills on day one. run real work, let the agent watch, and let the harness write the skills. you build a custom skill library faster by working than by writing prompts. ## what I'm running on hermes I am an AI marketer, not a coder. most of what I run on hermes is marketing infrastructure with the occasional internal tool. here is the actual list: - **a personal assistant** that handles business and private, lives in telegram, flags the four emails worth reading every morning, schedules my reminders, summarizes meetings I missed - **a marketing workflow prototyping bench** where I test new flows (lead magnet, ad creative review, content sprint) against real work for 2-3 runs before promoting them - **specialized marketing agents**: SEO, outbound / BD, design review, content writing, each one with its own soul and its own scope - **a company brain** that monitors slack, chats, emails, transcripts, voice memos, and makes all of it queryable. when I ask "what did we say to that client about pricing last month" I get the answer in 3 seconds instead of 30 minutes of digging - **an SEO agent** that runs the full pipeline from keyword seed to published article in one docker container, 21 steps, no human in the middle until the final review - **a content distribution agent** that takes a piece of long form (this article, for example) and atomizes it across LinkedIn, X, Threads, with platform-specific hooks - **an orchestrator agent** that does not produce work itself, just routes requests to the right specialist based on what I'm asking for the blueprint I posted that summarized it: > 5月13日 > > the org chart for my Hermes Agent company four layers, all isolated docker containers on one vps: 1. company brain - vision, brand, customers, products. the context every other layer inherits 2. orchestrator hermes agent - reads the company brain, picks the right department, the SEO agent in particular is worth zooming in on, because it is the one I have shipped publicly and the one that maps cleanest to the architecture in the rest of this article. five layers, all inside one docker container, 21 steps from keyword seed to published article. the 21 steps look like this in the terminal: ```markdown [research + ideate] 01 keyword seed 02 serp snapshot 03 competitor extraction 04 intent + format analysis 05 content + visual gap 06 internal validation 07 external validation [production] 08 angle + positioning brief 09 visual strategy brief 10 outline 11 draft 12 image gen 13 flowchart gen 14 visual qa 15 article qa [distribution] 16 publish prep 17 schema 18 internal linking 19 syndication 20 analytics setup 21 monitoring ``` the layers above this pipeline: 1. **company brain** at the top: vision, brand, audience, products. every agent reads from this 2. **orchestrator hermes agent**: takes the topic or keyword seed and routes it to the seo agent 3. **seo brain**: ranking playbook, voice rules, content formats, visual style guide, success criteria per format. all seo-specific context lives here 4. **three sub-agents** inside the SEO agent, each one handling a phase: 5. **research + ideate**: keyword seed, serp snapshot, competitor extraction, intent and format analysis, content and visual gap, internal and external validation 6. **production**: angle and positioning brief, visual strategy brief, outline, draft, image gen, flowchart gen, visual and article qa 7. **distribution**: publish prep, schema, internal linking, syndication, analytics, monitoring 8. **one docker container** holds all three sub-agents. they share env, memory, and tools. sub-profiles switch context per phase. one process, one filesystem, one set of credentials. why one container instead of three: seo work is sequential. research feeds the brief, the brief feeds production, production feeds distribution. every step needs memory of what was decided upstream. splitting into three containers means shuttling state across boundaries, which gets expensive and breaks the chain. every other specialized agent in the company runs on the same template. clone the SEO agent template, swap the brain (seo brain → outbound brain, or → design brain, or → support brain), and you have a new agent for any function with the same five-layer shape. > 5月15日 > > how my hermes seo agent works in the org chart it runs the full pipeline from keyword seed to published article, 21 steps, all inside one docker container the structure: LAYER 1: company brain shared context: vision, brand, audience, products. every agent reads from this > the layers are not decoration. they are the reason the agent does not lose context as the work gets specialized. the company brain stays stable while the worker iterates. the brain layers make the worker disposable. I also hosted Nous Research at our [@EspressioAI](https://x.com/@EspressioAI) HQ in Lisbon for a Hermes Agent evening recently. [@yeahfortommy](https://x.com/@yeahfortommy) from Nous ran a Q&A, Simao from noticed .so showed an agent harness with autoresearch, and I walked through how we are using hermes for growth at Espressio. > 4月27日 > > we are hosting @NousResearch for a Hermes Agent evening at the Espressio HQ tomorrow @touchgrassklub is organizing in collabration with Talent Protocol Here´s the agenda for the evening: > I´ll start by talking about using Hermes Agent for growth, what we're shipping at if you are in Lisbon and want to come to the next one, I will post when it's scheduled. ## from one agent to a full fleet before the levels, the mental model. the setup has four parts: - **you** are the operator. you have direct access to every part of the system. - the **agent control room** is the side control plane. it is not an agent you chat through. it is a folder at /root/vps-agents that documents and governs the whole fleet. you open it, edit it, inspect it, or ask claude, codex, or hermes to use it when you are managing the system. - the **hermes agents** are the workers. some are specialists (seo, dev, cmo, ops). one of them can optionally be an orchestrator. - the **agent task bus** is an optional handoff desk that sits between the orchestrator and the specialists. you only need it once you have an orchestrator in play. the whole thing looks like this: ```markdown ┌───────┐ │ YOU │ the operator └───┬───┘ │ ┌─────────────────────────────┼─────────────────────────────┐ │ │ │ control path orchestrated path direct path │ │ │ ▼ ▼ ▼ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │ AGENT CONTROL ROOM │ │ HERMES │ │ SPECIALIST AGENT │ │ /root/vps-agents │ │ ORCHESTRATOR │ │ │ │ │ │ (optional door) │ │ seo · dev · cmo · │ │ docs · rules · │ └─────────┬──────────┘ │ ops · life │ │ runbooks · env-map │ │ delegates │ │ │ · registry │ ▼ │ talk to it │ │ │ ┌────────────────────┐ │ directly, │ │ side control plane │ │ AGENT TASK BUS │ │ no routing │ │ no raw secrets │ │ /srv/agent-bus │ │ │ │ │ └─────────┬──────────┘ │ │ └────────────────────┘ │ │ │ │ routes │ │ └───────────────▶ │ │ │ └────────────────────┘ the agent control room governs every agent in this diagram. it is the single source of truth, and the place you go to manage the fleet, not the place you go to run work through it. ``` the storage split matters more than people think: ```markdown /root/vps-agents → control room: docs, rules, runbooks, architecture no raw secrets, ever /srv//data → live runtime: secrets, memory, skills, sessions, crons this is where each hermes agent lives ``` the control room contains the answers to questions like which agents exist, what they do, what ports they use, what credentials they reference, what each agent can and cannot do, and how to restart, debug, or rebuild any of them. the live runtime contains the actual workings. > the control room is the brain that defines the system. the live runtime is the body that runs it. you can rebuild the body from the brain. you cannot rebuild the brain from the body. inside the control room: ```markdown /root/vps-agents/ README.md CLAUDE.md agents/ / inventory.md docker.md env-map.md runbook.md backup.md shared/ security.md commands.md api-keys-sop.md orchestrator-and-fleet-skills.md ``` and inside each agent's runtime at /srv//data/: ```markdown .env config.yaml SOUL.md memories/ skills/ cron/ sessions/ logs/ state.db ``` ## three ways you interact ```markdown control path: you ──────► agent control room (add agents, rotate keys, update docs, debug setup) direct path: you ──────► hermes-seo-espressio (talk to a specialist directly, fastest) orchestrated path: you ──► hermes-orchestrator ──► task bus ──► specialists ──► you (one front door, routes and synthesizes multi-agent work) ``` - **control path** is the meta layer. used when adding agents, reviewing docs, checking ports, rotating keys, debugging setup. - **direct path** is the fastest. used when you already know which agent does the work. - **orchestrated path** is the synthesizer. used when you want one front door that routes and combines work across multiple specialists. ## level 1: one agent you have one hermes agent. that is it. the control room can still exist (recommended) but it only documents that one agent. ```text you → one hermes agent control room → documents that one agent ``` best for: initial setup, your personal hermes, root install documentation, simple docker migration. one agent, lived-in, with a personality you have tuned and a memory that has started to build. fill in SOUL.md with the voice you want, MEMORY.md with the stable facts about your business, and USER.md with the stable facts about you. connect it to telegram or discord so it lives where you do. start using it on real tasks. let it touch your tools. let it write its own skills along the way. MEMORY.md holds the stable facts (what your business is, who your customers are, what your products do). USER.md holds the stable facts about you (timezone, working hours, recurring projects, preferred output formats). both get refined every week as you correct the agent in real conversations. ## level 2: direct specialist agents you have multiple specialized agents, but you still talk to each one directly. no orchestrator yet. ```markdown you → hermes-life you → hermes-seo-espressio you → hermes-dev you → hermes-cmo ``` the control room documents all of them. best for: clear role separation, testing which agents are useful, avoiding premature orchestration, keeping credentials scoped per agent. > the trap to avoid here is reaching for an orchestrator before you have proven your specialists are useful. spin up two or three, run them directly, and only add an orchestrator when you find yourself wanting one front door. when to spin up a new agent vs stay with what you have: ```markdown needs its own credentials → new agent needs its own long-term memory → new agent ongoing repeated work that is a separate role → new agent otherwise stay with what you have ``` bad pattern: one mega-agent with every credential and every memory layer mashed together. you lose isolation, you lose the ability to revoke access cleanly, and the agent gets confused about which voice to use. ## level 3: orchestrator + specialists you add hermes-orchestrator as a front door. you can still talk directly to specialists, but the orchestrator can route work and synthesize results. ![图像](https://pbs.twimg.com/media/HIX8GPyWAAAQd4c?format=jpg&name=large) the orchestrator reads the control room to know which agents exist, what each one does, where task queues live, what requires approval, which actions are forbidden, and where docs and runbooks are. it does not need to ask you any of that, it reads it. best for: cross-functional work, delegation, summary and synthesis, one main interface for multi-agent workflows. > the orchestrator is the moment your setup stops being a collection of agents and starts being a team. it is also the moment where the control room earns its keep, because the orchestrator is only as good as the docs it reads. what a quick check-in on the fleet looks like from my laptop or phone: ```markdown $ ssh hermes welcome to hermes-vps-1. last login: thu may 15 09:14:22 hermes-vps-1 ~ $ cd vps-agents hermes-vps-1 ~/vps-agents $ docker ps --format \ "table {{.Names}}\t{{.Status}}\t{{.Image}}" NAMES STATUS IMAGE hermes-orchestrator up 14 hours hermes-runtime hermes-seo-espressio up 8 hours hermes-runtime hermes-cmo up 8 hours hermes-runtime hermes-outbound up 4 hours hermes-runtime hermes-life up 12 hours hermes-runtime hermes-vps-1 ~/vps-agents $ cat agents/hermes-seo-espressio/runbook.md # runbook: hermes-seo-espressio restart: docker compose restart hermes-seo-espressio logs: docker logs -f hermes-seo-espressio shell: docker exec -it hermes-seo-espressio bash ... ``` > 5月13日 > > my entire Hermes Agent setup is controlled from one folder on a VPS I can manage it from my laptop or phone in under 10 seconds, spin up isolated agents per project, and never lose context here's the full setup: > bash command "ssh hermes" auto-connects to the VPS > session ## level 4: automated agent team ame shape as level 3, but with recurring workflows and stronger automation. weekly seo reports run on cron. server health checks fire daily. backup verification runs without you asking. cross-agent business workflows kick off on schedule. best for: weekly seo reports, content operations, server health checks, backup verification, cross-agent business workflows. > level 4 is what a marketing department in your terminal looks like. it does not need you to start the day. it shows up to work on its own, files reports, checks itself, and only pings you for the decisions that need taste. ![图像](https://pbs.twimg.com/media/HIX8niUXgAE50SA?format=png&name=large) ## the control hierarchy one principle to keep in your head as you climb the levels. the control room is for config, docs, runbooks, and governance. it documents which agents exist, what they do, where they run, which credentials they reference, what each agent can and cannot do. it is the admin panel for the fleet, including the orchestrator. it is not where you go to do work. for work, you talk to the agents directly. either a specialist (when you know which agent owns the job) or the orchestrator (when you want one front door to route across specialists). ## the setup guide: point your agent at the repo now you understand the architecture. here is how you build it. I shipped a public template that holds the exact structure described above, plus the skills your agent needs to set it up for you. it lives at [github.com/shannhk/hermes-agent-control-room](https://github.com/shannhk/hermes-agent-control-room). ![图像](https://pbs.twimg.com/media/HIX9YQEWoAId_oy?format=jpg&name=large) you can clone it manually, but the point is that you do not have to. if you have claude code or codex on your laptop, the agents do most of the work after you hand over a Hetzner API key. the automated flow: ```markdown you ──► generate a Hetzner API key (5 min: sign up, generate a token, drop it in your .env) │ ▼ agent ──► create-vps skill spins up a Hetzner box, generates an SSH key, writes the alias to ~/.ssh/config so \`ssh hermes\` works │ ▼ agent ──► setup-control-room skill installs Node, Docker, Claude Code, Codex CLI, Hermes Agent, then clones the repo to the VPS at /root/agent-control-room │ ▼ you ──► finish interactive auth on the VPS (claude /login, codex, hermes) │ ▼ agent ──► agent-control-room skill registers your first hermes agent in the docs, fills in the runbook, sets up the env-map │ ▼ you are at level 1 with a documented agent ``` within ten to fifteen minutes you have: - a fresh Hetzner VPS with the right tooling installed - the control room cloned at /root/agent-control-room on the VPS - the bundled skills linked into ~/.claude/skills on the VPS - one hermes agent registered, runbook filled in, env-map written - an SSH alias on your laptop so ssh hermes connects instantly ## the prototype → production methodology most workflows do not start as production ones. they start messy. a flow that runs SEO research, drafts an article, schedules it in Typefully, and posts it to LinkedIn does not exist in your head fully formed. you discover it by running it. hermes is the prototyping environment for this. here is the four-step path I use to take any new marketing workflow from idea to autonomous deployment: 1. **prototype in hermes**. open your main hermes agent, describe what you want to happen, and let it try. it will get most of it wrong on the first run. that's fine. 2. **run it 2-3 times against real work**, correcting drift each time. the harness watches every correction and starts writing the skill as it learns the shape. by run three the agent is doing most of what you want without coaching. 3. **fine-tune in a dedicated workspace**. pull the workflow into a separate Claude Code workspace (or a fresh hermes agent if you prefer), tighten the prompts, lock the routing, add error handling, decide what should run on cron and what should be triggered. 4. **deploy to a VPS on a schedule**. once it survives a week of real runs without you babysitting it, push it to its own docker container on your VPS, set the cron, walk away. I learned this pattern after burning a few weekends trying to write production-ready agents from scratch. you cannot write a production agent from scratch. you have to grow one. hermes makes the growing part fast. ![图像](https://pbs.twimg.com/media/HIX9voFWQAAserb?format=png&name=large) 1. prototype in hermes 2. fine-tune in a dedicated workspace 3. deploy autonomous on a VPS ## the models I run on hermes hermes gives you the framework. the model underneath is your choice. through the tool gateway you can route to 300+ models from one subscription, switching per agent or per task. what I personally run today: - **claude opus 4.7** for the creative work: copywriting, voice, hook generation, content drafting, anything where taste and writing quality matter - **codex (gpt 5.5)** for the structured work: coding, planning, multi-step workflows, browser automation, scraping, anything where the steps need to be tight and the output predictable I run both. opus writes. codex builds and plans. hermes makes routing easy, you point each agent at the model that fits the work it does. if you can only run one, the answer depends on what kind of work your fleet is doing. heavy on content and copy? start with claude opus 4.7. heavy on infrastructure, automation, and engineering workflows? start with codex. you can always add the second model later through the same tool gateway. ## honest trade-offs I am not going to pretend hermes is perfect. three real trade-offs. **1\. the bundled defaults are also** [opinions.hermes](https://opinions.hermes/) ships with strong defaults for how memory works, how skills get written, how the agent uses tools. that is the whole pitch. but it also means if you want primitives with explicit control over every step, hermes will feel heavy. openclaw is the better fit for that taste. pick the tool that matches your philosophy. **2\. level 3 and 4 have a real learning curve.**docker, VPS, SSH, the control room folder structure, the orchestrator skills, none of this is "install and go." you should not jump to level 3 if you are not already running hermes at level 1 daily. **3\. the model still** [matters.hermes](https://matters.hermes/) is a framework that makes a good model great. it does not make a small model into a strategist. use the strongest models you can afford for the work that matters (your orchestrator, your strategy agent, your brain). drop to cheaper models for the work that does not (research scraping, draft generation, batch processing). > none of this is magic. it is a framework that pays back because the memory persists, the skills accumulate, and the agents stay scoped. apply it to the wrong-sized model and you get a confused team. apply it to the right one and you get a team. ## resources if you are starting today, here is what I would read in order. - **the official docs**: [hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs). start with the install guide, then read the skills page so you understand what ships out of the box - **the control room template (my repo)**: [github.com/shannhk/hermes-agent-control-room](https://github.com/shannhk/hermes-agent-control-room). the exact structure I described above, ready to clone. control-room-first template for managing hermes agents from one VPS agent to specialist teams and orchestrated workflows. fork it and make it yours - [hermesatlas.com](https://hermesatlas.com/): the community-curated map of 100+ open source tools, plugins, workspaces, and integrations built on hermes. categorized by domain (memory providers, workspaces, skill registries, deployment, orchestration). also includes the Hermes Handbook, a beginner-friendly walkthrough. weekly updates, free newsletter - [@Teknium](https://x.com/@Teknium) **on X**: Nous Research founder. ships hermes updates almost daily. the codex runtime integration, the DeepSeek V4 Flash free tier on Nous Portal, the pretext skills, all came through his feed first - [@NousResearch](https://x.com/@NousResearch) **on X**: the official account, official feature announcements - **the meetups**: there are hermes meetups happening in person now (Lisbon, Ventura, more cities). worth showing up if there's one near you. you learn more in 90 minutes of side conversations than in a week of reading ![图像](https://pbs.twimg.com/media/HIYBywiXMAAxMZi?format=jpg&name=large) Hope you got some value out of this, appreciate you reading the whole thing. \-- Shann ]]> Wed, 20 May 2026 06:20:47 GMT https://reader-feed.pages.dev/posts/fec8cf414b-How%20to%20Become%20a%20Hermes%20Agent%20Operator.md obsidian:299f7cff1b:workflow/agent/这个 harness 真的需要存在吗？.md 0. 先问最危险的问题 好。换成 Linus / Musk / Mario 的视角，直接开砍。 **这个 harness 真的需要存在吗？** 第一性原理下的答案，先不是“怎么设计 harness”，而是： > **一个 agent 要可靠地改代码，物理上、信息上、组织上，最少需要什么？** 答案就三件事： 1. **一个能跑代码和测试的隔离环境**（否则无法验证）； 2. **一个能产生 diff 并回滚的版本控制**（否则无法收敛、无法安全）； 3. **一个能在关键节点说“yes/no”的人**（否则无法承担责任）。 **就这三件。** 其他全部是工程修饰。 你上一版那 13 个模块？**先全部假设不存在。** 然后一个一个加回来，加不回来的那个，就是该删的。 > Musk: “如果你删掉的东西里没有 10% 后来要加回来，说明你删得不够狠。” --- ## 1. 砍掉之前那套架构，先列出“看起来必要”的东西 上一版里的模块： 1. Task Intake & Contract Builder 2. Agent Kernel 3. Self-Reflection Ledger 4. ACI / Tool Registry 5. Sandbox 6. Policy Engine 7. Tool Gateway 8. Verification Engine 9. Auto-Repair Loop 10. Human Review Console 11. PR Workflow 12. Repo Memory / AGENTS.md 13. Observer / Stability Monitor / Risk Scorer / Learning Loop / ... **听起来都对。但 90% 是“给屎抛光”。** 第一性原理拷问每一个：**没有它，agent 还能不能完成任务？** --- ## 2. 一个一个砍 ### ❌ 砍掉：Task Intake & Contract Builder **质疑**：你为什么要一个“合同构建器”？ issue 本身就是合同。acceptance criteria 写不清楚，是**人**的问题，不是 harness 的问题。 做一个 contract builder 只是把“人写不清需求”这个事实包装成一个组件而已。 **保留的最小核**：agent 启动时，必须能回答一句话—— > “完成的判定标准是什么命令返回 0？” 如果回答不出来，停。让人补。**这就是全部 intake 逻辑。** 不需要 schema，不需要 builder，不需要服务。一个字段：`done_when: `。 --- ### ❌ 砍掉：Self-Reflection Ledger（那个十几个字段的 JSON） **质疑**：agent 真的需要维护 assumptions、confidence、context_map、risk.score 这些东西吗？ 不需要。这些是**给人看的安慰剂**。 真正驱动 agent 下一步决策的，物理上只有两样： 1. **上一次动作的输出**（test 输出、编译错误、diff）； 2. **目标是否达成**（`done_when` 是否返回 0）。 LLM 自己会在 context 里推理这些。你把它结构化成 20 个字段，只是为了让 dashboard 好看。 **保留的最小核**：一个 append-only 的事件流。 ``` event = {ts, action, output, done_check_result} ``` 就这样。**没有 confidence、没有 risk score、没有 assumption list。** 需要的时候 grep。 --- ### ❌ 砍掉：Policy Engine + Tool Gateway 的复杂 YAML **质疑**：你列了 20 条 allow/ask/deny 规则。物理上，危险动作的本质是什么？ 危险动作的第一性定义只有一个： > **离开 sandbox 影响外部世界的动作。** 不是“修改 auth 目录”。auth 目录在 sandbox 里改，改坏了 rollback 就行，**它不危险**。 真正危险的是： - `git push` 到 protected branch - 网络出站到非白名单 - 读 secret - 调用生产 API - merge / deploy **这些都在 sandbox 边界上。** 所以 policy engine 不需要 200 行 YAML。需要的是： > **sandbox 默认什么都不能出去。要出去的东西，列一个白名单。** 白名单大概 5 行： ``` allowed_egress: - github.com/api (read-only token) - npm/pypi registry allowed_writes: - branch: agent/* forbidden: - everything else ``` **Default deny。这一条规则替代了你上一版整个 policy matrix。** > Linus: “你的策略矩阵品味有问题。20 条规则说明你没想清楚边界在哪。” --- ### ❌ 砍掉：Stability Monitor / Lyapunov V / Risk Scorer **质疑**：你真的要给 agent 算一个 Lyapunov 函数吗？ 不要。这是控制论隐喻用过头了。 物理上，agent 失控只有三种表现： 1. **同一个测试连续失败 N 次**（振荡）； 2. **diff 越改越大**（发散）； 3. **超过 token / time / $ 预算**（资源耗尽）。 三个 if 语句解决： ```python if same_check_failed_n_times(3): stop_and_ask_human() if diff_lines > budget: stop_and_ask_human() if cost > budget or time > budget: stop_and_ask_human() ``` **不需要 V 函数，不需要 7 个权重，不需要 risk scorer。** 三个计数器。 --- ### ❌ 砍掉：Auto-Repair Loop 作为独立模块 **质疑**：repair 和正常 implement 有什么本质区别？ 没有。都是“看 observation，决定下一步”。 把它做成独立模块，是工程师的强迫症。Agent 自己在 loop 里看见测试失败，自然会修。**唯一需要的是 retry budget。** **保留的最小核**：上面那三个计数器之一。**不需要 FailureKind 枚举，不需要分类器，不需要 hypothesis generator。** 这些都是 LLM 本来就会做的事，你不要替它做。 --- ### ❌ 砍掉：Observer / State Estimator / Context Model / Risk Model / Human Model / ... **质疑**：这些“model”物理上存在吗？ 不存在。它们是文档，不是运行时对象。 LLM 的 context window 就是它的 state estimator。你做一个外部 state estimator，本质是在和 LLM 抢工作，而且做得比它差。 **保留的最小核**：只保留 LLM 自己拿不到的信息： - 上次运行的命令输出（已经在事件流里）； - repo 的根目录约定（一个 `AGENTS.md`）； - 当前 diff（`git diff` 就够）。 **就这三个。不要 Repo Model，不要 Context Model。** --- ### ❌ 砍掉：Specialist Agents（Reviewer / Tester / Security / Docs sub-agents） **质疑**：为什么需要多个 agent？ 90% 的情况下，不需要。多 agent 是 2024 年的时髦病。 真正需要“另一个视角”的场景只有一个：**当前 agent 卡住了，需要 fresh context 重新看问题。** 这时候开一个新 session，把 failure ledger 喂进去，**这不是 sub-agent，这是 retry with reset**。 **保留的最小核**：一个 `reset_and_retry(with_summary)` 动作。**不要 ReviewerAgent class，不要 SecurityAgent class。** --- ### ❌ 砍掉：Evidence Pack / Review Cockpit / 复杂 HITL UI **质疑**：人 review 的时候，物理上需要什么？ 需要： 1. **diff**； 2. **测试结果**； 3. **agent 说的一句话：我做了什么、为什么、卡在哪**。 **这就是 GitHub PR。** 已经存在了 15 年。 不要做 review cockpit。不要做 evidence pack schema。**让 agent 开 PR，人在 PR 里 review。** 你做的所有 dashboard，没有人会用第二次。 > Linus: “GitHub PR 已经把这事解决了。你重新发明一个，只是为了在简历上写一行。” --- ### ❌ 砍掉：Learning Loop / Eval Pipeline / Trajectory Store（在 v0/v1 阶段） **质疑**：你都还没让 10 个任务跑通，learning loop 学什么？ 先跑 100 个真实任务，**手工**看失败模式，**手工**改 prompt 和 AGENTS.md。等手工改不动了，再做自动化。 > Musk 第 5 步：“自动化放在最后，不要先自动化错误的流程。” --- ## 3. 砍完之后，剩下什么？ ``` ┌─────────────────────────────────────────────────┐ │ 1. Sandbox（container + git worktree） │ │ - default-deny egress │ │ - 只能 push 到 agent/* branch │ ├─────────────────────────────────────────────────┤ │ 2. Agent loop（一个 while 循环） │ │ while not done_when_passes(): │ │ action = llm.decide(history, AGENTS.md) │ │ output = run_in_sandbox(action) │ │ history.append((action, output)) │ │ if stuck(): break_and_open_pr() │ ├─────────────────────────────────────────────────┤ │ 3. Tools（5 个，不是 15 个） │ │ - shell (in sandbox) │ │ - read_file / write_file (=patch) │ │ - run_tests (= shell, 但显式语义) │ │ - open_pr │ │ - ask_human(question) │ ├─────────────────────────────────────────────────┤ │ 4. 三个 if 语句（stuck 检测） │ │ - same failure x3 │ │ - diff > budget │ │ - cost/time > budget │ ├─────────────────────────────────────────────────┤ │ 5. GitHub PR（review 界面，免费的） │ ├─────────────────────────────────────────────────┤ │ 6. AGENTS.md（repo-level 配置，一个文件） │ └─────────────────────────────────────────────────┘ ``` **就这 6 件事。** 不到 500 行代码可以跑起来。 --- ## 4. 一张表：砍前 vs 砍后 | 上一版 | 砍后 | 原因 | |---|---|---| | Task Intake & Contract Builder | 一个 `done_when` 字段 | issue 就是合同 | | Self-Reflection Ledger (20 字段) | append-only 事件流 | LLM 自己会反思 | | Policy Engine (200 行 YAML) | sandbox 边界 + 5 行白名单 | 危险 = 出 sandbox | | Tool Gateway + Registry | 5 个工具函数 | 不需要 registry 抽象 | | Verification Engine | `done_when` 命令 | 一个 shell command | | Auto-Repair Loop | 同一个 loop | repair 不是独立阶段 | | Stability Monitor / Lyapunov | 3 个计数器 | 不需要控制论隐喻 | | Observer / State Estimator | git diff + 事件流 | LLM context 就是 state | | Repo / Risk / Human Model | AGENTS.md | 一个 markdown 文件 | | Specialist sub-agents | reset_and_retry | 多 agent 是病 | | Review Cockpit / Evidence Pack | GitHub PR | 已经存在 | | Learning Loop / Eval | 先手工 | 自动化放最后 | | Trajectory Store / OpenTelemetry | 事件流写文件 | 等有规模再说 | | Risk-Adaptive Autonomy (v2) | 删 | 过早抽象 | **模块数：13 → 6。代码量大概砍掉 80%。功能损失：0。** --- ## 5. 加回来的部分（≤10%） 砍完之后跑一阵，**真的不够用的时候**，按这个顺序加： 1. **第一个加回来的，几乎一定是：事件流的查询 UI**。因为你会需要 debug 失败 case。但是是 `grep + jq`，不是 dashboard。 2. **第二个可能加回来的：cost dashboard**。因为账单会让你心疼。 3. **第三个可能加回来的：protected path 列表**。但只有在你**真的被烫到一次**之后才加，而不是预防性地加 200 行 YAML。 4. **Eval set**：当你改 prompt 不知道有没有 regression 的时候。 **注意：Specialist agents、Risk Scorer、Stability Monitor、Contract Builder 这些，大概率永远不会加回来。** 这就是它们该被删的证据。 --- ## 6. 第一性原理的几条硬规则 砍完之后，留下这几条作为防止反弹的纪律： 1. **任何模块，先证明没有它系统会坏，再加。** 不是“有了会更好”就加。 2. **任何抽象层，先有 3 个具体用例，再抽。** 不是预想中可能有用就抽。 3. **任何 schema，字段先少后多。** 加字段容易，删字段难。 4. **任何 policy，default deny。** 白名单永远比黑名单短。 5. **任何 dashboard，先用 grep。** grep 不够用了再做 UI。 6. **任何 sub-agent，先用 reset。** reset 不够用了再做 sub-agent。 7. **任何自动化，先手工跑 100 次。** 手工烦死了再自动化。 --- ## 7. 留给你的挑战 去看你上一版那 13 个模块。对每一个，回答三个问题： 1. **删掉它，第一个会坏掉的具体场景是什么？** 写不出来 → 删。 2. **这个场景一年发生几次？** < 10 次 → 删，发生时手工处理。 3. **LLM 自己能不能在 prompt 里做这件事？** 能 → 删，让 LLM 做。 我赌你能再砍掉 30%。 然后：**先写 500 行让它跑起来，跑 50 个真实任务，再来谈架构。** > Talk is cheap. Show me the harness running on real PRs. ]]> Mon, 11 May 2026 07:42:30 GMT https://reader-feed.pages.dev/posts/299f7cff1b-%E8%BF%99%E4%B8%AA%20harness%20%E7%9C%9F%E7%9A%84%E9%9C%80%E8%A6%81%E5%AD%98%E5%9C%A8%E5%90%97%EF%BC%9F.md obsidian:4e5e77f605:workflow/agent/把钱学森《工程控制论》的思想映射到 coding agent harness.md 1. 把 coding agent 看成控制系统 我的最大启发是： **Coding agent harness 不应该被设计成“流程编排器”，而应该被设计成一个面向不完全确定智能体的“分层反馈控制系统”。** > Agent 是主控制器，harness 是观测器、约束器、安全联锁和人机协同外环；人是慢速高价值反馈源，而不是每一步的按钮审批员。 下面把钱学森《工程控制论》的思想映射到 coding agent harness。 --- ## 1. 把 coding agent 看成控制系统 可以这样建模： | 控制论概念 | Coding agent harness 中的对应物 | |---|---| | 参考输入 `r` | 用户任务、issue、acceptance criteria | | 被控对象 `P` | 代码库、sandbox、测试环境、CI、依赖系统 | | 控制器 `C` | Agent kernel，自主决定 workflow | | 执行器 | edit、patch、bash、test、git、PR 等工具 | | 输出 `y` | diff、测试结果、lint、typecheck、CI、PR 状态 | | 误差 `e` | 当前实现与目标之间的差距 | | 反馈 | 测试结果、编译错误、review comment、CI failure | | 扰动 `d` | 需求不清、隐藏依赖、flaky test、LLM 幻觉、环境不一致 | | 观测器 | run state、trajectory log、failure ledger、risk estimator | | 人类外环 | reviewer、approver、product/architecture decision maker | 所以 agent harness 的本质不是： ```text step1 -> step2 -> step3 -> step4 ``` 而是： ```text 目标 -> agent 决策 -> 工具动作 -> 环境反馈 -> 状态估计 -> 自修复/升级/继续 ``` 也就是一个闭环系统。 --- ## 2. “稳定性第一”：自治必须有边界 钱学森强调控制系统首先要稳定。对应到 coding agent，稳定性不是数学上不发散，而是： - 不无限循环； - 不越改越大； - 不为了修一个测试破坏更多模块； - 不绕过测试； - 不修改敏感路径； - 不擅自 merge / deploy； - 不把不确定性伪装成完成。 因此 harness 里应该有一个 **Progress / Stability Monitor**。 可以定义一个类似 Lyapunov 函数的风险-误差度量： ```text V = w1 * 未满足验收条件数量 + w2 * failing checks 数量 + w3 * diff 范围复杂度 + w4 * 风险路径修改程度 + w5 * 未验证假设数量 + w6 * retry 消耗 + w7 * agent 自信度不足 ``` 每轮 agent 动作之后，harness 评估： ```text V 是否下降？ 风险是否扩大？ 是否触碰 hard constraint？ 是否进入重复失败模式？ ``` 如果 `V` 连续几轮不下降，就不应该继续让 agent 盲目修，而应进入： 1. 缩小问题； 2. 回滚到 checkpoint； 3. 重新计划； 4. 请求 human review。 这就是控制论里的稳定性约束。 --- ## 3. “反馈是灵魂”：测试、CI、review 都是反馈信号 Coding agent 最大的错误设计，是把 LLM 当成一次性生成器。 控制论视角下，它必须是反馈驱动的： ```mermaid flowchart LR Goal[Task / Acceptance Criteria] --> Agent[Agent Controller] Agent --> Action[Tool Action / Patch] Action --> Env[Repo / Sandbox / CI] Env --> Feedback[Test / Lint / Diff / Error] Feedback --> Observer[State Estimator] Observer --> Agent ``` 因此 harness 应该强制 agent 不断回答： - 当前目标是什么？ - 现在观察到了什么？ - 哪个假设被证实？ - 哪个假设被推翻？ - 下一步实验是什么？ - 当前风险是否变大？ - 是否需要人类判断？ 这就是我之前提到的 **Self-Reflection Ledger**。它不是让模型暴露完整思维链，而是保存工程化状态摘要： ```ts type ReflectionLedger = { current_goal: string; observed_facts: string[]; assumptions: { text: string; confidence: "low" | "medium" | "high"; evidence?: string; }[]; failed_attempts: { action: string; result: string; suspected_cause: string; }[]; next_experiment: string; risk_change: "lower" | "same" | "higher"; need_human?: { reason: string; decision_needed: string; }; }; ``` 这相当于 agent 的“状态估计器”。 --- ## 4. “不完全确定系统”：LLM agent 天然就是不确定控制对象 钱学森特别关注不完全确定系统，这一点对 agent harness 极其关键。 Coding agent 面临的不确定性包括： | 不确定性 | 表现 | |---|---| | 需求不确定 | issue 写得模糊，验收标准缺失 | | 环境不确定 | 本地测试和 CI 不一致 | | 代码库不确定 | 隐藏约定、文档过期、历史 debt | | 模型不确定 | hallucination、过度自信、上下文遗漏 | | 工具不确定 | flaky test、package install 失败 | | 人类偏好不确定 | reviewer 风格、架构偏好、产品取舍 | 所以 harness 要走 **鲁棒控制** 思路： - 默认不信单一信号； - 测试、静态分析、diff review 多重验证； - 对高风险动作加安全裕度； - 对不确定需求要求 human clarification； - 对失败修复设置 retry budget； - 对 agent confidence 低的地方自动升级； - 对敏感路径使用更严格 policy。 核心不是让 agent 永远正确，而是让系统在 agent 不完全可靠时仍然整体可靠。 --- ## 5. “可观测性”：看不见就无法控制 如果 harness 不能观察 agent 的状态，就无法安全放权。 所以每个 run 至少要观测： - agent 看过哪些文件； - 为什么认为这些文件相关； - 改了哪些文件； - diff 范围多大； - 跑了哪些测试； - 哪些测试失败； - 是否新增测试； - 是否触碰 protected path； - 是否出现循环行为； - 是否修改了任务目标； - 是否有未验证假设。 一个很重要的判断： > 如果 acceptance criteria 没有对应的可观测验证方式，这个任务对 agent 来说就是“不可观测系统”。 此时 agent 不应该强行完成，而应该： 1. 先补测试； 2. 生成验证计划； 3. 请求人类确认验收标准； 4. 或把 PR 标记为需要人工重点 review。 --- ## 6. “可控性”：agent 不是万能控制器 控制论里，系统可控才谈得上控制。 对应到 coding agent： - 如果工具权限不够，agent 不可控； - 如果没有测试命令，质量不可控； - 如果依赖服务无法启动，验证不可控； - 如果任务涉及产品决策，agent 不可控； - 如果需要线上数据但无安全访问方式，agent 不可控； - 如果修改范围超出 policy，agent 不可控。 所以 harness 应该有一个 **controllability check**： ```text 这个任务是否能在当前 sandbox + 当前工具 + 当前权限 + 当前验证手段下完成？ ``` 如果不能，agent 应该升级，而不是乱试。 --- ## 7. “采样控制”：不是每一步都让人看，而是在关键采样点介入 采样控制思想非常适合 human-in-the-loop。 人不应该连续介入，因为人类反馈成本高、速度慢。应该采用 **事件触发式采样**： ### 自动运行的采样点 - 每次工具调用后记录 observation； - 每次 patch 后更新 diff summary； - 每次测试后更新 failure ledger； - 每次 commit 后记录 checkpoint。 ### 需要人类采样的关键点 - 修改 protected path； - 新增依赖； - 修改数据库 schema； - 修改 auth/payment/security； - 扩大 scope； - 多次 auto-repair 失败； - 需要产品/架构取舍； - 准备从 draft PR 转 ready； - 最终 merge。 这就符合你的要求： > 人在 loop，但主要是 review，不是所有步骤都审批。 --- ## 8. “分层控制”：agent 主导 workflow，harness 控制边界，人类控制方向 我建议采用三层控制结构。 ```mermaid flowchart TD Human[Human Supervisor
目标/取舍/最终 review] --> Harness[Harness Supervisor
policy/risk/checkpoint] Harness --> Agent[Agent Controller
自主 workflow] Agent --> Tools[Tools / Actuators] Tools --> Repo[Repo / Sandbox / CI] Repo --> Observer[Observer / Feedback] Observer --> Agent Observer --> Harness Harness --> Human ``` ### 第一层：agent 内环 高频、自动、自主。 负责： - 查代码； - 制定计划； - 修改代码； - 运行测试； - 修复失败； - 写 PR summary。 ### 第二层：harness 监督环 中频、规则化、确定性。 负责： - policy gate； - risk scoring； - checkpoint； - retry budget； - sandbox isolation； - allowed/ask/deny； - trajectory logging。 ### 第三层：human 外环 低频、高价值。 负责： - 需求澄清； - 架构选择； - 风险确认； - review； - merge； - 事后调整 policy。 这样 agent 仍然是 workflow 的主导者，但系统整体不会失控。 --- ## 9. “模型即对象”：agent 操作的不是代码，而是代码系统的模型 钱学森强调数学建模。对 coding agent harness 来说，不能只给 agent raw repo。 应该维护多个模型： ```text Task Model 任务目标、验收条件、非目标 Repo Model 模块、依赖、owner、protected path Risk Model 哪些改动危险，哪些需要审批 Progress Model 当前完成度、失败点、剩余 gap Context Model 相关文件、相关 symbol、调用链 Human Model reviewer 偏好、项目规范、历史反馈 ``` Agent 每一步不是“凭感觉写代码”，而是在这些模型上做决策。 这也解释了为什么 `AGENTS.md` 很重要。它相当于这个控制系统的局部参数配置： ```md # AGENTS.md ## Build pnpm test pnpm typecheck ## Protected areas Ask before editing: - auth/** - payments/** - infra/** - migrations/** ## Review expectations - Add tests for bug fixes - Keep PR small - Do not introduce new dependency without approval ``` --- ## 10. “从特殊到一般，再回到特殊”：harness 要沉淀通用控制规律 钱学森的技术科学路径对 harness 设计很有启发： 1. 从具体 repo、具体 bug、具体 PR 中观察 agent 失败模式； 2. 抽象出通用策略； 3. 写入 harness policy、eval、tool design； 4. 再回到具体 repo 中应用。 例如： | 具体失败 | 抽象规律 | harness 改进 | |---|---|---| | agent 改太多文件 | scope 失控 | diff budget + risk escalation | | agent 反复修同一测试 | 闭环振荡 | retry cap + replan gate | | agent 绕过测试 | 目标函数错误 | forbid disabling tests | | agent 不理解 repo 惯例 | 模型不完整 | AGENTS.md + repo memory | | agent 看不到 CI 差异 | 观测不足 | CI feedback ingestion | | reviewer 总提同类意见 | 人类反馈未沉淀 | review comment classifier | 这样 harness 会越用越强，而不是每次从零开始。 --- ## 11. “最优控制”：优化目标不是只让 agent 完成任务 Agent harness 的目标函数不应该是： ```text maximize task completion ``` 而应该是多目标优化： ```text maximize correctness minimize risk minimize unnecessary human interruption minimize diff size minimize time minimize cost maximize maintainability maximize reviewer trust ``` 也就是说，agent 不是“尽快写完代码”，而是要在约束下找到最优控制策略。 例如： - 低风险文档修改：agent 可以直接改、测试、开 draft PR； - 中风险 bug fix：agent 自动修，但必须跑测试； - 高风险 auth 修改：先生成方案，请人 review，再动手； - 需求不清：不要写代码，先 ask human； - CI 多次失败：不要继续乱修，生成 failure report。 --- ## 12. 可以把 harness 重构成这几个控制论模块 我会在原架构上增加这些模块： ```text 1. Reference Manager 管理任务目标、验收标准、非目标。 2. Observer / State Estimator 从工具输出、diff、测试、CI 中估计当前状态。 3. Agent Controller 由 agent 自主决定下一步 workflow。 4. Supervisory Controller harness 的确定性控制层：allow / ask / deny。 5. Stability Monitor 检测循环、发散、scope creep、风险上升。 6. Repair Controller 管理自动修复、retry budget、rollback。 7. Human Feedback Interface 在关键节点请求 review、approval、clarification。 8. Learning / Identification Loop 从历史 run 中更新 policy、AGENTS.md、eval。 ``` 核心循环可以是： ```python while not done: y = observe_workspace() x = estimate_state(y) e = compare_with_acceptance_criteria(x, task) V = compute_progress_risk_score(x, e) if violates_hard_constraints(x): rollback_or_stop() ask_human() if not observable(task, x): agent.add_tests_or_request_clarification() if not controllable(task, tools, policy): escalate_to_human() action = agent.decide_next_action( task=task, state=x, error=e, risk=V, available_tools=tools, ) gate = supervisor.evaluate(action, state=x, risk=V) if gate == "allow": result = execute(action) elif gate == "ask": result = ask_human_with_evidence_pack(action, x) else: result = deny_and_return_reason(action) update_state(result) if progress_not_improving_for_n_steps(): replan_or_revert_or_escalate() ``` --- ## 13. 最重要的架构启发 我会把这句话作为设计原则： > **让 agent 自主，不等于让系统无控制；真正的自治来自闭环反馈、状态观测、稳定性约束和分层监督。** 所以，最好的 coding agent harness 不是一个强行规定 agent 每一步怎么做的 workflow engine。 它应该是： ```text 一个面向不完全确定智能体的工程控制系统。 ``` 其中： - agent 决定 workflow； - harness 提供可观测性、可控性、稳定性； - tests/CI/review 提供反馈； - human 是外环监督者； - policy 是安全边界； - checkpoint/rollback 是稳定机制； - failure ledger 是系统自省； - eval 和历史轨迹是系统学习。 一句话总结： > **用钱学森控制论思想看，coding agent harness 的核心不是“编排 agent”，而是“控制 agent 所在的工程闭环”：让 agent 在反馈中自主决策，在约束中自动修复，在关键节点接受人的高价值校正。** ]]> Mon, 11 May 2026 07:35:23 GMT https://reader-feed.pages.dev/posts/4e5e77f605-%E6%8A%8A%E9%92%B1%E5%AD%A6%E6%A3%AE%E3%80%8A%E5%B7%A5%E7%A8%8B%E6%8E%A7%E5%88%B6%E8%AE%BA%E3%80%8B%E7%9A%84%E6%80%9D%E6%83%B3%E6%98%A0%E5%B0%84%E5%88%B0%20coding%20agent%20harness.md obsidian:096755aa25:workflow/agent/Agent 主导的 coding agent harness 架构.md 0. 调研后的关键判断 下面是一套**Agent 主导的 coding agent harness 架构**。核心思想：**workflow 由 agent 动态决定；harness 只提供安全边界、工具接口、持久化、验证、审批与可观测性**。人不是每步批准，而是作为 **reviewer / approver** 出现在关键风险点。 Intake[Task Intake & Contract Builder] Intake --> Kernel[Agent Kernel: workflow self-director] Kernel --> State[Run State / Self-Reflection Ledger] Kernel --> ACI[Agent-Computer Interface] Kernel --> Critics[Specialist Agents as Tools
Reviewer / Tester / Security / Docs] ACI --> ToolGateway[Tool Gateway + Policy Engine] ToolGateway -->|allow| Sandbox[Ephemeral Sandbox / Worktree / Container] ToolGateway -->|ask| HITL[Human Review / Approval Console] ToolGateway -->|deny| Kernel Sandbox --> Verifier[Verification Engine
tests / lint / typecheck / build / security] Verifier --> Kernel Kernel --> Repair[Auto-Repair Loop] Repair --> ACI Kernel --> PR[Branch / Commit / Draft PR] PR --> CI[CI + Checks] CI --> HITL HITL -->|approve / request changes / edit plan / take over| Kernel HITL -->|final approve| Merge[Human Merge / Release Gate] State --> Obs[Trajectory Store / Audit / Metrics / Evals] Sandbox --> Obs ToolGateway --> Obs HITL --> Obs ``` **一句话分工：** | 层 | 责任 | |---|---| | Agent Kernel | 自己决定下一步：查代码、制定计划、编辑、测试、修复、请 reviewer、开 PR | | Harness | 提供受控工具、沙箱、权限、checkpoint、验证、审批、日志 | | Human | 只 review 关键节点：高风险计划、敏感工具、最终 PR、失败升级 | --- ## 2. 核心组件设计 ### 2.1 Task Intake & Contract Builder 输入可以是 issue、Jira、Linear、Slack、人工 prompt。第一步不是直接写代码，而是生成结构化任务合同： ```ts type TaskSpec = { task_id: string; goal: string; repo: string; branch_base: string; acceptance_criteria: string[]; non_goals: string[]; risk_hints: string[]; required_checks: string[]; human_contact?: string; }; ``` **自动继续条件：** - 需求清楚； - 影响范围低； - acceptance criteria 可测试； - 不涉及安全、权限、支付、数据迁移、生产配置。 **请求人类澄清条件：** - 需求模糊； - 目标和现有行为冲突； - agent 发现多个可行方案且 trade-off 明显； - 需要产品决策。 --- ### 2.2 Agent Kernel：让 agent 主导 workflow Agent Kernel 不应是固定 DAG，而应是一个“可约束的自治 loop”。 ```python while not state.done and budget.remaining(): state = load_run_state() action = agent.decide_next_action( task=state.task, repo_summary=state.repo_summary, plan=state.plan, failures=state.failure_ledger, tools=tool_registry.available_tools(), policy_summary=policy.visible_rules(), ) decision = policy.evaluate(action, state) if decision.type == "deny": observation = ToolObservation.denied(decision.reason) elif decision.type == "ask_human": checkpoint(state, action) human_decision = approval_service.interrupt(action, evidence_pack(state)) observation = apply_human_decision(human_decision) else: observation = tool_gateway.execute(action) state = agent.reflect_and_update_state(state, action, observation) if verifier.should_run(action, state): report = verifier.run(state) state = agent.reflect_and_repair_or_continue(state, report) ``` 重点：**下一步由 agent 决定**，但每个动作都经过 `Policy Engine` 和 `Tool Gateway`。 --- ### 2.3 Self-Reflection Ledger：可自省，但不要存 raw chain-of-thought 建议保存的是**可审计的工程推理摘要**，而不是完整隐藏思维链。 ```ts type AgentRunState = { phase: | "intake" | "discover" | "plan" | "implement" | "verify" | "repair" | "review" | "done" | "escalated"; current_goal: string; plan: Array<{ id: string; description: string; status: "todo" | "doing" | "done" | "blocked"; evidence_refs: string[]; }>; assumptions: Array<{ text: string; confidence: "low" | "medium" | "high"; validated_by?: string; }>; context_map: Array<{ file: string; relevance: string; symbols?: string[]; }>; failure_ledger: Array<{ check: string; command: string; failure_summary: string; suspected_causes: string[]; attempted_fixes: string[]; next_experiment?: string; }>; risk: { score: "low" | "medium" | "high" | "critical"; reasons: string[]; requires_human_gate: boolean; }; verification: { tests_added: string[]; tests_run: string[]; lint: "pass" | "fail" | "not_run"; typecheck: "pass" | "fail" | "not_run"; ci: "pass" | "fail" | "pending" | "not_run"; }; open_questions: string[]; done_criteria_status: Record; }; ``` 每次重要 observation 后，agent 必须更新： 1. 我现在认为问题在哪里； 2. 哪些证据支持； 3. 哪些假设未验证； 4. 下一步实验是什么； 5. 什么情况下停止并升级给人。 这就是“自省”，但保持工程可读、可审计。 --- ## 3. ACI / Tool 层设计 不要把 agent 直接接到完整 shell。给它一组专用工具。 ### 推荐工具集 | 工具 | 用途 | 默认权限 | |---|---|---| | `repo_search(query)` | 搜代码、符号、调用点 | allow | | `view_file(path, range)` | 分段查看文件 | allow | | `semantic_search(query)` | 基于 embeddings / AST 的上下文检索 | allow | | `dependency_graph(symbol)` | 查调用关系、依赖 | allow | | `apply_patch(diff)` | 应用 patch | 条件 allow | | `edit_file(path, range, replacement)` | 精确编辑 | 条件 allow | | `run_test(selector)` | 运行测试 | allow | | `run_lint()` | lint | allow | | `run_typecheck()` | typecheck | allow | | `safe_bash(cmd)` | 受限 shell | policy gated | | `git_diff()` | 查看 diff | allow | | `git_commit(message)` | 提交到 agent 分支 | 条件 allow | | `open_draft_pr()` | 创建 draft PR | ask / allow by repo policy | | `request_review()` | 请求人类 review | allow | | `mark_ready_for_review()` | 转正式 PR | ask | | `merge_pr()` | 合并 | deny，必须人类 | SWE-agent 的经验支持这种方向：专用 ACI、受控编辑器、linter、目录搜索和文件查看器能显著改善 agent 操作代码库的能力。([github.com](https://github.com/SWE-agent/SWE-agent/blob/main/docs/background/aci.md)) --- ## 4. Sandbox / Workspace 每个任务创建独立 workspace： - 独立 git worktree 或 clone； - 独立 branch； - Docker / microVM sandbox； - 最小权限 token； - 默认无生产 secret； - 网络 egress allowlist； - 所有命令 stdout / stderr 入库； - 文件改动全部通过 diff 记录。 OpenHands 文档把 sandbox 定义为 agent 执行命令、编辑文件、启动服务的环境，并推荐 Docker sandbox 以隔离 host；GitHub Copilot cloud agent 也在临时开发环境中探索代码、改代码、跑测试和 linter。([docs.openhands.dev](https://docs.openhands.dev/openhands/usage/runtimes/overview)) --- ## 5. Policy Engine：只在关键节点问人 建议实现 **allow / ask / deny** 三态策略。 ### 默认策略矩阵 | 动作类型 | 默认策略 | |---|---| | 读文件、搜索、查看 git diff | allow | | 运行本地测试、lint、typecheck | allow | | 修改普通业务代码 | allow if sandbox + diff 小 + 非 protected path | | 修改测试、文档 | allow | | 新增依赖 | ask | | 修改 lockfile | ask | | 修改 auth、crypto、payment、permission、tenant isolation | ask | | 修改 DB migration / schema | ask | | 修改 CI/CD、Dockerfile、部署脚本 | ask | | 访问外网 | ask，必须说明目的和域名 | | 读取 secret / `.env` / credential | deny | | 删除大量文件 | ask 或 deny | | force push / rewrite history | deny | | merge 到 protected branch | deny | | prod deploy / kubectl apply / terraform apply | deny | | 关闭测试、安全扫描、绕过 CI | deny | OpenAI 的 agent 指南建议把 guardrails 做成多层防御，并在高风险动作或超过失败阈值时触发人类介入；Agents SDK 也支持对敏感工具调用暂停等待批准。([openai.github.io](https://openai.github.io/openai-agents-python/guardrails/)) ### Policy-as-code 示例 ```yaml protected_paths: - "infra/**" - ".github/workflows/**" - "migrations/**" - "auth/**" - "payments/**" - "security/**" - "**/.env*" tools: repo_search: default: allow view_file: default: allow deny_if_path_matches: - "**/.env*" - "**/secrets/**" apply_patch: default: allow ask_if: - path_matches: protected_paths - diff_lines_gt: 500 - deletes_files: true - modifies_public_api: true deny_if: - path_matches: ["**/.env*", "**/private_keys/**"] safe_bash: allow_patterns: - "git status" - "git diff*" - "pytest*" - "npm test*" - "pnpm test*" - "ruff*" - "mypy*" - "tsc*" ask_patterns: - "npm install*" - "pnpm add*" - "pip install*" - "curl*" - "wget*" - "docker*" deny_patterns: - "rm -rf /*" - "git push --force*" - "kubectl *" - "terraform apply*" - "aws *" - "gcloud *" merge_pr: default: deny ``` --- ## 6. Auto-Repair Loop Auto-repair 应该是 harness 的一等能力，而不是“失败后再问人”。 ### 失败分类 ```ts type FailureKind = | "syntax" | "lint" | "typecheck" | "unit_test" | "integration_test" | "build" | "security_scan" | "dependency" | "flaky_test" | "merge_conflict" | "ambiguous_requirement" | "environment"; ``` ### 修复流程 ```mermaid flowchart TD F[Failure Report] --> C[Classify Failure] C --> R[Retrieve Relevant Context] R --> H[Generate Hypothesis] H --> P[Patch Candidate] P --> T[Run Targeted Check] T -->|pass| Full[Run Broader Verification] T -->|fail| Reflect[Reflect + Update Failure Ledger] Reflect --> Budget{Retry Budget Left?} Budget -->|yes| R Budget -->|no| Escalate[Human Escalation Pack] Full -->|pass| Continue[Continue Workflow] Full -->|fail| Reflect ``` AutoCodeRover 的论文中也采用了“生成 patch 后跑测试，失败则重新调用 patch generation agent”的验证重试思路。([zhiyufan.github.io](https://zhiyufan.github.io/files/ISSTA2024a.pdf)) ### 默认 retry budget | 场景 | 自动修复次数 | |---|---:| | lint / format | 5 | | syntax / typecheck | 4 | | 单元测试失败 | 3 | | 集成测试失败 | 2 | | flaky / 环境问题 | 1，然后标记不确定 | | 安全扫描失败 | 1，然后 ask | | schema / infra / auth 相关失败 | ask | ### 必须升级给人的条件 - 同一失败连续 3 次； - agent 想扩大改动范围超过原计划； - 需要修改 protected path； - acceptance criteria 不可验证； - 修复会改变 public API； - agent confidence 低； - CI 和本地结果冲突； - 需要产品或架构决策。 --- ## 7. Human Review Console 人类界面不是聊天窗口，而是 **review cockpit**。 ### 每次 ask human 必须提供 Evidence Pack ```ts type EvidencePack = { task_summary: string; current_phase: string; proposed_action: string; why_needed: string; risk_reasons: string[]; files_touched: string[]; diff_summary?: string; tests_run: string[]; failing_checks?: string[]; alternatives_considered: string[]; rollback_plan: string; requested_decision: | "approve_tool" | "approve_plan" | "choose_option" | "clarify_requirement" | "review_pr" | "take_over"; }; ``` ### 人类可做的动作 | 人类动作 | Agent 后续 | |---|---| | Approve | 继续执行 | | Reject | 重新计划 | | Edit plan | 更新 state，继续 | | Add constraint | 写入 task contract | | Request changes | agent 自动修复 | | Take over | 停止 agent，保留 branch | | Final approve | 人类合并或发布 | LangGraph 的 HITL 支持 approve/reject，也支持 review 并编辑 graph state 后恢复执行，这正适合这里的 review cockpit。([docs.langchain.com](https://docs.langchain.com/oss/python/langgraph/human-in-the-loop)) --- ## 8. PR / Review 工作流 建议采用 GitHub-style PR 作为最终交付边界： 1. agent 自动创建 branch； 2. agent 自动 commit 小步改动； 3. agent 自动跑本地 checks； 4. agent 可自动创建 draft PR； 5. agent 写 PR summary、测试证据、风险说明； 6. human review； 7. reviewer comment 触发 agent repair； 8. CI 全绿后，human merge。 GitHub Copilot cloud agent 的产品形态也是让 agent 研究 repo、制定计划、在 branch 上改代码、跑测试和 linter，然后通过 PR 让开发者 review；GitHub 文档还强调这种方式让步骤通过 commit 和 logs 可见。([docs.github.com](https://docs.github.com/en/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot)) ### PR 模板 ```md ## Summary - What changed - Why ## Acceptance Criteria - [x] ... - [ ] ... ## Files Changed - `src/foo.ts`: ... - `tests/foo.test.ts`: ... ## Verification - [x] unit tests: `...` - [x] lint: `...` - [x] typecheck: `...` - [ ] integration tests: not run, reason: ... ## Agent Notes - Assumptions: - Risks: - Areas needing human attention: ## Rollback - Revert commit: ... ``` --- ## 9. Repo Instruction / Agent Memory 每个 repo 应该有一个 agent-facing instruction 文件，例如： ```md # AGENTS.md ## Build - pnpm install - pnpm test - pnpm typecheck ## Code style - Use existing service pattern in `src/services` - Do not introduce new state management library ## Testing - Add unit tests for bug fixes - Prefer integration tests for API route changes ## Protected areas - Ask before editing `infra/**` - Ask before editing `auth/**` - Never read `.env*` ## PR etiquette - Small commits - Include verification output - Draft PR first ``` Claude Code 的最佳实践也建议把 bash 命令、测试 runner、repo etiquette、架构决策等写进项目说明，并像代码一样 review / prune 这些 instructions。([anthropic.com](https://www.anthropic.com/engineering/claude-code-best-practices?_bhlid=6d35c25e04616eabb4469b78a6e8848b61863ba0)) --- ## 10. 推荐落地版本 ### MVP v0：Review-first - agent 可读 repo； - agent 生成 plan； - human approve plan； - agent 生成 patch； - human review diff； - 不自动 push。 适合刚开始建立信任。 ### v1：Autonomous implementation - 自动 branch； - 自动 patch； - 自动测试； - 自动修复； - 失败阈值后 ask； - 自动 draft PR； - human final review。 这是你描述的主要目标形态。 ### v2：Risk-adaptive autonomy - 低风险任务全自动到 draft PR； - 中风险任务 plan gate； - 高风险任务 tool gate + final review； - reviewer comment 自动修复； - metrics 驱动逐步放宽 allowlist。 --- ## 11. 关键指标 | 指标 | 目的 | |---|---| | Human interrupts per task | 是否打扰太多 | | Auto-repair success rate | 自修复能力 | | First CI pass rate | 初次质量 | | PR acceptance rate | 人类 review 通过率 | | Reviewer comments per PR | 代码质量 | | Mean time to draft PR | 效率 | | Escalation reasons | 哪些地方需要改工具或策略 | | Denied tool calls | 安全策略是否合理 | | Reverted agent PRs | 线上质量 | | Protected-path edit attempts | 风险行为监控 | --- ## 12. 最小可实现技术栈 如果你要快速做： - **Orchestrator**：LangGraph / Temporal / 自研 event loop； - **Checkpoint**：Postgres； - **Sandbox**：Docker container + git worktree； - **Tool Gateway**：Python/FastAPI service； - **Policy Engine**：YAML + deterministic matcher； - **Agent State**：JSONB + event sourcing； - **Verification**：repo-specific command registry； - **Review UI**：GitHub PR + lightweight approval dashboard； - **Observability**：OpenTelemetry + trajectory viewer。 OpenHands 的新 SDK 论文也强调 production software agents 需要 flexible implementation、reliable/secure execution、human interaction interfaces、sandboxed execution、lifecycle control 和 security analysis；这和上面的 harness 分层基本一致。([arxiv.org](https://arxiv.org/abs/2511.03690)) --- ## 13. 最重要的设计原则 **不要让 harness 决定 workflow。** Harness 应该决定： - 哪些工具存在； - 哪些动作安全； - 何时 checkpoint； - 何时 ask human； - 如何验证； - 如何记录证据； - 如何回滚。 **Agent 应该决定：** - 先查哪里； - 是否需要写测试； - 先修哪个失败； - 是否需要更多上下文； - 什么时候调用 reviewer/tester/security sub-agent； - 什么时候认为任务完成； - 什么时候主动升级给人。 这样才能满足你的要求：**agent 主导、自省、自动修复；人在 loop，但主要是 review，不是 babysit 每一步。** ]]> Mon, 11 May 2026 07:23:36 GMT https://reader-feed.pages.dev/posts/096755aa25-Agent%20%E4%B8%BB%E5%AF%BC%E7%9A%84%20coding%20agent%20harness%20%E6%9E%B6%E6%9E%84.md obsidian:02a59bc16b:workflow/Using Claude Code The Unreasonable Effectiveness of HTML.md Using Claude Code: The Unreasonable Effectiveness of HTML Markdown has become the dominant file format used by agents to communicate with us. It’s simple, portable, has some rich text capability and... Mon, 11 May 2026 07:23:30 GMT https://reader-feed.pages.dev/posts/02a59bc16b-Using%20Claude%20Code%20The%20Unreasonable%20Effectiveness%20of%20HTML.md obsidian:50f33f0c3f:workflow/agent/从 Skills 到分层 Workflow：AI Agent 工程化的下一层抽象.md 从 Skills 到分层 Workflow：AI Agent 工程化的下一层抽象 很多 AI Agent 项目走到中后期，都会开始沉淀 skills。一开始，这几乎是必然动作。写代码要有 TDD skill，排查问题要有 debug skill，提交前要有 review skill，写文档要有 writing skill。每一个 skill 都像是在给 Age... /design -> /plan -> /build -> /review -> /ship 这条路径背后的判断是：**工程交付需要状态机，而不是自由联想。** /refine：把模糊想法收敛成可验证规格 /refine 的任务不是“继续聊一聊需求”，而是把模糊想法压缩成可验证的 spec。它关心的是： - 问题是什么； - 用户是谁； - 成功标准是什么； - 约束有哪些； - 当前缺哪些外部事实； - 最终产物类型是什么。 这一阶段如果没有收敛清楚，后面所有实现都可能在错误目标上越跑越快。 /design：在实现前冻结创作与体验判断 很多系统最容易犯的错，是把 design 偷偷塞进 build。也就是说，边做边想、边写边改、边实现边决定体验。 这在小任务里看起来无伤大雅，但在多产物系统里会迅速失控。UI、文章、deck、视觉稿这些产物，本质上都需要先完成创作和体验层面的判断，再进入生产。否则，build 阶段就会不断替代 design 阶段，最终让整个流程失去边界。 /plan：定义任务拓扑，而不是写一份待办清单 /plan 真正要做的不是列出一些 todo，而是定义任务拓扑： - 哪些任务必须串行； - 哪些任务可以并行； - 哪些文件或模块允许写入； - 哪些步骤完成后才能进入下一阶段； - 哪些风险需要前置处理。 计划不是形式主义，它的意义在于把“工作如何展开”从运行时 improvisation，变成可审查的结构。 /build：消费已批准输入，而不是重新发明目标 /build 才是实现和内容生产真正发生的地方。但它最重要的纪律不是“认真执行”，而是：**只消费已经批准的 spec、design 和 plan，而不是在实现过程中重新定义目标。** 这是很多 Agent workflow 会失效的关键点。因为如果 build 可以随时回写目标、改写边界、替代 review，那前面的阶段就会全部失去约束意义。 /review：门控，而不是口头确认 /review 也不应该只是“帮我看看”。 真正的 review 是门控。它的职责不是鼓励，不是润色，也不是在明显缺失时给一句“整体不错”。它必须有能力阻断流程：只要发现 blocking 问题，就要明确退回 /build，必要时甚至退回 /plan 或 /refine。 /ship：交付完成，不等于实现结束 最后的 /ship 处理的不是代码本身，而是交付动作：发布、导出、同步、记录、回滚信息、交付痕迹。工程系统最容易被忽略的一点是：**代码写完，并不等于交付完成。** 交付真正结束，必须以可追踪的收尾动作为标志。 因此，workflow 的意义不在于给 skills 排一个顺序，而在于把每个阶段变成有输入、有输出、有门控的协议。它解决的不是“快点进入某种能力”，而是“任务如何合法地推进到下一状态”。 ## 三、真正的升级，不只是阶段流，而是纵向分层 ![图像](https://pbs.twimg.com/media/HH28gSsasAAM9kq?format=png&name=large) 如果只有阶段流，这个系统依然可能退化成一组更长、更复杂的 prompt。真正让 Unified Skills 变成工程系统的，不只是横向阶段，而是纵向分层。 我把它抽象成六层： CANON -> Command -> Agent -> Skill -> Artifact -> Hook / validate 这不是六种文件分类，而是六种不同的系统职责。每一层都解决一个问题，同时拒绝解决另一个问题。一个方案是否成熟，不看它能不能跑通一次，而看它能不能被复用、治理和演化。 ## 四、CANON：所有 Workflow 的宪法 ![图像](https://pbs.twimg.com/media/HH28kqLboAEXHvJ?format=png&name=large) 最上层是 CANON.md。 它不是某个具体 skill，也不是项目说明书，而是所有阶段、角色和技能都必须继承的全局纪律。它定义的不是某类任务技巧，而是不可放松的底线：先陈述假设、控制范围、验证优先、遇到矛盾先停止并澄清、调试先找根因、不做 yes-machine。 这一层解决的是**纪律统一**，而不解决具体任务策略。 为什么它必须独立存在？因为如果没有 CANON，每个 skill 都会带着自己的隐含价值观。TDD skill 强调测试，debug skill 强调根因，review skill 强调质量，但它们之间缺少统一的行为合同。久而久之，整个系统会出现一种隐性腐蚀：局部方法论都很认真，整体行为却越来越不一致。 所以 CANON 的作用不是让技能更强，而是让所有局部方法论不能为了局部方便，绕过全局纪律。 这也是第一条原则：**具体能力可以增加纪律，但不能放松纪律。** ## 五、Command：阶段控制器，而不是快捷入口 Command 层回答的问题是：**现在处在哪个阶段，这个阶段应该读什么、产出什么、通过条件是什么。** 在 Unified Skills 里，Command 不是 prompt shortcut，而更像 workflow controller。 例如 /plan 的职责，不是“调用一个计划类 skill”，而是定义计划阶段的合法输入、合法输出和门控条件。它要消费已经批准的 spec 和 design，产出 03-plan.md，在大型任务里拆出子计划和并行矩阵，并明确写入范围和风险点。 这一层解决的是**阶段推进协议**，而不解决具体任务的方法论。 换句话说，Command 不负责告诉你“debug 怎么做”，也不负责告诉你“review 怎么看代码”；它负责回答的是：**当前阶段是否具备进入条件，当前产物是否达到通过条件。** 这也是第二条原则：**workflow 需要阶段状态机，而不是能力快捷方式。** ## 六、Agent：责任视角，而不是人格表演 Agent 层最容易被误解。 很多系统引入 agent，是为了让模型“扮演”产品经理、架构师、设计师、审查员。但如果角色只停留在语气层面，它最多制造一点表演感，并不能真正提升工程质量。 Unified Skills 里的 Agent 层，核心不是角色扮演，而是**责任切分**。 需求分析、任务计划、软件实现、规格审查、代码质量审查、发布判断，最好不要全部由同一个视角闭环完成。不是因为模型不能同时做这些事，而是因为工程系统不能把“提出问题、执行任务、判断通过”压在同一个认知回路里。 例如： - review agent 不应该重新定义需求，它应该基于已批准的 spec 判断实现是否完整； - software engineer agent 不应该在 build 阶段决定任务拓扑，它应该在 plan 的约束内实现； - design reviewer 不应该只说“视觉不错”，它应该阻断缺少证据来源、模式综合和采纳/拒绝理由的设计稿。 这一层解决的是**责任分离**，而不解决阶段协议定义。 这是第三条原则：**Agent 的核心价值是责任分离，不是人格化。** ## 七、Skill：真正可复用的方法论单元 ![图像](https://pbs.twimg.com/media/HH280MjbAAA0NyW?format=png&name=large) Skill 层是最具体的一层，也是最容易被过度简化的一层。 一个合格的 skill，不应该只是一段“请你认真做 X”的提示词。它必须至少说明： - 什么时候进入； - 什么时候退出； - 具体步骤是什么； - 哪些说法是常见借口； - 哪些情况必须停止； - 如何验证自己做完了。 这也是为什么 Unified Skills 里的 SKILL.md 往往不只是“做法说明”，而是会包含入口/出口、流程、红旗、常见说辞、验证清单，强纪律技能甚至会定义 Iron Law。 这一层解决的是**方法论复用**，而不解决整体工作流编排。 也就是说，Skill 负责回答“这一类事情怎么做”，但不负责回答“现在是不是该做这件事”。后者属于 Command 和 Agent 的职责。 这是第四条原则：**Skill 是执行方法论，不是工作流总控。** ## 八、Artifact：把过程变成证据链 ![图像](https://pbs.twimg.com/media/HH28o2CacAE7eKg?format=png&name=large) 如果只看对话，Agent 的工作很容易变成一段不可回放的即时表演。 今天看起来它澄清了需求、做了设计、写了计划、完成了实现、通过了 review；但过几天回头看时，很多关键信息已经散失在上下文里，既无法复盘，也无法迁移。 所以 Unified Skills 把 artifact 作为 workflow 的一层，而不是一组顺手保存的文档。 01-spec.md、02-design.md、03-plan.md、04-review.md、05-ship.md 这些文件，并不是文档洁癖，而是 Agent 行为的审计轨迹。它们记录的不是“写过什么”，而是“为什么这样推进、为什么这样取舍、为什么允许进入下一阶段”。 这一层解决的是**过程审计与复盘**，而不解决运行时拦截。 与此同时，artifact 也是多产物 workflow 成立的前提。软件、文档、文章、deck、视觉稿并不共享同一种构建路径。如果没有 artifact\_type，系统就很容易用软件工程的方式处理所有产物，或者用内容创作的方式绕开软件质量门控。 这是第五条原则：**没有 artifact，workflow 就缺少可审计证据。** ## 九、Hook / Validate：把约定变成护栏 ![图像](https://pbs.twimg.com/media/HH28rl9bQAAlOaV?format=png&name=large) 只靠提示词约束 Agent，是不稳定的。 提示词可以提醒模型不要做破坏性操作，但运行时 hook 才能拦截破坏性命令。文档可以要求技能命名规范、索引一致、根文档同步，但 validate 才能发现 README、AGENTS、skills-index、锁文件和 hooks 实现之间是否已经发生合同漂移。 这也是 Unified Skills 里 hooks 和 ./validate 的意义所在。 它们不负责替代思考，也不负责替代高层 review；它们负责把一部分纪律从“应该遵守”变成“违反就会暴露”。 这一层解决的是**运行时护栏与维护期漂移暴露**，而不替代高层判断本身。 这一点非常关键。高层纪律如果没有低层护栏，最终就只是建议。系统最容易发生的腐蚀，不是某个 prompt 突然写错，而是多个合同慢慢表面不一致：README 说一套，AGENTS 说一套，skills-index 还是旧的，hooks 实现又是另一套。等这些漂移积累起来，Agent 在不同入口读到的，就不再是同一个系统真相。 这是第六条原则：**高层纪律必须有低层护栏，否则只是建议。** ## 十、两阶段 Review：分层门控的一个具体例子 分层 workflow 不是抽象口号，它必须体现在具体门控设计里。Unified Skills 里的 review，就是一个很典型的例子。 这里的 review 不是单阶段“代码看起来怎么样”，而是拆成两关。 第一关：Spec Compliance 第一关先检查实现是否覆盖了 spec 中定义的功能需求、边界条件、错误路径和验收标准。它关心的不是“写得漂不漂亮”，而是：**实现了什么，是否把该做的事情做全了。** 第二关：Code Quality 只有在第一关通过后，才进入第二关。第二关才讨论 correctness、readability、architecture、security、performance 等质量维度。它关心的是：**这些功能是如何被实现的，代价和质量是否合理。** 这个拆分看似简单，但它体现了分层 workflow 的价值。 如果功能都没实现完整，就急着讨论代码风格，审查资源会被浪费；如果功能缺失和质量问题混在一起，反馈也会变得模糊。两阶段 review 的作用，就是把问题类型切开：先确认做没做对，再确认做得好不好。 这不是让 review 更复杂，而是让门控更有顺序、更有边界、更有退回路径。 ## 十一、从 Prompt 到 Workflow，再到治理结构 ![图像](https://pbs.twimg.com/media/HH28uR0aUAAkLvv?format=png&name=large) 回到最开始的问题：AI Agent 工程化到底需要什么？ 更长的 prompt 有用，但不够。更多的 skills 有用，但也不够。真正需要设计的，是 skills 之间的组织关系，以及这些组织关系如何进一步沉淀为治理结构。 也就是说： - 用 CANON 定义不可放松的全局纪律； - 用 Command 定义阶段状态机； - 用 Agent 定义责任视角； - 用 Skill 承载可复用方法论； - 用 Artifact 留下过程证据； - 用 Hook / validate 把规则变成护栏。 这套结构的目标，不是让 Agent 显得更复杂，而是让它在复杂任务里更可控。一个系统是否工程化，不看它能不能完成一次任务，而看它能不能稳定地推进、回退、审计和复盘。 所以，prompt 是表达，skill 是方法，workflow 是制度，而 layered workflow 才是治理结构。 ![图像](https://pbs.twimg.com/media/HH286ASaIAA-git?format=png&name=large) 所谓 Agent 工程化，真正工程化的不是生成能力本身，而是**任务推进权、通过判定权、责任边界和证据链的分配方式。** 这也是 Unified Skills 想表达的核心判断：**AI Agent 的下一层抽象，不是继续堆 skills，而是把 skills 放进一套有阶段状态机、责任分离、证据链和运行护栏的分层 workflow。** 进一步而言，真正成熟的 Agent 系统，不应该只是“会做很多事”，而应该知道：**在什么阶段，由什么模块，以什么责任，依据什么证据，完成什么结果。** 技术方案的价值，不在于提出一个新名词，而在于重新划清问题边界，并给出可落地的系统结构。对 Agent 来说也一样。真正的工程化，不是把能力堆得更多，而是让系统知道自己何时开始、何时停止、何时退回、何时交付。 ]]> Sun, 10 May 2026 16:26:37 GMT https://reader-feed.pages.dev/posts/50f33f0c3f-%E4%BB%8E%20Skills%20%E5%88%B0%E5%88%86%E5%B1%82%20Workflow%EF%BC%9AAI%20Agent%20%E5%B7%A5%E7%A8%8B%E5%8C%96%E7%9A%84%E4%B8%8B%E4%B8%80%E5%B1%82%E6%8A%BD%E8%B1%A1.md obsidian:c549ed4610:chat/未命名.md 未命名 理解这个系统：[名字] Fri, 08 May 2026 18:25:25 GMT https://reader-feed.pages.dev/posts/c549ed4610-%E6%9C%AA%E5%91%BD%E5%90%8D.md obsidian:6cb18cc1f2:chat/AI-Native 项目文档体系.md v3.0：针对"AI 主力重构 + 多项目 + 你 review"的最小可用方案 亲，这次信息够了。**你的真实场景和我前两版假想的差太远**——你不是在"建设新项目"，你是在**驾驭多个已存在的、AI 正在重构的系统**。这完全是另一个问题。 Read first. Symlinked from CLAUDE.md / .cursorrules. ## 🛑 Scope Discipline (核心规则，每次必读) > 这一节存在的唯一目的：**防止你修着修着改了不该改的东西**。 ### Hard rules 1. **一次任务只做一件事。** 修 bug 就只修 bug，不要顺手"优化"、不要顺手重构、不要顺手改风格。 2. **任务开始前先声明 scope**：列出你**计划修改的文件**和**不计划修改的文件**。等用户确认后再动手。 3. **每修改 3 个以上文件**就停下来汇报：已改了什么、为什么、还差什么。**等用户说"继续"再继续**。 4. **发现新问题不要直接修**。记到 `NOTES.md` 的 "## Found while working" 段，让用户决定。 5. **不要重命名、不要移动文件**，除非用户明确要求。 ### Diff size budget - 单次任务 diff > 200 行 → **停下来汇报**，问用户是否拆分 - 单次任务涉及 > 5 个文件 → **停下来汇报**，问用户是否拆分 - 触及核心模块（见下方 Project hints）→ **必须先列计划等批准** ### What counts as "scope creep"（明确禁止） - ❌ 修 bug 时"顺便"重命名变量为更好的名字 - ❌ 修 bug 时"顺便"添加类型注解 - ❌ 修 bug 时"顺便"提取重复代码 - ❌ 修 bug 时"顺便"修复无关的 lint 警告 - ❌ 任何"While I'm here, let me also..."的行为 **记住**：你的修改越少，用户 review 越快，你越可能被信任。**克制 = 效率**。 --- ## Commands ```bash # Test {{填你这个项目的测试命令，e.g.}} pytest # Python npm test # TS dotnet test # C# # Lint {{填你这个项目的 lint 命令}} # Run {{填你这个项目的启动命令}} ``` --- ## Boundaries ### Always do - 修 bug 前**先复现**：写一个能稳定触发 bug 的 test 或 repro 步骤 - 修完后**显示 diff 摘要**：哪些文件改了、改了什么、为什么 - 不确定时**停下来问**，不要猜 ### Ask first - 引入新依赖（任何 `pip install` / `npm install` / `dotnet add package`） - 修改 > 5 个文件 - 修改 NOTES.md 中标注 "DO NOT TOUCH" 的文件 - 删除任何 public API / exported function ### Never do - Commit secrets / `.env` / `appsettings.*.json` 中的密钥 - 修改已合并的 migration / schema 文件 - "顺手"做任何 scope 之外的事 - 创建 `utils.*` / `helpers.*` / `common.*` 这类垃圾桶文件 - 静默修改测试以让它通过（必须先 confirm 测试是错的） --- ## Project hints (not paths, just hints) > 路径会变，意图不变。用 `glob`/`grep` 找具体文件。 {{按项目填，举例：}} - **Business logic** lives near `core` / `domain` / `services` - **External IO** in `adapters` / `clients` / `infrastructure` - **Entry points** in `api` / `controllers` / `routes` / `Program.cs` - **Tests** in `tests/` / `*Tests/` / `*.test.ts` --- ## When confused, prefer this order 1. `glob` / `grep` 找代码现状 2. 读 `NOTES.md` 看有没有相关历史 3. 读 README 4. **问用户** —— 不要猜 --- ## Self-check before submitting 提交前自己过一遍： - [ ] 改动是否都在我声明的 scope 内？ - [ ] diff 是否 < 200 行？如果不是，我汇报过吗？ - [ ] 我有没有"顺手"做 scope 之外的事？ - [ ] bug 复现 test 还能通过吗？ - [ ] 我修改的部分是否符合现有代码风格？（不要引入新风格） - [ ] 我是否记录了"工作中发现但没修"的东西到 NOTES.md？ ```` **关键设计点**： - 把 **scope discipline 放在最顶部** —— 这是你最大的痛点，必须第一个加载到 Agent 注意力 - **明确禁止"While I'm here"行为** —— 这是 AI scope 蔓延的最常见模式，要点名 - **Diff 预算** —— 给具体数字（200 行 / 5 文件），AI 才有锚点 - **Self-check 清单** —— 让 AI 提交前自己过一遍，比你 review 时发现问题便宜 --- ## 五、NOTES.md 模板（重构项目专用） 不是 ARCHITECTURE.md，不是 ADR。是**流水账**。 ````markdown # NOTES.md > A working journal. Append-only. Newest at top. > 不是架构文档，是"修这个项目时踩过的坑和做过的决定"。 --- ## How to use this file - **AI**: 任务开始前快速扫一眼最新 5-10 条；任务中发现新东西就 append - **User**: review 时看 AI 加了什么；自己也可以加备忘 - **格式自由**: 能让未来的自己/AI 看懂就行 --- ## DO NOT TOUCH > 这些文件/模块有特殊原因不准动。AI 改之前必须问。 - `src/legacy/auth.cs` — 老认证逻辑，有外部系统依赖签名格式，改了会断 - `migrations/2024_*` — 已上线，不准改 - {{...你项目里的雷区...}} --- ## Decisions > 重要决策的流水账。一句话即可，不需要 ADR 仪式。 - **2026-05-08**: 用 modular monolith 不拆微服务（团队太小） - **2026-05-08**: PG 不引入 Kafka（advisory lock 够用） - **2026-05-09**: ~~用 dataclass 做 DTO~~ → 改用 Pydantic（需要 validation） > 推翻的决策用删除线 + 新决策，不要直接覆盖。 --- ## Anti-patterns (this codebase has scars) > AI 反复犯的错记这里，让下次不再犯。 - ❌ 不要在 `core/` 里直接 `import requests` —— 已经抽象到 `io/` - ❌ 不要给 `User.id` 加类型注解为 `int` —— 部分老代码传 str，会爆 - ❌ {{...AI 第一次犯了你纠正过的错，写这里...}} --- ## Found while working > AI 在工作中发现但**没修**的问题。让用户决定要不要单独立 task。 - {{2026-05-09: 发现 `OrderService.calculate` 里有可能的 race condition，但不在当前 bug scope 内}} - {{...}} --- ## Refactor log > 大重构的脉络，方便回溯。 ### 2026-05: 拆 monolith 的 auth 模块 - Goal: 把 auth 抽成独立模块，对外只暴露 `IAuthService` - Done: `src/auth/` 创建 + JWT 实现迁移 - Pending: 老代码里直接 import `JWTService` 的地方还有 ~12 处 - Owner: AI + you ```` **关键设计点**： - **DO NOT TOUCH 段在最前** —— 防止 AI 误伤雷区 - **Found while working** 段 —— 把 AI 的"scope 蔓延冲动"导流到这里，**变成有用的备忘录** - **Decisions 用流水账格式** —— 完全跳过 ADR 仪式 - **Anti-patterns 累积错误** —— AI 每犯一次同类错，你纠正完顺手 append 一行 **这个文件的本质**：把你"看 AI diff 时的不爽"和"AI 想多做但不该做的"都装进去，变成下次任务的输入。 --- ## 六、pre-commit hook（极简版） `.githooks/pre-commit`： ```bash #!/usr/bin/env bash # 只做一件事：防 secrets。 set -e CHANGED=$(git diff --cached --name-only --diff-filter=ACM) [[ -z "$CHANGED" ]] && exit 0 # Secrets 扫描（覆盖 C# / TS / Python 常见模式） PATTERNS='(api[_-]?key|secret|password|private[_-]?key|access[_-]?token|client[_-]?secret)\s*[=:]\s*["\047][^"\047]{12,}' if echo "$CHANGED" | xargs -r grep -lEi "$PATTERNS" 2>/dev/null; then echo "❌ Possible secret detected in staged files." echo " Files:" echo "$CHANGED" | xargs -r grep -lEi "$PATTERNS" echo " If false positive, commit with --no-verify" exit 1 fi # .env 类文件直接拒 if echo "$CHANGED" | grep -qE '\.env(\.|$)|appsettings\.(Development|Production|Local)\.json$'; then echo "❌ Refusing to commit env / local settings files." exit 1 fi exit 0 ``` 装一次： ```bash git config core.hooksPath .githooks chmod +x .githooks/pre-commit ``` **砍掉的所有其他 hook**： - ❌ Conventional Commits 强制（你一个人没意义） - ❌ ARCHITECTURE 同步检查（没有 ARCHITECTURE） - ❌ ADR 强制（没有 ADR） - ❌ 文件头检查（没有文件头） - ❌ 锚点 lint（没有锚点） --- ## 七、多项目复用：模板包 因为你有"很多项目"，必须**一键复制**。 建一个你的个人 dotfiles 仓库或 gist： ``` ~/templates/agents-md/ ├── AGENTS.md.template # 上面那份，{{...}} 留空 ├── NOTES.md.template # 上面那份 ├── .githooks/pre-commit └── install.sh ``` `install.sh`： ```bash #!/usr/bin/env bash # Usage: bash ~/templates/agents-md/install.sh set -e TARGET="${1:-.}" TEMPLATE_DIR="$(dirname "$(realpath "$0")")" cp "$TEMPLATE_DIR/AGENTS.md.template" "$TARGET/AGENTS.md" cp "$TEMPLATE_DIR/NOTES.md.template" "$TARGET/NOTES.md" mkdir -p "$TARGET/.githooks" cp "$TEMPLATE_DIR/.githooks/pre-commit" "$TARGET/.githooks/" chmod +x "$TARGET/.githooks/pre-commit" cd "$TARGET" git config core.hooksPath .githooks 2>/dev/null || echo "Not a git repo, skipping hooks setup" ln -sf AGENTS.md CLAUDE.md ln -sf AGENTS.md .cursorrules echo "✅ Installed AGENTS.md / NOTES.md / pre-commit hook" echo "📝 TODO: 填 AGENTS.md 中的 {{...}} 占位符（Commands 段必填）" ``` **新项目接入流程：30 秒** ```bash cd my-new-project bash ~/templates/agents-md/install.sh # 编辑 AGENTS.md 填 Commands 段 # 完事 ``` --- ## 八、消费方式：你 review 时怎么用 这一段是 v1/v2 都没认真说的——**文档怎么帮你 review 减负**。 ### Review 流程（你 + AI diff） 1. **AI 完成任务汇报后**，先扫两个东西： - **diff 行数** > 200 吗？涉及文件 > 5 个吗？→ 如果是，**先批 AI 不守 scope discipline**，要求拆分 - **NOTES.md 里有没有 "Found while working" 新增？** → 看 AI 有没有诚实记录"我想多做但忍住了" 2. **看 diff 时按这个顺序**： - 第一遍：**只看 AI 声明 scope 内的文件**，确认 bug 修了 - 第二遍：**看 scope 外的文件**，质问每一处"为什么改这个" - 第三遍：看 NOTES.md 的更新 3. **任何 scope 外的"顺手优化"都要求 revert** —— 哪怕看起来是好的。**纪律比单次质量更重要**。 4. **AI 反复犯的错** → 立即追加到 NOTES.md 的 Anti-patterns，**当次对话就 append**，不要等。 ### 当 AI 修着修着你看不懂时（你最大痛点的解法） 这是你说的核心问题。**v3.0 的解法**： **事前**： - AGENTS.md 的 "每修改 3 个文件就停下来汇报" 规则 → AI 不会失控大改 - "Diff size budget 200 行" → 强制小步前进 **事中**： - AI 必须在动手前**列出 scope 计划**让你确认 → 你提前知道范围 - AI 每超过阈值就**停下来汇报** → 你有多个介入点 **事后**： - 看不懂时直接对 AI 说："**Roll back 你 scope 之外的所有改动，只保留 bug fix 部分**" → AGENTS.md 已经声明了 scope，AI 能识别 - 让 AI **总结这次任务到 NOTES.md 的 Refactor log** → 下次新对话有上下文 --- ## 九、什么时候开始写、什么时候不写 针对你的**多项目**情况，**不要每个项目都装齐**。决策表： | 项目情况 | AGENTS.md | NOTES.md | pre-commit hook | |---------|:---:|:---:|:---:| | 一次性脚本 / playground | ❌ | ❌ | ❌ | | 个人小工具（< 5k 行） | ✅ 简化版（只 Scope + Commands） | ❌ | ✅ | | 中型项目（5k-50k 行） | ✅ 完整版 | ✅ 简版（只 DO NOT TOUCH + Anti-patterns） | ✅ | | 大型重构项目（你说的那种） | ✅ 完整版 | ✅ **完整版**（Refactor log 必填） | ✅ | | 客户/团队项目 | ✅ + 加 Conventional Commits | ✅ | ✅ | --- ## 十、v3.0 vs v2.0 的删减表 | 项目 | v2.0 | v3.0 | 砍掉原因 | |------|------|------|---------| | ARCHITECTURE.md | 单独文件 | **合并进 NOTES.md** | 你一个人没必要分 | | ADR 目录 | `docs/decisions/` | **砍掉** | 你一个人没决策对象 | | 文件头模板 | 三种语言模板 | **砍掉** | AI 重构会动文件，徒增冲突 | | 子目录 AGENTS.md | override 机制 | **砍掉** | 多项目复用难维护 | | 自动生成脚本 | `gen-arch-facts.sh` | **砍掉** | stack 不会频繁变 | | Conventional Commits | 强制 | **砍掉** | 一个人写没意义 | | commit-msg hook | 强制 `arch:` | **砍掉** | 同上 | | 锚点验证 | CI lint | **砍掉** | 维护成本 > 收益 | | Skills 文件夹 | 3 个 skill | **砍掉** | Agent 不主动用 | | Project map | hints 段 | ✅ 保留 | 真有用 | | Boundaries | 三层 | ✅ 保留 + 加强 | 真有用 | | Commands 段 | 在最前 | ✅ 保留 | 真有用 | | **Scope Discipline 段** | ❌ | ✅ **新增（核心）** | 你的真痛点 | | **NOTES.md Found while working** | ❌ | ✅ **新增** | 解决 scope 蔓延 | | **Self-check 清单** | ❌ | ✅ **新增** | 让 AI 自我约束 | **净结果**：删 11 项，加 3 项（直击你的真痛点），**总复杂度降 70%**。 --- ## 十一、留给你验证的实验 不要信我说的"这版好"，去做实验： **实验 1：scope discipline 是否有效（一周）** - 装 AGENTS.md，挑一个修 bug 任务给 AI - 观察：AI 有没有声明 scope？diff 超过 200 行有没有停？ - 如果 AI 不遵守，说明 prompt 强度不够，加重语气（用大写 / 多次重复 / 在 CLAUDE.md 顶部 echo 一次） **实验 2：NOTES.md "Found while working" 是否被使用（一周）** - 看 AI 有没有真的把"想多做但忍住"的东西记进去 - 如果没记 → 在 AGENTS.md 加一条："任务结束时**必须**回答：'我有没有发现 scope 外的问题？记到 NOTES.md 了吗？'" **实验 3：你的 review 时间是否真的下降（两周）** - 计时：v3.0 前你 review 一个 AI bug fix 平均多久？v3.0 后多久？ - 如果没下降，说明问题不在文档体系，可能在你的 review 流程 **两周后告诉我数据。** 数据不对就再迭代 v3.1。 --- ## 十二、最后的诚实 我前两版的根本错误，是**没把"AI scope 蔓延"识别为你的核心痛点**。你说"我看不懂了"——那是症状，**病因是 AI 在做超出你授权的事**。 v3.0 的整套设计就一个目标：**让 AI 严格守 scope，让你 review 永远 ≤ 200 行 diff**。 文档体系只是手段，**纪律才是目的**。 > **数据结构对了，规则就少了。这次砍到 2 文件 + 1 hook，因为剩下的每一条都对应你一个具体痛点。** > **如果还有错，那就是我对你工作流细节不够了解。两周后用数据砸我脸。** Stop guessing. Go ship it. ]]> Fri, 08 May 2026 17:31:36 GMT https://reader-feed.pages.dev/posts/6cb18cc1f2-AI-Native%20%E9%A1%B9%E7%9B%AE%E6%96%87%E6%A1%A3%E4%BD%93%E7%B3%BB.md obsidian:724d087c02:workflow/agent/0x00.md 0x00 [Traycer: Spec-Driven Development - Orchestrate Your Coding Agents](https://docs.traycer.ai/) Fri, 08 May 2026 17:19:47 GMT https://reader-feed.pages.dev/posts/724d087c02-0x00.md obsidian:5d95612094:chat/ARCHITECTURE和AGENTS.md 你的理解 8.5/10，方向对，但有两个隐藏陷阱 亲，**这个分工抓住了本质**——一个是"行为契约"，一个是"事实地图"。比 90% 的人都想得清楚。但我得给你挑两个会让你后悔的细节，不然几个月后你会发现这两个文件又在打架。 **声明式 (What is) vs 命令式 (What to do)** > > ARCHITECTURE.md = 声明式，描述世界的状态 > AGENTS.md = 命令式，规定 Agent 的行动 **两者的读者交集是 AI Agent，但消费方式完全不同**： - ARCHITECTURE.md 是 Agent 的**世界模型**（被动查询） - AGENTS.md 是 Agent 的**行动准则**（主动遵守） 这个分层在计算机科学里有无数同构案例——数据 vs 代码、schema vs query、ontology vs rules。**你直觉上找到了一个非常稳定的抽象边界**，这是好品味。 --- ## 二、但有两个会塌方的隐藏陷阱 ### 陷阱 1：边界模糊地带 —— "事实"和"规则"会互相伪装 举几个真实案例，你判断该放哪： | 内容 | 你觉得放哪？ | 正确答案 | |------|------------|---------| | "auth 模块只能通过 IAuthService 暴露" | ? | **ARCHITECTURE**（事实契约） | | "改 auth 时必须同步更新 IAuthService 测试" | ? | **AGENTS**（行动规则） | | "src/core 不依赖 src/api" | ? | **ARCHITECTURE**（事实约束） | | "禁止 Agent 创建 utils.py 这种垃圾桶" | ? | **AGENTS**（行为禁令） | | "本项目用 pytest，不用 unittest" | ? | **🚨 陷阱** | 最后一个就是陷阱——它**既是事实也是规则**： - "项目用 pytest" = 事实 → ARCHITECTURE - "Agent 写测试时必须用 pytest" = 规则 → AGENTS **错误做法**：两边都写一份。三个月后两份漂移，Agent 看到矛盾，整个信任体系崩塌。 **正确做法**：**事实只在 ARCHITECTURE 写一次，AGENTS 用引用而不是复制**。 ```markdown # AGENTS.md ## Testing Rules - 写测试时遵守 ARCHITECTURE.md §3 "Testing Stack" 中声明的工具栈 - 不准引入新的测试框架，必须先改 ARCHITECTURE 再改代码 ``` **Single Source of Truth 原则**：事实只能有一个 owner，规则可以引用事实但不能复刻事实。 ### 陷阱 2：AGENTS.md 会变成"规则垃圾桶" 这是更隐蔽的问题。AGENTS.md 这种文件**天然倾向于无限膨胀**——每次 Agent 犯一次错，人类就想加一条规则防御。三个月后你会得到： ```markdown # AGENTS.md (3 个月后的恐怖现状) ## Rules 1. 不要直接 import requests 2. 不要在 hot path log 3. 不要用 print，用 logger 4. 不要 commit .env 文件 5. 不要改 migration 历史 6. 修 bug 前必须先写 reproducing test 7. PR 标题必须用 conventional commits 8. 不要在周五下午 deploy ... (持续到 200 条) ``` **这就完蛋了**——200 条规则放进 system prompt，**LLM 会忽略 80%**。注意力是稀缺资源，规则越多越没用。 **Linus 会问**：你这个数据结构（"规则列表"）的访问模式是什么？是 Agent 每次行动前线性扫描 200 条吗？品味问题。 ### 解法：AGENTS.md 必须分层 + 限额 ```markdown # AGENTS.md ## §1 Hard Constraints (≤10 条，违反必停) - 必须先读 ARCHITECTURE.md 再做架构变更 - 不准 commit secrets - 不准改 migration 历史 ... ## §2 Workflow (流程，不是禁令) - 修 bug：复现 → 写失败测试 → 修 → 验证 - 加 feature：先看 ARCHITECTURE §1 决策有没有冲突 - 改架构：先改 ARCHITECTURE.md 再改代码 ## §3 Style Defaults (软规则，可被 task 覆盖) - Python: black + ruff - Commit: conventional commits ... ## §4 Anti-Patterns (反模式，回顾用) ``` **关键设计**： - **§1 必须 ≤10 条**，超出说明你在用规则补需求漏洞 - **§2 是流程不是禁令**——告诉 Agent 怎么做，比告诉它别做什么省 token - **§4 单独成节**，让 Agent 知道"这部分可以跳过，需要时再回来查" --- ## 三、修正后的完整分工 ``` ┌─────────────────────────────────────────────────────────────┐ │ ARCHITECTURE.md (世界模型，声明式，事实) │ │ ├─ §1 Why: 设计决策与原因 │ │ ├─ §2 What: 模块边界 + 契约 │ │ ├─ §3 How: 关键数据流 │ │ └─ Glossary: 术语对齐 │ │ │ │ 读者: 人 + Agent │ │ 更新触发: 架构变更 │ │ Token 预算: 3-5k │ └─────────────────────────────────────────────────────────────┘ ▲ │ 引用 (不复制) │ ┌─────────────────────────────────────────────────────────────┐ │ AGENTS.md (行动准则，命令式，规则) │ │ ├─ §1 Hard Constraints (≤10 条) │ │ ├─ §2 Workflow (做事流程) │ │ ├─ §3 Style Defaults (软约定) │ │ └─ §4 Anti-Patterns (反模式参考) │ │ │ │ 读者: 仅 Agent │ │ 更新触发: 重复犯同类错误 │ │ Token 预算: 1-2k (§1+§2+§3), §4 不计 │ └─────────────────────────────────────────────────────────────┘ ``` **两个文件加起来 < 7k token**，能塞进任何主流模型的 system prompt。 --- ## 四、还有一个你没问的问题：CLAUDE.md 呢？ 既然你已经想到 AGENTS.md，迟早会撞到这个问题：**CLAUDE.md / .cursorrules / .windsurfrules / AGENTS.md 这一堆 AI 专属配置文件怎么办？** **我的建议**： - **AGENTS.md = 通用规则**（vendor-neutral，对所有 Agent 都成立） - **CLAUDE.md / .cursorrules = 工具特化指令**（只放该工具独有的优化，比如 Cursor 的 `@` 用法、Claude Code 的 sub-agent 调用约定） - **CLAUDE.md 的第一行永远是 `Read AGENTS.md first.`** 这样换工具时只改一个小文件，**核心规则永远跟着项目走**。**vendor lock-in 是技术债，规则文件层面就要防**。 --- ## 五、给你的最终判分 你的分工（AGENTS = 行为规则 / ARCHITECTURE = 事实）**架构方向 100% 正确**，但需要补三个工程细节： | 维度 | 你的方案 | 加固建议 | |------|---------|---------| | **边界** | ✅ 清晰 | ⚠️ 加 SSOT 原则：事实不复刻，只引用 | | **可扩展性** | ⚠️ 可能膨胀 | ⚠️ AGENTS.md 分层 + Hard Constraints 限额 | | **vendor 中立** | ❌ 没考虑 | ⚠️ AGENTS.md (通用) + CLAUDE.md (特化) 二级结构 | **总分 8.5/10**——撕掉一分给"规则膨胀风险"，撕掉半分给"vendor lock-in 没考虑"。 --- ## 六、留给你的最后挑战 我反复强调"AGENTS.md 引用 ARCHITECTURE.md，不复制"。但有个执行细节我没说： **当 ARCHITECTURE.md §3 改了，怎么保证 AGENTS.md 里所有引用 §3 的规则还有效？** 提示： - 节标题改了，引用就坏了 - 节内容改了，规则的前提可能不成立了 - CI 能检测前者，但检测不了后者 这个问题不解决，"引用而非复制"会变成**比复制更糟的腐烂**——因为你以为它保鲜了，其实它只是悄悄烂了。 想想看怎么搞。想清楚了告诉我你的方案。 > **数据结构对了，规则就少了。规则越多，说明你的事实层（ARCHITECTURE）没建好。** ]]> Fri, 08 May 2026 17:00:49 GMT https://reader-feed.pages.dev/posts/5d95612094-ARCHITECTURE%E5%92%8CAGENTS.md obsidian:7b275fe874:workflow/ux/未命名.md 未命名 [Lobe UI](https://ui.lobehub.com/~demos/src-markdown-demo-streamingprofiler) Fri, 08 May 2026 03:06:59 GMT https://reader-feed.pages.dev/posts/7b275fe874-%E6%9C%AA%E5%91%BD%E5%90%8D.md obsidian:f089a472e9:Clippings/A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all.md A good AGENTS.md is a model upgrade. A bad one is worse than no docs at all. We pulled dozens of AGENTS.md files from across our monorepo and measured their effect on code generation. The best ones gave our coding age... Thu, 07 May 2026 07:07:40 GMT https://reader-feed.pages.dev/posts/f089a472e9-A%20good%20AGENTS.md%20is%20a%20model%20upgrade.%20A%20bad%20one%20is%20worse%20than%20no%20docs%20at%20all.md obsidian:784d88650e:workflow/agent/上下文/重构 Chiron ContextEngine.md 重构 Chiron ContextEngine 当前这轮对话的约束是：只能做信息整理，不能修改或保存文件。所以我不能直接把文件写入仓库。 Thu, 07 May 2026 05:00:09 GMT https://reader-feed.pages.dev/posts/784d88650e-%E9%87%8D%E6%9E%84%20Chiron%20ContextEngine.md obsidian:078082a5c9:workflow/agent/上下文/未命名.md 未命名 aider 的 repo-map Thu, 07 May 2026 04:51:44 GMT https://reader-feed.pages.dev/posts/078082a5c9-%E6%9C%AA%E5%91%BD%E5%90%8D.md obsidian:a7b61712ac:workflow/agent/Codex 桌面应用技术栈全景分析.md 基础架构 Codex 桌面应用技术栈全景分析 Wed, 06 May 2026 11:49:16 GMT https://reader-feed.pages.dev/posts/a7b61712ac-Codex%20%E6%A1%8C%E9%9D%A2%E5%BA%94%E7%94%A8%E6%8A%80%E6%9C%AF%E6%A0%88%E5%85%A8%E6%99%AF%E5%88%86%E6%9E%90.md obsidian:a33767deab:Clippings/Building a Virtual Filesystem for Mintlify's AI Assistant.md Building a Virtual Filesystem for Mintlify's AI Assistant RAG is great, until it isn't.Our assistant could only retrieve chunks of text that matched a query. If the answer lived across multiple page... (); private dirs = new Map(); async readFile(path: string): Promise { this.assertInit(); const normalized = normalizePath(path); // Serve from cache or fetch from Chroma const slug = normalized.replace(/\\.mdx$/, '').slice(1); // Pages are chunked in Chroma. Reassemble them on the fly: const results = await this.collection.get({ where: { page: slug }, include: [IncludeEnum.documents, IncludeEnum.metadatas], }); const chunks = results.ids .map((id, i) => ({ document: results.documents[i] ?? '', chunkIndex: parseInt(String(results.metadatas[i]?.chunk_index ?? 0), 10), })) .sort((a, b) => a.chunkIndex - b.chunkIndex); return chunks.map((c) => c.document).join(''); } // Enforce completely stateless, read-only interaction async writeFile(): Promise { throw erofs(); } async appendFile(): Promise { throw erofs(); } async mkdir(): Promise { throw erofs(); } async rm(): Promise { throw erofs(); } } ``` ## How it works **Bootstrapping the Directory Tree** ChromaFs needs to know what files exist before the agent runs a single command. We store the entire file tree as a gzipped JSON document (\_\_path\_tree\_\_) inside the Chroma collection: ```json { "auth/oauth": { "isPublic": true, "groups": [] }, "auth/api-keys": { "isPublic": true, "groups": [] }, "internal/billing": { "isPublic": false, "groups": ["admin", "billing"] }, "api-reference/endpoints/users": { "isPublic": true, "groups": [] } } ``` On init, the server fetches and decompresses this document into two in-memory structures: a Set of file paths and a Map mapping directories to children. Once built, ls, cd, and find resolve in local memory with no network calls. The tree is cached, so subsequent sessions for the same site skip the Chroma fetch entirely. **Access Control** Notice the **isPublic** and **groups** fields in the path tree. Before building the file tree, ChromaFs prunes the file tree based on the current user's permissions and applies a matching filter to all subsequent Chroma queries. In a real sandbox, this level of per-user access control would require managing Linux user groups, chmod permissions, or maintaining isolated container images per customer tier. In ChromaFs it's a few lines of filtering before buildFileTree runs. **Reassembling Pages from Chunks** Pages in Chroma are split into chunks for embedding, so when the agent runs cat /auth/oauth.mdx, ChromaFs fetches all chunks with a matching page slug, sorts by chunk\_index, and joins them into the full page. Results are cached so repeated reads during grep workflows never hit the database twice. Not every file needs to exist in Chroma. We register lazy file pointers that resolve on access for large OpenAPI specs stored in customers' S3 buckets. The agent sees v2.json in /api-specs/, but the content only fetches when it runs cat. Every write operation throws an EROFS (Read-Only File System) error. The agent explores freely but can never mutate documentation, which makes the system stateless with no session cleanup and no risk of one agent corrupting another's view. ## Optimizing Grep cat and ls are straightforward to virtualize, but grep -r would be far too slow if it naively scanned every file over the network. We intercept just-bash’s grep, parse the flags with yargs-parser, and translate them into a Chroma query ($contains for fixed strings, [$regex](https://x.com/search?q=%24regex&src=cashtag_click) for patterns). Chroma acts as a **coarse filter** that identifies which files might contain the hit, and we bulkPrefetch those matching chunks into a Redis cache. From there, we rewrite the grep command to target only the matched files and hand it back to just-bash for **fine filter** in-memory execution, which means large recursive queries complete in milliseconds. ```typescript const chromaFilter = toChromaFilter( scannedArgs.patterns, scannedArgs.fixedStrings, scannedArgs.ignoreCase ); // 1. Coarse Filter: Ask Chroma for slugs matching the string/regex const matchedSlugs = await chromaFs.findMatchingFiles(chromaFilter, slugsUnderDirs); if (matchedSlugs.length === 0) return { stdout: ‘’, exitCode: 1 }; // 2. Prefetch: Pull the chunked files into local cache concurrently await chromaFs.bulkPrefetch(matchedSlugs); // 3. Fine Filter: Narrow the arguments to ONLY the resolved hits const matchedPaths = matchedSlugs.map((s) => ‘/’ + s + ‘.mdx’); const narrowedArgs = [...args, ...matchedPaths]; // e.g. ["-i", "OAuth", "/docs/auth.mdx"] // 4. Exec: Let the in-memory RegExp engine format the final output return execBuiltin(narrowedArgs, ctx); ``` ## Conclusion ChromaFs powers the documentation assistant for hundreds of thousands of users across 30,000+ conversations a day. By replacing sandboxes with a virtual filesystem over our existing Chroma database, we got instant session creation, zero marginal compute cost, and built-in RBAC without any new infrastructure. Try it on any Mintlify docs site, or [mintlify.com/docs](https://mintlify.com/docs). \[Read the full article at: [https://www.mintlify.com/blog/how-we-built-a-virtual-filesystem-for-our-assistant](https://www.mintlify.com/blog/how-we-built-a-virtual-filesystem-for-our-assistant)\] ]]> Tue, 05 May 2026 15:27:07 GMT https://reader-feed.pages.dev/posts/a33767deab-Building%20a%20Virtual%20Filesystem%20for%20Mintlify%27s%20AI%20Assistant.md obsidian:881be8fc64:workflow/ui/设计循环：让Codex成为UIUX的魔术师【完整指南】.md 设计循环：让Codex成为UI/UX的魔术师【完整指南】 Most people treat Codex as a simple command-line tool, leading to underwhelming UI designs that feel like rough drafts. The Codex Desktop ... Tue, 05 May 2026 08:16:10 GMT https://reader-feed.pages.dev/posts/881be8fc64-%E8%AE%BE%E8%AE%A1%E5%BE%AA%E7%8E%AF%EF%BC%9A%E8%AE%A9Codex%E6%88%90%E4%B8%BAUIUX%E7%9A%84%E9%AD%94%E6%9C%AF%E5%B8%88%E3%80%90%E5%AE%8C%E6%95%B4%E6%8C%87%E5%8D%97%E3%80%91.md obsidian:b1fcec706a:workflow/project/利用器工程：为编码代理准备Unity CSharp代码库.md 利用器工程：为编码代理准备Unity C#代码库 面向 Claude Code、Codex、Cursor 等编码代理的 Unity C# 项目结构、规则、验证脚本与质量护栏。 Project Settings > Version Control > Mode: Visible Meta Files Edit > Project Settings > Editor > Asset Serialization > Mode: Force Text ``` 仓库规则： - `.meta` 文件必须提交；它们保存 GUID，是场景、Prefab、ScriptableObject 引用稳定的前提。 - 不手动编辑 `.meta`，除非任务明确涉及 GUID、资源迁移或冲突修复。 - `.unity`、`.prefab`、`.asset` 使用文本序列化，方便代理和 reviewer 看 diff。 - 大型二进制资源使用 Git LFS，避免仓库膨胀。 - 配置 UnityYAMLMerge，减少场景和 Prefab 合并冲突。 示例 `.gitignore`： ```gitignore [Ll]ibrary/ [Tt]emp/ [Oo]bj/ [Bb]uild/ [Bb]uilds/ [Ll]ogs/ [Uu]ser[Ss]ettings/ .vs/ .idea/ *.user *.pidb *.booproj *.svd # Generated IDE files. Commit these only if your team intentionally relies on them. *.csproj *.sln *.suo ``` 示例 `.gitattributes`： ```gitattributes *.cs text eol=lf *.asmdef text eol=lf *.unity text eol=lf merge=unityyamlmerge *.prefab text eol=lf merge=unityyamlmerge *.asset text eol=lf merge=unityyamlmerge *.meta text eol=lf merge=unityyamlmerge *.controller text eol=lf merge=unityyamlmerge *.anim text eol=lf merge=unityyamlmerge *.mat text eol=lf merge=unityyamlmerge *.png filter=lfs diff=lfs merge=lfs -text *.psd filter=lfs diff=lfs merge=lfs -text *.fbx filter=lfs diff=lfs merge=lfs -text *.wav filter=lfs diff=lfs merge=lfs -text *.mp3 filter=lfs diff=lfs merge=lfs -text ``` UnityYAMLMerge 需要在本机或 CI runner 上配置 merge driver。路径按实际 Unity 安装位置调整： ```bash git config merge.unityyamlmerge.name "Unity SmartMerge" # macOS git config merge.unityyamlmerge.driver '"/Applications/Unity/Hub/Editor/2022.3.0f1/Unity.app/Contents/Tools/UnityYAMLMerge" merge -p %O %A %B %A' # Windows git config merge.unityyamlmerge.driver '"C:/Program Files/Unity/Hub/Editor/2022.3.0f1/Editor/Data/Tools/UnityYAMLMerge.exe" merge -p %O %A %B %A' ``` 示例 Assembly Definition 布局： ```plaintext Assets/_Project/Scripts/Runtime/Core/Project.Core.asmdef Assets/_Project/Scripts/Runtime/Gameplay/Project.Gameplay.asmdef Assets/_Project/Scripts/Runtime/UI/Project.UI.asmdef Assets/_Project/Scripts/Editor/Project.Editor.asmdef Assets/_Project/Scripts/Tests/EditMode/Project.Tests.EditMode.asmdef Assets/_Project/Scripts/Tests/PlayMode/Project.Tests.PlayMode.asmdef ``` 建议依赖方向： ```plaintext Project.Gameplay -> Project.Core Project.UI -> Project.Core Project.Editor -> Project.Core, Project.Gameplay, Project.UI Tests -> Runtime assemblies ``` 禁止让 `Core` 反向依赖 `Gameplay` 或 `UI`。这类规则可以通过文档、asmdef 依赖和 CI 检查共同约束。 ## 用 asmdef 控制爆炸半径 Unity 没有 TypeScript monorepo 那样天然的包边界，但 `.asmdef` 可以起到类似作用。 一个适合代理修改的 Unity 项目，不应该让所有脚本都处在默认 Assembly-CSharp 里。否则代理新增一个类时，很容易无意识引用任何地方的类型，最后形成大型循环依赖。 推荐规则： - 每个稳定模块都有自己的 `.asmdef`。 - Runtime assembly 不引用 Editor assembly。 - Feature 模块只能依赖 Core、Shared、明确允许的服务层。 - UI 不直接调用存档、网络、支付等底层实现，而是依赖接口或应用服务。 - Editor 工具放在 `Editor/` 目录，并使用 Editor-only asmdef。 示例 `Project.Gameplay.asmdef`： ```json { "name": "Project.Gameplay", "rootNamespace": "Project.Gameplay", "references": [ "Project.Core" ], "includePlatforms": [], "excludePlatforms": [], "allowUnsafeCode": false, "overrideReferences": false, "precompiledReferences": [], "autoReferenced": true, "defineConstraints": [], "versionDefines": [], "noEngineReferences": false } ``` `rootNamespace` 很重要。它能帮助代理遵守命名空间，不要把所有类都生成在全局空间。 ## 为代理准备 Unity 专属 AGENTS.md TypeScript 项目常用 `CLAUDE.md`，Unity 项目可以使用 `AGENTS.md`、`CLAUDE.md` 或 `.cursor/rules`。关键是让所有代理读取同一套规则。 示例： ````markdown # Project Unity Coding Rules ## Overview This is a Unity game built with Unity 2022.3 LTS. Runtime code lives in `Assets/_Project/Scripts/Runtime`. Editor tools live in `Assets/_Project/Scripts/Editor`. Do not modify third-party assets under `Assets/ThirdParty` unless explicitly asked. ## Entry Points - Boot scene: `Assets/_Project/Scenes/Boot.unity` - Main menu scene: `Assets/_Project/Scenes/MainMenu.unity` - Gameplay scene: `Assets/_Project/Scenes/Gameplay.unity` - Game bootstrap: `Project.Core.Bootstrap.GameBootstrapper` ## Mandatory Rules - Do not create scripts in `Assets/` root. - Do not put project code in global namespace. - Do not edit `.meta` files manually unless the task explicitly requires asset GUID work. - Do not move or rename assets casually; Unity references depend on GUIDs. - Do not modify `ProjectSettings/` unless the task is about build settings, input, quality, graphics, packages, or player settings. - Do not modify third-party plugin code; wrap it from project code instead. - Prefer editing existing components over adding duplicate manager classes. - Before adding a singleton, search for existing services, installers, bootstrap code, or ScriptableObject configs. ## C# Style - Use explicit namespaces matching assembly/module names. - Use `private` fields with `[SerializeField]` for inspector references. - Avoid public mutable fields. - Avoid `FindObjectOfType`, `GameObject.Find`, and tag-based lookup in gameplay code unless there is no stable reference path. - Avoid `async void` except Unity event handlers where unavoidable. - Prefer cancellation-aware async flows when using UniTask or Tasks. - Do not catch and rethrow exceptions without adding useful context. - Do not add comments that narrate obvious code. ## Unity Lifecycle Rules - Keep `Awake` for local initialization. - Keep `Start` for cross-object initialization that depends on scene setup. - Keep `Update` small; move non-trivial behavior into named methods or systems. - Unsubscribe events in `OnDisable` or `OnDestroy` consistently with where they were subscribed. - Do not allocate every frame in `Update`, `LateUpdate`, `FixedUpdate`, UI bindings, or hot gameplay paths. ## Validation Before considering a task complete, run: ```bash ./tools/validate-unity.sh ``` If validation fails, fix the cause. Do not weaken tests, remove analyzers, or bypass compilation unless explicitly asked. ```` ## 技能体现 Unity 最佳实践 如果团队成员使用不同代理，例如 Claude、Codex、Cursor、JetBrains AI，可以把共享技能或规则放在 `.agents/skills/`，再由各工具引用。 ```plaintext .agents/ skills/ unity-csharp-expert/ SKILL.md unity-editor-tooling/ SKILL.md unity-performance/ SKILL.md unity-ui-ugui/ SKILL.md unity-addressables/ SKILL.md .codex/ skills/ unity-csharp-expert -> ../../.agents/skills/unity-csharp-expert .claude/ skills/ unity-csharp-expert -> ../../.agents/skills/unity-csharp-expert ``` 完整 Skill 模板见附录 A。最小化版本至少要覆盖： - 修改前读取 `AGENTS.md`、相关 `docs/*.md` 和最近的 `.asmdef`。 - 保护 Unity 序列化字段、Prefab、Scene、ScriptableObject 和 `.meta`。 - 限制 Runtime / Editor 依赖边界。 - 对性能、UI、Addressables 等高风险领域使用专门 Skill。 - 完成前说明验证结果和资产影响。 Unity 的关键区别是：**C# 类型重构会影响序列化数据**。代理必须知道，字段改名、类改名、命名空间改名、文件移动、asmdef 变更，都可能破坏场景和 Prefab 引用。 ## 附录 A：完整 Skills 模板 下面是上文出现的 `.agents/skills/*/SKILL.md` 可直接落地版本。实际使用时，把 `Project`、路径和技术栈替换成项目真实名称。 ### `.agents/skills/unity-csharp-expert/SKILL.md` ````markdown --- name: unity-csharp-expert description: Use when writing, reviewing, or refactoring Unity runtime C# code, especially MonoBehaviours, ScriptableObjects, gameplay systems, services, asmdefs, serialized fields, async flows, and tests. --- # Unity C# Expert Use this skill when editing Unity runtime C# code. ## Read First - `AGENTS.md` - `docs/architecture.md` - `docs/conventions.md` - `docs/scenes-and-entrypoints.md` - `docs/asset-pipeline.md` - The nearest `.asmdef` for the files being changed ## Core Rules - Check existing MonoBehaviours, ScriptableObjects, services, bootstrap code, tests, and asmdefs before creating new files. - Preserve serialized field names unless a migration is included. - Do not rename serialized fields without `[FormerlySerializedAs]` and a migration note. - Do not move or rename `.unity`, `.prefab`, `.asset`, or `.meta` files unless explicitly asked. - Do not create scripts in `Assets/` root or global namespace. - Do not modify third-party assets; wrap them from project code. - Keep changes surgical. Do not redesign architecture around a small feature or bug fix. ## C# Style - Use namespaces that match the owning assembly or feature area. - Use `private` fields with `[SerializeField]` for inspector references. - Avoid public mutable fields. - Prefer explicit dependencies over scene-wide lookup. - Avoid single-use helpers, wrappers, base classes, and manager classes. - Avoid comments that narrate obvious code; comment only hidden constraints or surprising Unity behavior. ## Unity Runtime Rules - Use `Awake` for local initialization and `Start` for initialization that depends on scene wiring. - Subscribe and unsubscribe events symmetrically, usually in `OnEnable` and `OnDisable`. - Keep `Update`, `LateUpdate`, and `FixedUpdate` small and allocation-free. - Avoid `FindObjectOfType`, `GameObject.Find`, tag lookups, and broad singleton lookup in gameplay code. - Avoid per-frame LINQ, string formatting, closure allocations, and repeated `GetComponent` in hot paths. - Validate serialized references in `OnValidate`, targeted editor validation, or startup validation. ## Async And Coroutines - Avoid `async void` except Unity event handlers where unavoidable. - Prefer cancellation-aware async flows when using UniTask or `Task`. - Stop coroutines or cancel async work when objects are disabled or destroyed. - Do not update destroyed Unity objects after awaits, scene unloads, or cancellation. ## Tests And Validation - Add or update EditMode tests for pure logic, ScriptableObject constraints, and editor validation. - Add or update PlayMode tests for scene loading, lifecycle, UI, and gameplay flows. - Before finishing, run `./tools/validate-unity.sh` when Unity is available. - If validation fails, fix the cause rather than bypassing checks. ## Final Response Checklist - Mention any serialized field, asset, scene, prefab, or asmdef impact. - Mention tests run and validation status. - Mention if Unity was unavailable and which checks remain for the user. ```` ### `.agents/skills/unity-editor-tooling/SKILL.md` ````markdown --- name: unity-editor-tooling description: Use when creating or changing Unity Editor scripts, custom inspectors, menu items, asset processors, validation commands, build scripts, importers, and CI-facing `-executeMethod` entry points. --- # Unity Editor Tooling Use this skill for code under `Assets/_Project/Scripts/Editor` and editor-only assemblies. ## Read First - `AGENTS.md` - `docs/asset-pipeline.md` - `docs/build-and-release.md` - `docs/testing.md` - The editor `.asmdef` and the runtime assemblies it references ## Boundaries - Editor code must be in an `Editor/` folder or an Editor-only asmdef. - Runtime assemblies must not reference `UnityEditor`. - Do not put editor utilities in runtime namespaces. - Do not modify Project Settings unless the task explicitly requires it. - Do not create editor automation that silently rewrites scenes, prefabs, or assets without a dry-run or clear log. ## Validation Commands - Prefer static methods callable by `-executeMethod` for CI-facing validation. - Throw `BuildFailedException` for validation failures so Unity exits non-zero in batchmode. - Log enough asset paths and object names for agents and humans to fix failures. - Keep validation deterministic. Do not depend on current scene selection, inspector focus, or editor window state. ## AssetDatabase Rules - Use `AssetDatabase.FindAssets` with scoped folders, not whole-project scans by default. - Use GUIDs and `AssetDatabase.GUIDToAssetPath` for stable asset lookup. - Call `AssetDatabase.SaveAssets` only when the tool intentionally mutates assets. - Do not call `AssetDatabase.Refresh` repeatedly inside loops. - Never delete assets automatically unless the command is explicitly destructive and documented. ## Custom Inspectors And Windows - Keep editor UI thin; put validation and transformation logic in testable helper methods. - Support multi-object editing only when intentionally implemented. - Use `Undo.RecordObject` or `Undo.RegisterCompleteObjectUndo` for inspector-driven mutations. - Mark changed assets dirty only when values actually change. ## Final Response Checklist - Mention whether the tool reads assets, mutates assets, or changes Project Settings. - Mention the menu path or `-executeMethod` entry point. - Mention validation run status. ```` ### `.agents/skills/unity-performance/SKILL.md` ````markdown --- name: unity-performance description: Use when changing hot gameplay paths, Update loops, physics, UI refresh, pooling, allocations, Addressables loading, mobile performance, memory, frame time, or build size. --- # Unity Performance Use this skill when performance, memory, GC, frame time, loading, or build size could be affected. ## Read First - `AGENTS.md` - `docs/performance.md` - `docs/architecture.md` - Relevant profiler captures or benchmark notes if present ## Runtime Rules - Keep per-frame code allocation-free unless the allocation is intentional and documented. - Avoid per-frame LINQ, closures, string interpolation, boxing, and repeated component lookups. - Cache component references when access is repeated. - Prefer object pooling for frequently spawned short-lived objects. - Do not add new global `Update` loops when existing systems can own the work. - Prefer event-driven UI refresh over polling. ## Physics And Animation - Use `FixedUpdate` for physics mutation and `Update` for input sampling. - Avoid changing physics settings globally for a local feature. - Do not call expensive Animator or hierarchy operations every frame without measuring. - Be explicit about world space vs local space operations. ## Loading And Memory - Release Addressables handles consistently with the ownership model. - Avoid loading large assets synchronously on gameplay paths. - Do not keep scene-only references in persistent services after scene unload. - Avoid mutating imported ScriptableObject assets at runtime; copy runtime state when needed. ## Validation - Add tests for logic changes, but do not pretend unit tests prove performance. - If profiler data is available, compare before and after. - For risky changes, document expected frame-time, allocation, memory, or loading impact. ## Final Response Checklist - Mention hot paths touched. - Mention expected allocation and frame-time impact. - Mention tests run and any profiling not performed. ```` ### `.agents/skills/unity-ui-ugui/SKILL.md` ````markdown --- name: unity-ui-ugui description: Use when editing Unity UI built with uGUI, Canvas, RectTransform, prefabs, view controllers, UI events, navigation, layout, localization, and accessibility. --- # Unity UI uGUI Use this skill when editing uGUI screens, prefabs, panels, widgets, and UI-facing C# code. ## Read First - `AGENTS.md` - `docs/architecture.md` - `docs/asset-pipeline.md` - `docs/scenes-and-entrypoints.md` - Existing UI prefabs and controllers in the same feature area ## UI Code Rules - Keep views thin. UI components bind data, raise user intents, and delegate behavior to services or presenters. - Do not put gameplay, save, network, or economy logic directly in button handlers. - Use serialized references for UI widgets. Avoid runtime hierarchy searches except during controlled setup. - Subscribe and unsubscribe UI events symmetrically. - Avoid rebuilding layouts every frame. - Do not leave unused serialized fields, stale branches, hidden panels, or abandoned animation hooks. ## Prefab And Layout Rules - Preserve prefab references and serialized field names. - Do not unpack or restructure large UI prefabs unless explicitly asked. - Prefer editing existing UI prefabs/controllers over creating parallel variants. - Be careful with anchors, pivots, safe areas, scaling, and dynamic text length. - Keep localization expansion in mind; avoid hard-coded widths for text-heavy UI. ## Accessibility And Input - Preserve keyboard/controller navigation when changing selectable UI. - Keep interactable state and visual state consistent. - Avoid color-only state communication when the UI needs accessibility. ## Validation - Add EditMode tests for formatting/presenter logic when possible. - Add PlayMode tests for critical UI flows when practical. - Run relevant scenes or validation commands when Unity is available. ## Final Response Checklist - Mention UI prefabs, scenes, or serialized fields touched. - Mention input/navigation impact. - Mention tests or manual validation performed. ```` ### `.agents/skills/unity-addressables/SKILL.md` ````markdown --- name: unity-addressables description: Use when changing Unity Addressables, remote content, asset references, labels, groups, loading/release flows, catalogs, or asset bundle build validation. --- # Unity Addressables Use this skill when editing Addressables configuration, code paths that load assets, or assets intended for remote/local bundles. ## Read First - `AGENTS.md` - `docs/asset-pipeline.md` - `docs/build-and-release.md` - Existing Addressables groups, labels, and key conventions ## Key And Group Rules - Addressable keys must be stable. Do not rename keys casually. - Do not hard-code the same key in multiple places; centralize keys in constants or config. - Use labels intentionally. Do not add broad labels that pull too many assets into memory. - Keep group schema, compression, remote/local settings, and update restrictions consistent with existing groups. - Do not move assets between groups without documenting build and patching impact. ## Loading Rules - Track ownership of Addressables handles. - Release handles according to the same layer that loaded them. - Avoid synchronous loading in gameplay paths. - Handle load failure at real boundaries with actionable logs. - Do not keep references to unloaded scene assets or released Addressables. ## Validation - Run Addressables Analyze or project validation when available. - For build-impacting changes, run an Addressables content build or explain why it was not run. - Add tests around key resolution, catalog-facing config, or loader behavior when possible. ## Final Response Checklist - Mention keys, labels, groups, or assets changed. - Mention load/release ownership. - Mention Addressables validation/build status. ```` ## 代理需要维护的 Unity 文档 Unity 项目文档不应只描述代码，还要描述资源和编辑器约定。 推荐文档： ```plaintext docs/ architecture.md # 模块、依赖方向、启动流程 scenes-and-entrypoints.md # 场景用途、加载顺序、入口脚本 asset-pipeline.md # Prefab、SO、Addressables、命名规范 conventions.md # C#、Unity 生命周期、Inspector 规则 testing.md # EditMode、PlayMode、CI、覆盖范围 build-and-release.md # 平台、构建参数、版本号、签名 performance.md # GC、对象池、Update 预算、Profiler 流程 cleanup.md # AI 垃圾回收的边界、提示词、PR 规则 ``` `docs/scenes-and-entrypoints.md` 示例： ```markdown # Scenes And Entry Points ## Boot.unity Purpose: initializes project-wide services and loads the next scene. Main scripts: - `Project.Core.Bootstrap.GameBootstrapper` - `Project.Core.SceneLoading.SceneLoader` Rules: - Do not place gameplay objects in Boot scene. - Do not make Boot depend on UI or Gameplay assemblies. - New global systems must be registered through the bootstrap flow, not via hidden scene searches. ## Gameplay.unity Purpose: contains the playable game loop. Main roots: - `GameplayRoot` - `PlayerSpawnRoot` - `LevelRuntimeRoot` Rules: - Scene references should be wired in prefabs or root installers. - Do not add duplicate manager GameObjects without checking existing roots. ``` `docs/asset-pipeline.md` 示例： ```markdown # Asset Pipeline ## Prefabs - Runtime prefabs live under `Assets/_Project/Prefabs`. - UI prefabs live under `Assets/_Project/Prefabs/UI`. - Do not unpack third-party prefabs in place. - Do not rename serialized fields without migration notes. ## ScriptableObjects - Balance configs live under `Assets/_Project/Configs/GameBalance`. - ScriptableObject types live under `Project.Core.Config` or the owning feature namespace. - Runtime systems may read config assets but must not mutate imported asset instances during play. ## Addressables - Addressable keys must be stable. - Do not hard-code Addressable keys in multiple places; centralize them in constants or config. - Validate Addressables before release builds. ``` ## Unity C# 编码规则：减少 AI Slop Unity 项目的 AI slop 往往不是语法错误，而是“看起来能跑，但工程越来越烂”： - 新增很多 `Manager`、`Controller`、`Handler`，职责重叠 - 到处 `FindObjectOfType` 和 `DontDestroyOnLoad` - 改字段名导致 Prefab 引用丢失 - 在 `Update` 里分配 GC 或做昂贵查询 - 编辑器脚本混入 Runtime assembly - 测试缺失，只靠手动点场景 - 留下旧 Prefab、旧 ScriptableObject、旧分支逻辑 可以在 `AGENTS.md` 里强制： ```markdown ## Minimal Changes / No Slop - Re-read your diff before finishing. Delete unused code, stale branches, unused serialized fields, and abandoned helper methods. - Do not add narration comments. Comments must explain non-obvious Unity constraints, lifecycle ordering, serialization migration, or platform-specific behavior. - Do not create a new manager/service if an existing system owns the responsibility. - Do not create a helper class for a single caller. - Do not add speculative null checks for serialized fields everywhere. Validate required references in `OnValidate` or targeted startup validation. - Do not use `FindObjectOfType`, `GameObject.Find`, or global singleton lookup as a first choice. - Do not rename serialized fields without `[FormerlySerializedAs]` and a migration note. - Do not move assets unless the task requires it. - Do not edit generated files, package cache files, or third-party assets. ``` 字段改名示例： ```csharp using UnityEngine; using UnityEngine.Serialization; namespace Project.Gameplay.Player { public sealed class PlayerMovement : MonoBehaviour { [FormerlySerializedAs("moveSpeed")] [SerializeField] private float movementSpeed = 5f; } } ``` 这条规则对 Unity 很重要。没有 `[FormerlySerializedAs]`，代理一次普通重命名就可能让所有 Prefab 上的数值回到默认值。 ## 用 OnValidate 和编辑器验证建立护栏 Unity 项目里，很多错误不会被 C# 编译器发现：Prefab 少绑了引用、配置数值非法、Addressable key 不存在、场景没有必要入口对象。 可以用 `OnValidate` 做局部约束： ```csharp using UnityEngine; namespace Project.Gameplay.Weapons { public sealed class WeaponConfig : ScriptableObject { [SerializeField] private float damage = 10f; [SerializeField] private float cooldownSeconds = 0.25f; public float Damage => damage; public float CooldownSeconds => cooldownSeconds; private void OnValidate() { damage = Mathf.Max(0f, damage); cooldownSeconds = Mathf.Max(0.01f, cooldownSeconds); } } } ``` 也可以写项目级验证菜单，给代理和 CI 调用： ```csharp #if UNITY_EDITOR using UnityEditor; using UnityEditor.Build; using UnityEngine; namespace Project.Editor.Validation { public static class ProjectValidator { [MenuItem("Project/Validation/Run All")] public static void RunAll() { ValidateWeaponConfigs(); Debug.Log("Project validation passed."); } private static void ValidateWeaponConfigs() { string[] guids = AssetDatabase.FindAssets("t:WeaponConfig", new[] { "Assets/_Project/Configs" }); foreach (string guid in guids) { string path = AssetDatabase.GUIDToAssetPath(guid); var config = AssetDatabase.LoadAssetAtPath(path); if (config == null) { throw new BuildFailedException($"Invalid WeaponConfig asset at {path}"); } } } } } #endif ``` 更完整的项目可以把验证做成 `-executeMethod` 可调用的静态入口： ```csharp #if UNITY_EDITOR namespace Project.Editor.Validation { public static class ProjectValidationCommand { public static void RunAll() { ProjectValidator.RunAll(); } } } #endif ``` 然后 CI 或本地脚本执行： ```bash Unity \ -batchmode \ -quit \ -projectPath . \ -executeMethod Project.Editor.Validation.ProjectValidationCommand.RunAll \ -logFile Logs/unity-validation.log ``` ## 让糟糕代码难以提交 Unity 项目也应该使用提交前钩子。可以用 `pre-commit`、Husky、lefthook 或 Git hooks。 示例 `.pre-commit-config.yaml`： ```yaml repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 hooks: - id: check-yaml - id: check-json - id: end-of-file-fixer - id: trailing-whitespace exclude: ".*(.unity|.prefab|.asset|.meta)$" - repo: local hooks: - id: dotnet-format name: dotnet format entry: dotnet format ProjectName.sln --verify-no-changes language: system files: "\\.cs$" pass_filenames: false ``` 这里要显式写 solution 路径，不要依赖 `dotnet format` 在仓库根目录自动猜测。Unity 项目如果忽略 `.sln` / `.csproj`，需要先打开 Unity 或用 Unity 批处理生成 C# project files，再运行： ```bash dotnet format ProjectName.sln --verify-no-changes ``` 如果团队使用 Rider/ReSharper，也可以在 CI 中加入 InspectCode： ```bash jb inspectcode ProjectName.sln --output=inspectcode.xml ``` 不要指望代理每次都记得格式化、跑测试。把这些变成钩子和 CI，而不是口头约定。 ## 一个命令验证所有内容 代理需要一个明确终点线。Unity 项目推荐准备 `tools/validate-unity.sh` 或 `tools/validate-unity.ps1`。 示例 `tools/validate-unity.sh`： ```bash #!/usr/bin/env bash set -euo pipefail UNITY_PATH="${UNITY_PATH:-Unity}" PROJECT_PATH="$(pwd)" LOG_DIR="$PROJECT_PATH/Logs" mkdir -p "$LOG_DIR" "$UNITY_PATH" \ -batchmode \ -quit \ -projectPath "$PROJECT_PATH" \ -runTests \ -testPlatform EditMode \ -testResults "$LOG_DIR/editmode-results.xml" \ -logFile "$LOG_DIR/editmode.log" "$UNITY_PATH" \ -batchmode \ -quit \ -projectPath "$PROJECT_PATH" \ -runTests \ -testPlatform PlayMode \ -testResults "$LOG_DIR/playmode-results.xml" \ -logFile "$LOG_DIR/playmode.log" "$UNITY_PATH" \ -batchmode \ -quit \ -projectPath "$PROJECT_PATH" \ -executeMethod Project.Editor.Validation.ProjectValidationCommand.RunAll \ -logFile "$LOG_DIR/project-validation.log" ``` 然后在 `AGENTS.md` 中写清楚： ````markdown Before considering a task complete, run: ```bash ./tools/validate-unity.sh ``` If it fails, fix the errors rather than working around checks. Do not delete tests, weaken assertions, or bypass Unity validation unless explicitly asked. ```` Windows 团队可以提供 PowerShell 版本： ```powershell $ErrorActionPreference = "Stop" $UnityPath = if ($env:UNITY_PATH) { $env:UNITY_PATH } else { "Unity.exe" } $ProjectPath = Get-Location $LogDir = Join-Path $ProjectPath "Logs" New-Item -ItemType Directory -Force -Path $LogDir | Out-Null & $UnityPath -batchmode -quit -projectPath $ProjectPath -runTests -testPlatform EditMode -testResults "$LogDir/editmode-results.xml" -logFile "$LogDir/editmode.log" if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } & $UnityPath -batchmode -quit -projectPath $ProjectPath -runTests -testPlatform PlayMode -testResults "$LogDir/playmode-results.xml" -logFile "$LogDir/playmode.log" if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } & $UnityPath -batchmode -quit -projectPath $ProjectPath -executeMethod Project.Editor.Validation.ProjectValidationCommand.RunAll -logFile "$LogDir/project-validation.log" if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } ``` ## 始终使用测试驱动开发 Unity 的 TDD 可以分成三层： 1. **纯 C# 单元测试**：不依赖 Unity 场景，测试规则、计算、状态机、存档格式。 2. **EditMode 测试**：测试 ScriptableObject、编辑器验证、资源导入规则、Prefab 结构。 3. **PlayMode 测试**：测试场景加载、MonoBehaviour 生命周期、输入、UI、玩法流程。 代理最适合先写测试规格，再写实现。 例如，先让代理生成测试： ```csharp using NUnit.Framework; using Project.Gameplay.Combat; namespace Project.Tests.EditMode.Gameplay.Combat { public sealed class DamageCalculatorTests { [Test] public void CalculateDamage_DoesNotReturnNegativeDamage() { int damage = DamageCalculator.CalculateDamage(baseDamage: 5, armor: 999); Assert.That(damage, Is.EqualTo(0)); } [Test] public void CalculateDamage_AppliesCriticalMultiplierAfterArmorReduction() { int damage = DamageCalculator.CalculateDamage(baseDamage: 20, armor: 5, criticalMultiplier: 2f); Assert.That(damage, Is.EqualTo(30)); } } } ``` 人工先检查测试是否符合需求。确认后，再让代理实现： ```csharp namespace Project.Gameplay.Combat { public static class DamageCalculator { public static int CalculateDamage(int baseDamage, int armor, float criticalMultiplier = 1f) { int reducedDamage = System.Math.Max(0, baseDamage - armor); return (int)(reducedDamage * criticalMultiplier); } } } ``` 好测试不仅是质量保障，也是给代理的监督信号。没有测试时，代理会倾向于“看起来合理”；有测试时，代理会被迫对齐明确行为。 ## Unity CI：本地护栏不够时 本地 hooks 只能拦住一部分问题。Unity 项目最好在 CI 中运行： - C# 编译 - EditMode 测试 - PlayMode 测试 - 项目自定义验证 - Addressables 构建或分析 - 目标平台构建 - 静态分析 - Secret 扫描 - 许可证和第三方依赖审计 GitHub Actions 示例： ```yaml name: Unity Validate on: pull_request: workflow_dispatch: jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: lfs: true - uses: actions/cache@v4 with: path: Library key: Library-${{ hashFiles('Assets/**', 'Packages/**', 'ProjectSettings/**') }} restore-keys: | Library- - name: Run EditMode tests uses: game-ci/unity-test-runner@v4 env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }} UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }} with: testMode: EditMode artifactsPath: test-results/editmode - name: Run PlayMode tests uses: game-ci/unity-test-runner@v4 env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }} UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }} with: testMode: PlayMode artifactsPath: test-results/playmode - name: Run project validation uses: game-ci/unity-builder@v4 env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }} UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }} with: targetPlatform: StandaloneWindows64 buildMethod: Project.Editor.Validation.ProjectValidationCommand.RunAll - name: Build player uses: game-ci/unity-builder@v4 env: UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }} UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }} with: targetPlatform: StandaloneWindows64 ``` 对于大型项目，还可以加入： - Addressables Analyze - AssetBundle 构建验证 - 平台特定 smoke test - IL2CPP 构建 - Android/iOS 签名检查 - 内存和包体积预算检查 ## Unity 版“垃圾回收”：定期清理 AI Slop 即使有规则，AI slop 仍然会出现。Unity 项目可以定期让代理做小范围维护 PR，但必须限制权限和范围。 适合自动清理的事项： - 删除无引用的私有方法和类 - 清理未使用 using - 同步 `AGENTS.md` 和 `docs/` - 查找重复 Manager/Service - 查找 Editor 代码误入 Runtime assembly - 查找空目录、过期测试、无效文档引用 - 查找没有 `[FormerlySerializedAs]` 的可疑字段重命名 不适合自动清理的事项： - 大规模移动资产 - 批量重命名 Prefab、场景、ScriptableObject - 自动改 Project Settings - 自动升级 Unity 版本或包版本 - 自动重写核心架构 垃圾回收提示词示例： ```markdown Read `AGENTS.md` and `docs/cleanup.md`. Make one small, safe maintenance improvement only. Prefer C# cleanup over asset moves. Do not rename serialized fields. Do not move `.unity`, `.prefab`, `.asset`, or `.meta` files. Do not modify third-party assets. If no safe cleanup exists, leave the repository unchanged. Before finishing, run `./tools/validate-unity.sh` if Unity is available. ``` ## Unity 项目的安全与供应链 Unity 项目同样有安全风险，尤其是： - 第三方插件引入恶意代码 - API key 写入 ScriptableObject、场景或 `Resources` - 移动端客户端包含不该存在的服务端密钥 - Asset Store 插件包含过宽权限 - Addressables 或远程配置被滥用 - 内购、经济系统、存档校验逻辑只在客户端实现 建议： - 使用 secret scanning 检查 `.cs`、`.asset`、`.prefab`、`.unity`、`.json`。 - 不把服务端密钥放进 Unity 客户端。 - 对内购、货币、排行榜、账号权限做服务端校验。 - 审查第三方插件更新。 - CI 中加入依赖和许可证审计。 ## 始终思考 Unity 工程给代理提供了什么 编码代理的输出，强烈依赖仓库环境给它提供的约束。 如果 Unity 项目只有一个巨大的 `Assets/`、没有 asmdef、没有测试、没有文档、没有验证脚本，代理就会倾向于生成“能编译但脏”的代码。 如果项目提供： - 清晰目录结构 - 明确 asmdef 边界 - 可执行测试 - 项目级验证命令 - 严格 AGENTS.md - 资源和场景文档 - 提交钩子和 CI 那么代理就更容易写出可维护的 Unity C# 代码。 关键不是让 AI “更听话”，而是让工程环境本身变得更难写坏。 ## 附录 B：完整项目文档模板 下面是上文出现的 `AGENTS.md` 和 `docs/*.md` 可直接落地版本。它们的目标不是替代真实项目文档，而是给编码代理一个稳定的起点。落地时要把占位符替换成真实项目名称、Unity 版本、场景、程序集和平台。 ### `AGENTS.md` ````markdown # Project Unity Coding Rules ## Overview This is a Unity project built with Unity 2022.3 LTS. Runtime code lives in `Assets/_Project/Scripts/Runtime`. Editor tools live in `Assets/_Project/Scripts/Editor`. Project assets live under `Assets/_Project`. Third-party assets live under `Assets/ThirdParty` or `Assets/Plugins`. ## Read Before Editing - `docs/architecture.md` - `docs/conventions.md` - `docs/scenes-and-entrypoints.md` - `docs/asset-pipeline.md` - `docs/testing.md` - Relevant `.agents/skills/*/SKILL.md` files for the task ## Entry Points - Boot scene: `Assets/_Project/Scenes/Boot.unity` - Main menu scene: `Assets/_Project/Scenes/MainMenu.unity` - Gameplay scene: `Assets/_Project/Scenes/Gameplay.unity` - Game bootstrap: `Project.Core.Bootstrap.GameBootstrapper` ## Mandatory Rules - Do not create scripts in `Assets/` root. - Do not put project code in global namespace. - Do not edit `.meta` files manually unless the task explicitly requires asset GUID work. - Do not move or rename assets casually; Unity references depend on GUIDs. - Do not rename serialized fields without `[FormerlySerializedAs]` and a migration note. - Do not modify `ProjectSettings/` unless the task is about build settings, input, quality, graphics, packages, or player settings. - Do not modify third-party plugin code; wrap it from project code instead. - Prefer editing existing components over adding duplicate manager classes. - Before adding a singleton, search for existing services, installers, bootstrap code, and ScriptableObject configs. ## C# Style - Use explicit namespaces matching assembly/module names. - Use `private` fields with `[SerializeField]` for inspector references. - Avoid public mutable fields. - Avoid `FindObjectOfType`, `GameObject.Find`, and tag-based lookup in gameplay code unless there is no stable reference path. - Avoid `async void` except Unity event handlers where unavoidable. - Prefer cancellation-aware async flows when using UniTask or Tasks. - Do not catch and rethrow exceptions without adding useful context. - Do not add comments that narrate obvious code. ## Unity Lifecycle Rules - Keep `Awake` for local initialization. - Keep `Start` for cross-object initialization that depends on scene setup. - Keep `Update`, `LateUpdate`, and `FixedUpdate` small and allocation-free. - Unsubscribe events in `OnDisable` or `OnDestroy` consistently with where they were subscribed. - Do not mutate imported ScriptableObject assets as runtime state. ## Asset Rules - `.meta` files must be committed. - Unity serialization must use Force Text. - Version Control mode must use Visible Meta Files. - Do not unpack, restructure, or rename prefabs unless the task explicitly requires it. - Do not modify scenes unless the requested behavior requires scene wiring. - Mention prefab, scene, ScriptableObject, Addressables, or asmdef impact in the final response. ## Minimal Changes / No Slop - Re-read your diff before finishing and remove unused code, stale branches, unused serialized fields, and abandoned helpers. - Do not add single-use abstractions. - Do not add speculative null checks everywhere; validate at boundaries and targeted validation points. - Do not leave commented-out code or tombstone comments. - Do not perform broad cleanup around an unrelated bug fix. ## Validation Before considering a task complete, run: ```bash ./tools/validate-unity.sh ``` If validation fails, fix the cause. Do not weaken tests, remove analyzers, delete assertions, or bypass compilation unless explicitly asked. If Unity is unavailable, state that validation was not run and list the exact command the user should run. ```` ### `docs/architecture.md` ````markdown # Architecture ## Purpose This document describes the stable module boundaries, dependency direction, and runtime ownership model for the Unity project. Coding agents must read this before changing cross-module behavior. ## Project Layout ```plaintext Assets/_Project/ Configs/ Prefabs/ Scenes/ Scripts/ Runtime/ Core/ Gameplay/ UI/ Infrastructure/ Editor/ Tests/ EditMode/ PlayMode/ ``` ## Assemblies | Assembly | Path | Responsibility | May Reference | | --- | --- | --- | --- | | `Project.Core` | `Assets/_Project/Scripts/Runtime/Core` | Shared runtime primitives, bootstrap contracts, scene loading interfaces | Unity runtime packages only | | `Project.Gameplay` | `Assets/_Project/Scripts/Runtime/Gameplay` | Gameplay rules, player, enemies, combat, level systems | `Project.Core` | | `Project.UI` | `Assets/_Project/Scripts/Runtime/UI` | UI screens, widgets, view controllers | `Project.Core` | | `Project.Infrastructure` | `Assets/_Project/Scripts/Runtime/Infrastructure` | Save, platform, analytics, remote config, adapters | `Project.Core` | | `Project.Editor` | `Assets/_Project/Scripts/Editor` | Editor tools, validators, build scripts | Runtime assemblies as needed | | `Project.Tests.EditMode` | `Assets/_Project/Scripts/Tests/EditMode` | EditMode tests | Runtime and editor assemblies as needed | | `Project.Tests.PlayMode` | `Assets/_Project/Scripts/Tests/PlayMode` | PlayMode tests | Runtime assemblies | ## Dependency Rules - `Core` must not reference `Gameplay`, `UI`, or `Infrastructure`. - `Gameplay` must not call UI directly; communicate through events, state, or application services. - `UI` must not implement gameplay, save, payment, or network business logic. - Runtime assemblies must not reference `UnityEditor`. - Editor assemblies may reference runtime assemblies, but runtime assemblies may not reference editor assemblies. - New modules require an `.asmdef` and an entry in this document. ## Runtime Ownership - Bootstrapping starts in `Project.Core.Bootstrap.GameBootstrapper` from `Boot.unity`. - Persistent services are created by the bootstrap flow, not by hidden scene search. - Scene-specific objects are owned by scene roots and must be released on scene unload. - Imported ScriptableObject assets are configuration, not mutable runtime state. - Runtime state that derives from ScriptableObjects must be copied into plain C# objects or scene-owned components. ## Scene Loading - `Boot.unity` initializes global services and loads the next scene. - `MainMenu.unity` owns menu UI and user entry flow. - `Gameplay.unity` owns gameplay scene roots and gameplay-only objects. - Additive scenes must document ownership, loading trigger, and unload trigger in `docs/scenes-and-entrypoints.md`. ## Adding A Feature 1. Identify the owning assembly. 2. Search for existing services, roots, prefabs, configs, and tests. 3. Add the smallest code change in the owning module. 4. Add or update tests. 5. Update docs if scenes, public contracts, assets, or assembly boundaries change. 6. Run `./tools/validate-unity.sh`. ```` ### `docs/conventions.md` ````markdown # Conventions ## C# Naming - Namespaces start with `Project` and follow the owning module, for example `Project.Gameplay.Combat`. - MonoBehaviour class names describe behavior, not vague roles like `Manager` unless the existing architecture already owns that concept. - Serialized private fields use camelCase. - Public properties use PascalCase and expose read-only state unless mutation is intentional. - Async methods end with `Async` unless they are Unity event handlers. ## File And Folder Rules - One top-level public type per `.cs` file unless types are tightly coupled small value types. - Runtime code goes under `Assets/_Project/Scripts/Runtime`. - Editor code goes under `Assets/_Project/Scripts/Editor` or an Editor-only asmdef. - Tests go under `Assets/_Project/Scripts/Tests/EditMode` or `Assets/_Project/Scripts/Tests/PlayMode`. - Do not place project scripts directly under `Assets/`. ## Serialized Fields - Prefer `[SerializeField] private` over public fields. - Preserve serialized field names. - If a serialized field is renamed, add `[FormerlySerializedAs("oldName")]`. - Do not remove serialized fields without checking prefabs and scenes that may use them. - Required scene or prefab references should be validated in `OnValidate` or project validation. ## Unity Lifecycle - `Awake`: initialize local state and cache local components. - `OnEnable`: subscribe to events or start object-scoped work. - `Start`: perform initialization that depends on other scene objects being awake. - `Update`: keep small and allocation-free. - `OnDisable`: unsubscribe from events or cancel object-scoped work. - `OnDestroy`: release resources not already handled by disable flow. ## Comments - Do not write comments that restate code. - Do write comments for hidden Unity constraints, serialization migration, platform-specific behavior, and surprising ordering requirements. - Do not leave commented-out code. ## Error Handling - Validate at true boundaries: user input, save data, network responses, external SDK callbacks, Addressables loads, and editor validation. - Do not catch and rethrow without adding context. - Use actionable logs that include asset paths, scene names, object names, or keys when relevant. ## Prohibited Defaults - No new global singleton without checking existing bootstrap/service patterns. - No `FindObjectOfType` or `GameObject.Find` as a first choice. - No runtime dependency on `UnityEditor`. - No broad asset moves during code-only tasks. - No speculative architecture rewrites. ```` ### `docs/scenes-and-entrypoints.md` ````markdown # Scenes And Entry Points ## Scene List | Scene | Path | Purpose | Owner | | --- | --- | --- | --- | | Boot | `Assets/_Project/Scenes/Boot.unity` | Initializes global services and loads the next scene | Core | | MainMenu | `Assets/_Project/Scenes/MainMenu.unity` | Menu flow, profile selection, settings entry | UI | | Gameplay | `Assets/_Project/Scenes/Gameplay.unity` | Main playable loop | Gameplay | ## Boot.unity Purpose: initializes project-wide services and loads the next scene. Main scripts: - `Project.Core.Bootstrap.GameBootstrapper` - `Project.Core.SceneLoading.SceneLoader` Rules: - Do not place gameplay objects in Boot scene. - Do not make Boot depend on UI or Gameplay assemblies. - New global systems must be registered through the bootstrap flow, not via hidden scene searches. - Persistent objects must have clear ownership and teardown rules. ## MainMenu.unity Purpose: contains menu UI and non-gameplay user flow. Main roots: - `MainMenuRoot` - `MenuCanvas` - `SettingsPanelRoot` Rules: - UI controllers delegate to services; they do not implement save, economy, or network logic. - Button events must be backed by serialized references or explicit binding code. - Preserve controller/keyboard navigation when changing menu UI. ## Gameplay.unity Purpose: contains the playable game loop. Main roots: - `GameplayRoot` - `PlayerSpawnRoot` - `LevelRuntimeRoot` - `GameplayCanvas` Rules: - Scene references should be wired in prefabs or root installers. - Do not add duplicate manager GameObjects without checking existing roots. - Gameplay scene objects must not assume MainMenu objects still exist. - Scene-owned services must release subscriptions and Addressables handles on unload. ## Adding Or Changing Scenes When adding or changing a scene: 1. Add the scene path and purpose to this document. 2. Document root GameObjects and entry scripts. 3. Update build settings or Addressables docs if loading changes. 4. Add PlayMode tests for critical loading behavior when practical. 5. Mention scene impact in the final response. ```` ### `docs/asset-pipeline.md` ````markdown # Asset Pipeline ## Unity Serialization Project Settings must use: ```plaintext Version Control Mode: Visible Meta Files Asset Serialization Mode: Force Text ``` Rules: - `.meta` files must be committed. - Do not manually edit `.meta` files unless fixing GUID or merge issues. - Do not move or rename assets casually; references depend on GUIDs and paths. - Use Git LFS for large binary assets. - Use UnityYAMLMerge for `.unity`, `.prefab`, `.asset`, `.controller`, `.anim`, and `.mat` files. ## Prefabs - Runtime prefabs live under `Assets/_Project/Prefabs`. - UI prefabs live under `Assets/_Project/Prefabs/UI`. - Gameplay prefabs live under `Assets/_Project/Prefabs/Gameplay`. - System prefabs live under `Assets/_Project/Prefabs/Systems`. - Do not unpack third-party prefabs in place. - Do not rename serialized fields without `[FormerlySerializedAs]` and migration notes. - Prefer prefab variants when a variant is truly needed; do not create duplicate prefabs for small temporary differences. ## ScriptableObjects - Balance configs live under `Assets/_Project/Configs/GameBalance`. - ScriptableObject types live under `Project.Core.Config` or the owning feature namespace. - Runtime systems may read config assets but must not mutate imported asset instances during play. - If runtime mutation is needed, copy ScriptableObject data into runtime state. - Required fields should be validated by `OnValidate` or project validation. ## Addressables - Addressable keys must be stable. - Do not hard-code the same key in multiple places; centralize keys in constants or config. - Labels must have clear loading purpose. - Do not move assets between groups without documenting bundle, patch, and remote content impact. - Validate Addressables before release builds. ## Art And Audio - Source art files such as `.psd` and `.blend` use Git LFS. - Runtime textures, models, and audio should follow platform import presets. - Do not change compression, max size, or platform overrides unless the task is about asset optimization or visual/audio quality. - Document large asset additions in the final response. ## Generated Assets - Do not edit generated assets manually. - Generated file locations and regeneration commands must be documented near the generator or in `docs/build-and-release.md`. - If generated assets change, mention the generator command that produced them. ```` ### `docs/testing.md` ````markdown # Testing ## Test Layers | Layer | Location | Purpose | | --- | --- | --- | | Pure C# tests | `Assets/_Project/Scripts/Tests/EditMode` | Rules, calculators, state machines, save formats | | EditMode tests | `Assets/_Project/Scripts/Tests/EditMode` | ScriptableObjects, editor validation, import rules, prefab structure | | PlayMode tests | `Assets/_Project/Scripts/Tests/PlayMode` | Scene loading, MonoBehaviour lifecycle, UI, gameplay smoke tests | ## Commands Run all local validation: ```bash ./tools/validate-unity.sh ``` Run EditMode tests only: ```bash Unity -batchmode -quit -projectPath . -runTests -testPlatform EditMode -testResults Logs/editmode-results.xml -logFile Logs/editmode.log ``` Run PlayMode tests only: ```bash Unity -batchmode -quit -projectPath . -runTests -testPlatform PlayMode -testResults Logs/playmode-results.xml -logFile Logs/playmode.log ``` Run project validation: ```bash Unity -batchmode -quit -projectPath . -executeMethod Project.Editor.Validation.ProjectValidationCommand.RunAll -logFile Logs/project-validation.log ``` ## Testing Rules For Agents - Write or update tests before implementation when behavior is non-trivial. - Human review should confirm generated tests describe the intended behavior before implementation begins. - Do not delete tests to make validation pass. - Do not weaken assertions unless the requirement changed. - Prefer pure C# tests for deterministic logic. - Use PlayMode tests for lifecycle, scene, input, and UI behavior that cannot be proven in EditMode. ## What To Test - Calculators, state machines, cooldowns, timers, and progression rules. - Save/load serialization and migration. - ScriptableObject validation and default constraints. - Addressables key resolution and loader ownership. - Scene boot and critical smoke flows. - UI presenter formatting and critical button flows. ## What Not To Over-Test - Unity engine internals. - Trivial property pass-through. - Visual polish that needs human review unless screenshot tooling exists. - Performance claims without profiler or benchmark support. ## CI Expectations Pull requests should run: - EditMode tests - PlayMode tests for critical flows - Project validation command - Build for at least one representative target platform If a check cannot run locally, the final response must say so and name the CI check that should cover it. ```` ### `docs/build-and-release.md` ````markdown # Build And Release ## Unity Version Unity version: `2022.3.x LTS` The Unity version must be pinned in `ProjectSettings/ProjectVersion.txt`. Do not upgrade Unity versions unless explicitly asked. ## Supported Targets | Platform | Target | Notes | | --- | --- | --- | | Windows | `StandaloneWindows64` | Default CI build target | | macOS | `StandaloneOSX` | Add if release requires it | | Android | `Android` | Requires keystore and signing setup | | iOS | `iOS` | Requires Xcode signing pipeline | ## Local Build Command ```bash Unity -batchmode -quit -projectPath . -executeMethod Project.Editor.Build.BuildCommand.BuildWindows -logFile Logs/build-windows.log ``` Replace the build method with the real project build entry point. ## CI Build Requirements - Checkout must include Git LFS assets. - CI must use the pinned Unity version. - CI must run tests and project validation before release builds. - Build logs must be uploaded as artifacts on failure. - Release builds must not contain development-only scenes or test assets. ## Versioning - Update application version through the documented build pipeline, not by ad-hoc Project Settings edits. - Keep bundle identifiers stable. - Platform-specific version codes must be monotonic. - Mention version or build setting changes in the final response. ## Addressables And Remote Content - Validate Addressables before release. - Document content update restrictions before moving assets between groups. - Catalog and remote paths must match the target environment. - Do not change remote load paths without release owner approval. ## Secrets And Signing - Do not commit keystores, provisioning profiles, API keys, or service account files. - Signing credentials must come from CI secrets or local secure storage. - Unity clients must not contain server-only secrets. ## Release Checklist - `./tools/validate-unity.sh` passes. - Target platform build passes. - Addressables validation/build passes if Addressables changed. - Version and build number are correct. - Scenes in build settings are correct. - No development-only flags are enabled for production. ```` ### `docs/performance.md` ````markdown # Performance ## Budgets Define real budgets per project and platform. Starting placeholders: | Area | Budget | | --- | --- | | Frame time | 16.6 ms for 60 FPS target | | GC allocations during gameplay | 0 B/frame in hot paths | | Scene load | Project-specific | | Memory | Platform-specific | | Build size | Platform-specific | ## Hot Path Rules - No per-frame LINQ in gameplay or UI hot paths. - No repeated string formatting in `Update`, `LateUpdate`, `FixedUpdate`, or UI polling loops. - Cache repeated component lookups. - Avoid broad hierarchy searches during gameplay. - Prefer event-driven UI updates over polling. - Use pooling for frequently spawned short-lived objects. ## Profiling Workflow 1. Reproduce the performance issue in a stable scene or test flow. 2. Capture baseline profiler data. 3. Make the smallest targeted change. 4. Capture after-change data using the same scenario. 5. Document the measured result in the PR or final response. ## Memory Rules - Release Addressables handles consistently. - Do not keep scene object references in persistent services after scene unload. - Avoid mutating imported ScriptableObject assets at runtime. - Be cautious with large texture, audio, and animation imports. - Use platform import overrides intentionally. ## UI Performance - Avoid forcing layout rebuilds every frame. - Avoid enabling/disabling large UI hierarchies repeatedly in hot flows. - Prefer pooled list items for long or frequently refreshed lists. - Do not leave invisible panels doing work. ## Physics Performance - Use physics layers intentionally. - Avoid unnecessary collision matrix expansion. - Avoid expensive queries every frame without measuring. - Keep `FixedUpdate` logic focused and deterministic. ## Agent Rules - Do not claim performance improved without a measurement or clear mechanical reason. - If profiling was not run, say so. - Mention hot paths touched and expected allocation/frame-time impact. ```` ### `docs/cleanup.md` ````markdown # Cleanup Rules For AI Garbage Collection ## Purpose This document defines safe maintenance work for periodic AI cleanup. The goal is to remove obvious slop without creating risky asset, scene, or architecture churn. ## Allowed Cleanup Agents may make one small, focused cleanup PR for: - Removing unused private methods, fields, or using directives. - Removing dead code proven unreachable by current callers. - Removing stale comments or commented-out code. - Fixing documentation references to renamed or removed code. - Updating factual sections of `AGENTS.md` and `docs/*.md` to match the current codebase. - Moving editor-only code out of runtime assemblies when the fix is obvious and small. - Adding missing validation around existing documented invariants. ## Disallowed Cleanup Agents must not do these during automated cleanup unless explicitly asked: - Move or rename `.unity`, `.prefab`, `.asset`, or `.meta` files. - Rename serialized fields. - Rewrite core architecture. - Upgrade Unity, packages, or third-party plugins. - Modify Project Settings broadly. - Reorganize folders for aesthetics. - Delete assets just because text search does not find references. - Change public gameplay behavior without a test or explicit requirement. ## Required Process 1. Read `AGENTS.md` and this file. 2. Pick at most one small maintenance concern. 3. Search for references before deleting code. 4. Avoid asset moves and serialized field renames. 5. Run `./tools/validate-unity.sh` if Unity is available. 6. If no safe cleanup exists, leave the repository unchanged. ## Documentation Sync Scope Agents may update factual sections only: - Project structure - Scene list - Assembly list - Entry points - Test commands - Build commands - Asset locations - Validation commands Agents must not rewrite style, tone, architecture principles, or coding rules unless explicitly asked. ## Cleanup Prompt ```markdown Read `AGENTS.md` and `docs/cleanup.md`. Make one small, safe maintenance improvement only. Prefer C# cleanup over asset moves. Do not rename serialized fields. Do not move `.unity`, `.prefab`, `.asset`, or `.meta` files. Do not modify third-party assets. If no safe cleanup exists, leave the repository unchanged. Before finishing, run `./tools/validate-unity.sh` if Unity is available. ``` ## Final Response Checklist - State the single cleanup concern addressed. - State files changed. - State validation run status. - State any skipped validation and why. ```` ]]> Tue, 05 May 2026 08:15:59 GMT https://reader-feed.pages.dev/posts/b1fcec706a-%E5%88%A9%E7%94%A8%E5%99%A8%E5%B7%A5%E7%A8%8B%EF%BC%9A%E4%B8%BA%E7%BC%96%E7%A0%81%E4%BB%A3%E7%90%86%E5%87%86%E5%A4%87Unity%20CSharp%E4%BB%A3%E7%A0%81%E5%BA%93.md obsidian:17b3ee175c:Clippings/我用 Cloudflare 免费搭了一套 AI 内容流水线，真的能跑起来.md 我用 Cloudflare 免费搭了一套 AI 内容流水线，真的能跑起来 每天刷那么多信息，有用的记不住、存不下、找不到。看到一篇好文章，丢进收藏夹吃灰；想做个行业周刊，每周手动复制粘贴、用翻译器转录、再搞排版，没干两周就放弃了。信息过载的时代，个人创作者最大的痛点其实不是“缺内容”，而是“缺自动化的工作流”。那能不能一个人，不买云服务器，不掏月租，靠... 我的 AI 科技周刊

每日 AI 科技精选

``` 在 Dashboard 里新建一个 Pages 项目，把这俩文件扔上去，或者用命令行一键部署。连上 D1 binding，你的个人内容订阅站就正式上线了。 最终展示页 ![图像](https://pbs.twimg.com/media/HHOQ9_tbsAAtfxF?format=jpg&name=large) ## 免费额度到底够不够用？ 很多朋友一听到“全家桶”，第一反应就是“这跑起来不得破产？” 我们来算笔账。假设你搞的这个周刊，每天自动抓取 **50 篇** 文章进行 AI 翻译和总结，你的前端页面每天有 **1000 次** 访问。 ![图像](https://pbs.twimg.com/media/HHORDvoagAAkEoq?format=jpg&name=large) 结论很明确：**只要你不拿它做商业级别的大型爬虫，对于个人或者小团队的内容流自动化，Cloudflare 的免费套餐通常已经足够起步。真正上线前，还是建议按自己的抓取频率、AI 输出长度和访问量重新算一遍。** ## 几个防踩坑与进阶玩法 1. **Cron 触发的超时问题**：免费版 Workers 有 CPU 运行时间限制。如果你一次性抓 100 篇文章喂给 AI，很可能会超时。建议用多个短频快的定时任务（比如每 2 小时抓 5 篇），或者利用 Queue 把抓取和 AI 分析拆成异步。 2. **AI 的神经元（Neurons）计算**：Workers AI 现在的免费额度是按 Neurons 算的。尽量选 [@cf/meta](https://x.com/@cf/meta)/llama-3.1-8b-instruct-fast 这样的小且快模型，便宜好用。 3. **加点“料”：Vectorize 语义搜索**：如果你想在页面上加一个“按意思搜文章”的功能，可以把 AI 生成的文本再过一遍 Embedding 模型，存进 Cloudflare Vectorize 库里，瞬间变成高阶版的 RAG。 4. **邮件推送**：如果还想做邮件版周刊，可以再接邮件发送服务或 Cloudflare 的邮件相关能力。这里要注意，收信转发、处理来信和主动发信不是一回事，具体实现前要先确认当前账号可用的发送方式。 ## 结语 从抓取、清洗、AI 提炼、存储、到最终的发布。我们只用了不到两百行代码，零服务器成本，就在云端拼起了一个完整的“编辑部”。 这就是 Serverless + AI 带来的恐怖生产力。你不需要再陷在日常的 Ctrl+C 和 Ctrl+V 里，那些重复的信息筛选工作，完全可以交给机器在你看不到的边缘节点上默默完成。 如果你也有兴趣搞这么一套，可以先去官网注册个账号。准备好你的 API 源，建个 D1 跑跑看。 你手头现在最想自动化的是什么内容流？小红书笔记？竞品公众号？还是投资研报？在评论区聊聊，没准你的痛点大家都有同感。**更多 AI 干货同步更新公众号：雨哥聊AI，关注我带你玩转 AI 时代！** ]]> Sun, 03 May 2026 16:12:27 GMT https://reader-feed.pages.dev/posts/17b3ee175c-%E6%88%91%E7%94%A8%20Cloudflare%20%E5%85%8D%E8%B4%B9%E6%90%AD%E4%BA%86%E4%B8%80%E5%A5%97%20AI%20%E5%86%85%E5%AE%B9%E6%B5%81%E6%B0%B4%E7%BA%BF%EF%BC%8C%E7%9C%9F%E7%9A%84%E8%83%BD%E8%B7%91%E8%B5%B7%E6%9D%A5.md obsidian:f84dc57613:Clippings/用 Claude Code 将三万行 Go 项目移植到 Rust：Agent Team 实践与 Harness 效率优化.md 用 Claude Code 将三万行 Go 项目移植到 Rust：Agent Team 实践与 Harness 效率优化 以 mihomo（Clash Meta）代理内核的 Rust 移植为案例，分享使用 Claude Code Agent Team 进行大型项目移植的完整实践——从角色分工、里程碑规划到 CLAUDE.md 与 Memory 系统的效率调优。 ` trait object 而非泛型（因为运行时需要根据 YAML 配置动态组合传输层链） 2. **PM** 将 ADR 翻译为路线图中的四个有序任务（A-1 到 A-4），标注依赖关系——"VMess 在 A-2 完成后解锁" 3. **Engineer** 按序实现：先建 crate 骨架和 TLS 层，迁移 Trojan；然后 WebSocket 层，迁移 v2ray-plugin；然后手写 gRPC gun 帧；最后 HTTP/2 和 HTTPUpgrade 4. **QA** 在每一步验证集成测试仍然通过： `trojan_integration` 和 `v2ray_plugin_integration` 不能因迁移而中断 这个流程看起来很重——四个角色处理一个 crate 的创建。但正是这种结构化保证了几件事：gRPC 没有引入不必要的依赖（Architect 决策）、构建顺序没有被打乱（PM 管控）、迁移过程中测试一直是绿的（QA 验证）。 ![Spec 驱动开发流水线：以 Transport Layer 为例](https://maxlv.net/assets/2026/chart-mihomo-spec-workflow.svg) ## CLAUDE.md：Harness 效率的核心杠杆 CLAUDE.md 是 Claude Code 在每次会话开始时自动加载的指导文件。它是提高 harness 效率最重要的手段——写得好，agent 不需要每次都重新探索项目结构。 mihomo-rust 的 CLAUDE.md 只有 101 行，但信息密度很高： ```markdown ## Build Commands cargo build --release cargo test --lib cargo test --test rules_test # 78 rule matching tests cargo test --test trojan_integration # embedded mock server cargo test --test shadowsocks_integration # requires ssserver ## Architecture Listeners → Tunnel (routing) ←→ DNS Resolver | Rule Matching | Proxy Adapters / Groups → Remote Server REST API (Axum) → Runtime control ## Key Patterns - ProxyAdapter trait — all protocols implement this - Rule trait — all rule types implement this - Tunnel — Arc-shared routing engine ``` ### 写好 CLAUDE.md 的几个原则 **只写不能从代码推断的信息。** 不要列出每个文件的路径——agent 可以用 Glob 找到。要写的是：哪些 trait 是架构骨架、哪些测试需要外部依赖（ssserver）、构建命令有什么特殊参数。 **写清楚扩展点。** "如何添加新协议" 和 "如何添加新规则类型" 各三行，告诉 agent 需要改哪三个文件。这比写一整段架构描述更有效——agent 需要的是 actionable 的指令。 **不要写过时的信息。** CLAUDE.md 不是变更日志。如果某个决策已经落实到代码里（比如 fake-ip 已经被移除），就不需要在 CLAUDE.md 里再解释为什么移除。 ## Memory 系统：跨会话的经验积累 Claude Code 的 Memory 系统允许在会话之间持久化信息。mihomo-rust 项目积累了 7 条 memory，全部是 `feedback` 类型——即对 agent 行为的纠正或确认。 几条有代表性的： ### "不要在 router 上加 CatchPanic" ``` TEXTprohibits adding CatchPanic or panic-absorbing middleware to axum router. Task #26 requires panics in spawned tokio tasks to abort the process so failures are detectable. ``` 这条 memory 源于一次具体事件：Engineer agent 试图在 Axum router 上加 `tower::catch_panic` 来 "提高健壮性"。但 QA 的测试计划要求 panic 必须导致进程终止，以便在 soak test 中被检测到。保存这条 memory 后，后续会话中 Engineer 不再犯同样的错误。 ### "tokio::time::pause() 不虚拟化系统调用" ``` TEXTtokio::time::pause()/advance() only affects sleep/Instant futures, not kernel syscalls like TcpStream::peek(), read(), recv(). ``` 这条是 Engineer 在写 sniffer 测试时踩的坑。 `tokio::time::pause()` 看起来可以用来加速超时测试，但它只影响 tokio 自己的定时器，不影响实际的 socket IO。这个知识点保存后，在后续编写 boring-tls 测试时直接规避了同样的陷阱。 ### "里程碑完成时必须重启所有 teammate" ``` TEXTMandatory shutdown and respawn all four teammates at milestone completion. Respawn with model assignment: architect=opus, pm/engineer=sonnet, qa=haiku. Do not clear mid-milestone or if any state isn't saved. ``` 这是最重要的一条操作规范。Agent Team 的上下文窗口是有限的——经历一整个里程碑的讨论后，上下文中充满了过时的中间状态。在里程碑边界处 "重启" 所有 agent，让它们从干净的状态重新读取文件系统中的文档，比带着旧上下文继续工作更高效。 ## 上游分歧策略：ADR-0002 的实践价值 移植项目最棘手的问题之一是：上游的 bug 要不要复制？ ADR-0002 定义了一个简单的二分类法： - **Class A（安全/隐私/路由意图）** ：硬错误，拒绝加载。用户读配置文件时会误以为自己得到了 X，实际上得到的 Y 更不安全 - **Class B（性能/兼容性）** ：警告一次，继续运行。流量到达正确目的地，只是走了更慢的路径 ![上游分歧策略：二分类决策框架](https://maxlv.net/assets/2026/chart-mihomo-divergence.svg) 具体案例： | 场景 | 上游行为 | mihomo-rust | 分类 | | --- | --- | --- | --- | | VMess `cipher: zero` | 接受，明文传输 | 解析时报错 | A | | `alterId > 0` | 运行废弃的 MD5 密钥推导 | 警告并强制为 0 | B | | sniffer peek IO 错误 | 静默跳过 | 记日志，保留原始 metadata | A | | `default-nameserver` 包含 `tls://` | 接受，运行时 bootstrap 死循环 | 加载时报错 | A | 这个分类法的价值在于：它让 Engineer agent 在实现过程中遇到 spec 未预见的边界情况时，有一个明确的默认规则——"不确定时选 Class A（硬错误），在 PR 描述中标注"。这比每次都暂停来请求 Architect 决策高效得多。 对 QA 来说，测试用例中引用分歧分类（ `Class A per ADR-0002: upstream accepts, we reject` ）让审查者一眼就能判断测试的意图。 ## Spec 驱动开发：40 份文档不是官僚主义 项目产出了 40 份 spec 文档和对应的测试计划。这看起来像是过度工程，但在 agent team 的协作模式下，spec 是协调四个 agent 的关键工具。 每份 spec 的固定结构： 1. **YAML schema** ：配置文件中的字段定义 2. **Struct shapes** ：Rust 结构体的字段和类型 3. **Error types** ：所有错误情况的枚举 4. **Divergences table** ：与上游的分歧，引用 ADR-0002 分类 5. **Test plan** ：测试矩阵（独立文件） 为什么 spec 比直接告诉 Engineer "去实现 VLESS" 更高效？ 因为 **spec 是 agent 之间的接口协议** 。Architect 在 spec 的 struct shapes 部分定义类型签名，Engineer 实现它们，QA 根据 spec 的 error types 生成测试用例。没有 spec，每个 agent 都需要自己去读上游 Go 代码来理解应该怎么做，这会导致三个 agent 对同一个问题产生三种理解。 一个具体的数字：transport-layer.md 这份 spec 覆盖了 M1.A 的全部四个子任务，因为 ADR-0001 已经确定了架构。spec 只需要填充 YAML schema、struct shapes 和 per-layer 测试——大约 200 行。而 Engineer 根据这 200 行 spec 产出了整个 `mihomo-transport` crate 的代码。 ## 效率优化：踩过的坑和学到的经验 ### 1\. 上下文窗口是最稀缺的资源 Agent team 中每个 agent 都有独立的上下文窗口。长时间运行的会话会导致上下文被早期的探索、失败尝试和中间状态填满。解决方案： - 在 CLAUDE.md 中写清楚关键信息，让 agent 不需要每次都重新探索 - 里程碑边界处重启所有 agent - 用文件系统（docs/、specs/）而不是上下文窗口来传递状态 ### 2\. 文档是给 Agent 写的，不只是给人写的 传统软件项目中，文档是写给下一个读代码的人看的。在 agent team 模式下，文档同时也是 agent 的 "system prompt"——它们通过读取 `docs/` 来理解项目状态和决策历史。 这意味着文档的写法需要调整： - **用表格代替散文。** Agent 解析表格比理解段落高效 - **引用要精确。** "参见 ADR-0001" 比 "参见之前的架构讨论" 好，因为 agent 可以直接定位文件 - **状态要明确。** 每个工作项标注 "completed / in-progress / blocked"，而不是 "我们之前讨论过这个" ### 3\. Memory 要精简且可操作 Memory 系统的陷阱是存太多信息。mihomo-rust 只保存了 7 条 memory，全部是 feedback 类型——即 "不要做 X" 或 "做 Y 时注意 Z" 的规则。 不保存的东西： - 代码模式和约定（从代码本身可以推断） - Git 历史（ `git log` 更权威） - 调试方案（修复已经在代码里了） - 临时任务状态（用 task 系统而非 memory） ### 4\. 测试是验证 Agent 工作质量的唯一可靠手段 Agent 生成的代码看起来可能是正确的，但 "看起来正确" 不等于 "运行正确"。 ![测试基础设施：619 个测试函数覆盖 5 个层次](https://maxlv.net/assets/2026/chart-mihomo-test-coverage.svg) mihomo-rust 的 CI 管线包含： - 100+ 单元测试 - 82 个 API 集成测试 - 78 个规则匹配测试 - 5 个协议级集成测试（Trojan、Shadowsocks、v2ray-plugin、VLESS、boring-tls） - Docker 化的 TProxy 端到端测试 - MSRV 校验（确保声称的最低 Rust 版本是真的） 每次 Engineer agent 提交代码后，跑完整测试套件是不可跳过的步骤。在 ECH/uTLS 的开发中，31 个测试用例（包括 C13-C15 的真实 BoringSSL 服务器端到端握手）是判断 "这个 feature 可以合并" 的唯一标准。 ### 5\. 让 Agent 管理自己的状态文档 ECH/uTLS feature 的开发展示了一种有效模式：PM agent 维护一份 `ech-utls-status.md` ，记录 16 个 task 的状态、每个 task 的 owner、完成的 commit hash、以及关键决策（为什么选择 boring 而不是 rustls 做 ECH backend、为什么 `random` profile 在 `TlsLayer::new` 时解析而不是每次连接时）。 这份状态文档既是 agent 团队的协作界面，也是人类审查时的速查表。 ## 数字与成本 一些客观数据： | 指标 | 数值 | | --- | --- | | 总 Rust 代码量 | 31,178 行（117 个源文件） | | Workspace crate 数 | 11 | | 最大 crate | mihomo-proxy（9,797 行，27 文件） | | Git commits | 106 | | Claude 直接 commit | 10 | | Spec 文档 | 40 份（最大 695 行） | | ADR | 2 份 | | 测试函数 | 619 个（408 同步 + 211 异步） | | 集成测试套件 | 24 个 | | CI jobs | 5（lint、test、tproxy、msrv、macos） | | Cargo 依赖 | 375 个 | | 开发跨度 | ~4 周（2026-02-21 至 2026-04-12） | | 单日最高 commit | 27（2026-04-08，M0 sweep + 6 specs） | Claude 直接 commit 只有 10 个（主要是 CI 修复和 simple-obfs 插件），并不意味着 Claude 只贡献了 10 个 commit 的工作量。大部分 commit 的作者是我，但代码是在 Claude Code 会话中协作完成的——我审查、修改、然后以自己的名义提交。Claude 的贡献更多体现在：编写 spec、生成代码初稿、执行重构、维护文档。 ## 总结：什么时候值得用 Agent Team Agent Team 不是银弹。以下场景值得使用： - **项目规模大到一个上下文窗口装不下。** mihomo-rust 有 11 个 crate、31K 行代码、40 份文档。单个 agent 无法同时 hold 住全局架构和局部实现细节 - **需要不同层次的决策。** 架构决策（用不用 tonic）、项目管理决策（M1 先做什么）、实现决策（这个 struct 的字段类型）需要不同的思维模式 - **有明确的文档驱动流程。** Agent team 的协作基于文件系统——如果你的团队没有写 spec 的习惯，agent team 的效率会大打折扣 - **需要在里程碑之间保持一致性。** Memory 系统和文档保证了跨会话的知识不丢失 不值得使用的场景： - 小型项目（< 5K 行），单个 agent 足够 - 探索性原型开发，结构化流程是负担 - 没有测试基础设施的项目——你无法验证 agent 产出的质量 Claude Code 改变的不是 "AI 能不能写代码" 这个问题，而是 "AI 写的代码能不能被工程化地验证和集成"。Agent Team + CLAUDE.md + Memory + Spec 驱动开发构成了一个完整的 harness，让 AI 辅助从 "试试看能不能跑" 变成了一个可重复、可审查、可扩展的工程流程。 ]]> Sun, 03 May 2026 16:01:34 GMT https://reader-feed.pages.dev/posts/f84dc57613-%E7%94%A8%20Claude%20Code%20%E5%B0%86%E4%B8%89%E4%B8%87%E8%A1%8C%20Go%20%E9%A1%B9%E7%9B%AE%E7%A7%BB%E6%A4%8D%E5%88%B0%20Rust%EF%BC%9AAgent%20Team%20%E5%AE%9E%E8%B7%B5%E4%B8%8E%20Harness%20%E6%95%88%E7%8E%87%E4%BC%98%E5%8C%96.md obsidian:f0c0252dcb:workflow/project/利用器工程：为编码代理准备TypeScript代码库.md 利用器工程：为编码代理准备TypeScript代码库 At , I pushed our product team to fully embrace vibe coding with Claude Code and Codex, while enforcing guardrails and code quality standard... Affordance: a use or purpose that a thing can have, that people notice as part of the way they see or experience it. For a coding agent like Claude Code or Cursor to produce productive code instead of "AI slop" that becomes expensive to maintain and clean up later, building a codebase with obvious structure and automated guardrails becomes important. Even the smartest models today can't possibly reason about every edge case without a good harness. And even with coding agents like Claude Code, designing repositories in a thoughtful way can go a long way in improving the quality of the code. 仓库A repository should be treated less like a pile of code that can be executed, and more like an 应被视为代理的**execution environment for agents**. Good vibe coding, therefore, would mean that the environment provides: - Fast validation against "bad engineering" - A constrained blast radius - Guardrails that enforce invariants before commiting - Tests and scripts that the agent can use to "vibe-check" itself ## Make the repository legible to agents 使用并搭建一个单一仓库。如果你想跨多个仓库处理前端和后端微服务，你需要让你的编码代理在这些仓库之间切换上下文，或者赋予它们过于宽泛的权限，让他们能访问同一会话中的所有仓库。这可不好。所以直接用monorepo吧。[PNPM](https://pnpm.io/) ```plaintext apps/ frontend/ backend/ docs/ architecture.md conventions.md packages/ eslint-config/ shared-utils/ shared-tyles/ typescript-config/ CLAUDE.md package.json pnpm-lock.yaml pnpm-workspace.yaml turbo.json ``` monorepo 结构允许你创建多个使用共享包的应用。这些可以是效用和类型定义。此外，我发现将ESLint和TypeScript配置标准化为共享包很有用，这样它们可以轻松导入到新的应用和包中。 例如，一旦你导出类似的ESLint配置，包含在共享包中： ```typescript // packages/eslint-config/base.js import js from '@eslint/js' import eslintConfigPrettier from 'eslint-config-prettier' import turboPlugin from 'eslint-plugin-turbo' import tseslint from 'typescript-eslint' import onlyWarn from 'eslint-plugin-only-warn' /** * A shared ESLint configuration for the repository. * * @type {import("eslint").Linter.Config[]} * */ export const config = [ js.configs.recommended, eslintConfigPrettier, ...tseslint.configs.recommended, { plugins: { turbo: turboPlugin, }, rules: { 'turbo/no-undeclared-env-vars': 'warn', '@typescript-eslint/no-unused-expressions': 'off', '@typescript-eslint/no-unused-vars': [ 'warn', { argsIgnorePattern: '^_', varsIgnorePattern: '^_', caughtErrorsIgnorePattern: '^_', }, ], }, }, { plugins: { onlyWarn, }, }, { ignores: ['dist/**'], }, ] ``` 每个应用和包都可以直接从这个配置导入。 ```typescript // apps/frontend/eslint.config.mjs import { config } from '@my-project/eslint-config/base' export default config ``` ## 技能体现了最佳实践 技能包括 帮助编码代理生成成语代码。当然，很多观点带有强烈主观色彩，所以我们也会写自己的技能，来概括这些年来学到的最佳实践。如果你不知道这些最佳实践应该是什么，可以谷歌一下，或者指向一个展示强大软件工程原则的示例仓库，让它自己设计技能。[NestJS最佳实践](https://github.com/Kadajett/agent-nestjs-skills)[Typescript-advanced-types](https://github.com/sickn33/antigravity-awesome-skills/blob/main/plugins/antigravity-awesome-skills-claude/skills/typescript-advanced-types/SKILL.md) 我们有工程师使用各种不同的代理：Claude、Codex、Cursor 等，所以如果我们想让这些技能在团队成员间有用并共享，我们需要每个编码代理使用相同的技能集。 这就是为什么技能存储在 **.agents** 中，.**codex**、**.claude** 等与主 **.agents** 目录中的技能有符号链接。 ```plaintext .agents/ skills/ typescript-expert/ SKILL.md typescript-advanced-types/ SKILL.md [...] .codex/ skills/ typescript-expert -> ../../agents/skills/typescript-expert typescript-advanced-types -> ../../agents/skills/typescript-advanced-types [...] .claude/ skills/ typescript-expert -> ../../agents/skills/typescript-expert typescript-advanced-types -> ../../agents/skills/typescript-advanced-types [...] [...] ``` ## 经纪人阅读和维护的文档 如果写得好，CLAUDE.md（或等效文件）在提供自我演进的文档方面起到了很大作用。这些文档可以概述架构、技术栈，更重要的是，AI代理应遵守的规则。 ```plaintext # VibeSlop - The Best Vibe Coded Application ## Overview VibeSlop has a NestJS backend and a Nuxt frontend. It is a B2B AI SaaS. [...] ## Notion Documentation **IMPORTANT**: VibeSlop has comprehensive documentation in Notion that should be kept in sync with code changes. **Main page**: https://notion.so/[...] ### Documentation Structure | Section | Page ID | Description | | -------------- | ---------- | ------------------------------ | | Authentication | \`DEADBEEF\` | Auth guards, token types, RBAC | | [...] | [...] | [...] | ### When to Update Notion Docs Update the relevant Notion page when: - Adding new API endpoints → Update API Reference - Adding/modifying entities → Update Database & Entities - Changing auth guards or token handling → Update Authentication [...] ### How to Update Use the Notion MCP tools: - \`mcp__notionMCP__notion-fetch\` - Read existing page content - \`mcp__notionMCP__notion-update-page\` - Update page content - \`mcp__notionMCP__notion-create-pages\` - Create new nested pages [...] ## AI Coding Rules (MANDATORY) These rules are non-negotiable. Every code change — whether new feature, bugfix, or refactor — must comply. Violations must be fixed before committing. ### DTO & OpenAPI Contract [...] ### TypeScript Strictness - **No casting** except \`as const\`. No \`as unknown as X\`, \`as any\`, \`as SomeType\`, \`@ts-ignore\`, \`// @ts-expect-error\`. - **Use enums** instead of magic strings. If a value has a fixed set of options, define an enum. - **Use optional fields sparingly** — prefer union types (\`string | null\`) over optional (\`string?\`) when the field is semantically required but may be absent. - **No re-declaring types** that already exist in \`@my-project/shared-types\`, entity definitions, or generated code. - \`pnpm check-types\` must pass before committing. ### Architecture [...] ### Minimal Changes / No Slop AI-generated code accumulates: narration comments, single-use helpers, dead code from earlier iterations, error handling for cases that can't happen. Before declaring done, re-read your own diff with a hostile eye and cut everything the current implementation doesn't need. The principle is that a bug fix does not need surrounding cleanup, a one-shot change does not need a helper, and previous iterations are obsolete the moment a later iteration supersedes them. - **Re-read the diff end-to-end before finishing.** After several iterations, files carry leftovers — replaced methods, unused imports, stale branches, helpers that nothing calls anymore. Delete them. Git has the history; the codebase does not need a tombstone. - **No narration comments.** Don't explain WHAT (names do that) or reference the task ("added for X", "used by Y flow", "handles issue Z"). Only write a comment when the WHY is non-obvious: a hidden constraint, a workaround, a surprising invariant. - ✗ \`// Loop through findings and send feedback to Slack\` - ✗ \`// Added for the unfurl flow\` / \`// TODO: remove old logic once migrated\` - ✓ \`// Stripe retries webhooks on 5xx — dedupe on event.id before mutating state\` - **No commented-out code, no "removed X" tombstones, no backwards-compat shims for code you just deleted in the same PR.** If it's gone, it's gone. Don't keep a renamed \`_oldMethod\` "just in case". - **No single-use abstractions.** Don't create a helper, wrapper, base class, or custom decorator until a second caller exists. Three similar lines beats a premature abstraction. \`packages/shared-utils/src/status-mapper.ts\` is what justified extraction looks like — used across \`scan/\`, \`findings/\`, and \`cost-estimation/\`. Don't manufacture that bar; let duplication prove it. - **No speculative error handling.** Trust internal callers and framework guarantees. DTOs already validate controller input via \`class-validator\` — a service that receives a typed \`SendFeedbackDto\` (\`src/findings/dto/send-feedback.dto.ts\`) does not re-check that \`reaction\` is a string. Validate only at true boundaries: HTTP input, webhook payloads, external API responses, untyped env vars. - ✗ \`try { return await this.repo.findOne(...) } catch (e) { throw e }\` - ✗ \`if (!user) throw new Error('user required')\` where the parameter type is \`User\`, not \`User | undefined\` - ✗ Wrapping a single \`repo.save()\` in a try/catch that logs and rethrows - **Prefer editing existing files and reusing existing types.** Search \`src/utils/\`, \`src/services/\`, \`src/dto/\`, and \`@my-project/shared-utils\` before writing a new helper. Reuse \`PaginationDto\` (\`src/dto/pagination.dto.ts\`) for paginated endpoints instead of defining \`page\`/\`limit\` again. Reuse entity types from \`@my-project/shared-types\` instead of redeclaring shapes. Don't split a 200-line service into four files unless there's an actual reason. - **Keep the shape minimal.** Controllers stay thin — validate → service → return, no branching, no queries (see \`src/findings/findings.controller.ts\`). DTOs carry request/response fields only, decorated with \`@ApiProperty\` + \`class-validator\` — nothing more (see \`src/findings/dto/send-feedback.dto.ts\`, \`src/dto/pagination.dto.ts\`). Entities stay as columns + relations — no computed getters or lifecycle hooks unless actually needed (see \`src/seat/organization-developer.entity.ts\`). - **Frontend caveat:** UI iteration is where slop compounds fastest — unused props, stale Tailwind classes, dead conditional branches from designs two revs ago, state nothing reads. Same rule applies with more force: read the component top-to-bottom against the current design before declaring done, and delete anything the current design doesn't use. ### Quality Gates - Tests must pass (\`pnpm test\`) before committing. - Linter must pass (\`pnpm lint\`) before committing. - Type-checker must pass (\`pnpm check-types\`) before committing. ``` 这里有几点： 1. 我们通过指示代理更新 Notion 文档来强制执行自我文档开发。这假设使用 Notion MCP。 2. 我们根据过去观察到的行为来执行AI编码规则。例如，我们看到前端代码由于UI迭代的特性，会产生大量杂乱：它旨在产生许多不同的变体，直到开发者满意为止。这意味着编码代理常常留下大量陈旧且死掉的代码。我们发现执行“最小改动”规则帮助很大。 ## “垃圾收集”针对污水 即使我们尽了最大努力，“粗糙代码”依然不可避免。人类以前也不会写出粗糙的代码。但人工智能让我们通过定期审计代码库，比如代码库中出现无引用的函数、过时文档等问题来应对这个问题。 我们通过创建一个GitHub Actions工作流程，每24小时运行一次Claude代码，并提示它： 1. 根据我们在仓库中文档维护的一套规则，清理质量较差的代码。 2. 请根据最新的代码变更更新上述 **CLAUDE.md**。 ```yaml name: Claude Garbage Collection on: workflow_dispatch: schedule: - cron: '0 0 * * *' concurrency: group: claude-garbage-collection cancel-in-progress: false jobs: cleanup: strategy: fail-fast: false matrix: target_branch: - staging runs-on: ubuntu-latest permissions: contents: write pull-requests: write issues: write id-token: write actions: read steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 1 ref: ${{ matrix.target_branch }} - name: Setup pnpm uses: pnpm/action-setup@v3 with: version: 10 - id: auth uses: google-github-actions/auth@v2 with: workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }} service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }} token_format: access_token - name: Set NPM_TOKEN for Artifact Registry run: echo "NPM_TOKEN=${{ steps.auth.outputs.access_token }}" >> "$GITHUB_ENV" - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '24.x' cache: 'pnpm' - name: Install dependencies run: pnpm install --frozen-lockfile - name: Run Claude garbage collection task id: claude-cleanup uses: anthropics/claude-code-action@v1 with: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} base_branch: ${{ matrix.target_branch }} prompt: | Read \`CLAUDE.md\` and \`docs/cleanup/README.md\`. Use \`docs/cleanup/\` as the source of truth for this garbage collection pass. Work only against \`${{ matrix.target_branch }}\` and keep the change scoped to that branch's current state. You may make multiple improvements, but each PR must stay focused on one small, safe maintenance concern. Leave the repository unchanged if there is no clear cleanup to make. additional_permissions: | actions: read claude_args: "--allowedTools 'Edit,MultiEdit,Write,Read,Glob,Grep,LS,Bash(git:*),Bash(bun:*),Bash(npm:*),Bash(npx:*),Bash(pnpm:*),Bash(gh:*)'" sync-claude-md: strategy: fail-fast: false matrix: target_branch: - staging runs-on: ubuntu-latest permissions: contents: write pull-requests: write issues: write id-token: write actions: read steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 1 ref: ${{ matrix.target_branch }} - name: Sync CLAUDE.md with codebase id: claude-md-sync uses: anthropics/claude-code-action@v1 with: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} base_branch: ${{ matrix.target_branch }} prompt: | Your sole task is to update all \`CLAUDE.md\` files so they accurately reflect the current codebase on the \`${{ matrix.target_branch }}\` branch. Steps: 1. Read every \`CLAUDE.md\` file in the repo (root \`.claude/CLAUDE.md\` and any nested ones like \`apps/my-app/CLAUDE.md\`, etc.). 2. Audit each section against the actual codebase: - **Project structure**: list directories under \`apps/my-app/src/\` and update the tree if modules were added, renamed, or removed. - **Key entities**: check \`apps/my-app/src/**/entities/*.entity.ts\` and update the entity table. - **API namespaces**: check all \`@Controller()\` decorators and update the namespace table. - **Key commands**: verify each command in \`package.json\` scripts still exists. - **Environment variables**: check \`.env.example\` and update the env var list. - **Path aliases**: check \`tsconfig.json\` path mappings. - **Shared packages**: check \`packages/*/package.json\` names. - **Guards & auth**: check \`src/guards/\` and \`src/middleware/\` for current guard list. 3. Remove references to files, modules, entities, or endpoints that no longer exist. 4. Add entries for new modules, entities, or endpoints that are missing from the docs. 5. Do NOT change style, tone, or conventions sections — only factual/structural sections. 6. If nothing is out of date, make no changes and do not open a PR. Keep the PR focused: only \`CLAUDE.md\` file changes, nothing else. additional_permissions: | actions: read claude_args: "--allowedTools 'Edit,MultiEdit,Write,Read,Glob,Grep,LS,Bash(git:*),Bash(bun:*),Bash(npm:*),Bash(npx:*),Bash(pnpm:*),Bash(gh:*)'" ``` 这在很多时候产生了易于合并的拉取请求，也为我们节省了无数小时的手动重构和清理工作。它几乎像是一个垃圾回收引擎，在后台清理死代码和陈旧文档，除了审核（大多干净的）PR外，几乎不需要我们手动操作。 ## 让糟糕的代码难以提交 让Claude Code帮你运行**git提交**真是太丢人了......现在这已经成了常态，很多人都这么做。所以最好的做法是使用在提交时强制执行质量的钩子。 ![图像](https://pbs.twimg.com/media/HHXB961a4AAxcF2?format=jpg&name=large) 你可以很容易地设置这个： ```bash pnpm add -D husky lint-staged pnpm exec husky init ``` **package.json**年： ```json { "lint-staged": { "*.{ts,tsx}": ["eslint --fix", "prettier --write"], "*.{json,md,yml,yaml}": ["prettier --write"] } } ``` 这确保所有代码至少在进入 GitHub 前通过了 linting 和格式规则。 测试和排版检查呢？现在是时候更进一步，给这位特工...... ## 一个命令来验证所有内容 经纪人需要一个终点线。功能完成后，功能测试可以通过Playwright或Cursor内置浏览器轻松完成。但它怎么知道代码是否适合审核？ 你可以创建一个这样的脚本，进行类型检查、lints、运行单元测试，并生成生产版本： ```json { "scripts": { "validate": "pnpm typecheck && pnpm lint && pnpm test && pnpm build" [...] } } ``` 然后通过例如**，CLAUDE.md** 指示代理 使用该命令。 ```markdown Before considering a task complete, run: pnpm validate If it fails, fix the errors rather than working around the checks. Do not remove tests or weaken types unless explicitly asked. ``` ## 始终是测试驱动开发 代理只有在能够高度自信地完成“代码→测试/→再次验证代码”循环时，代理才有优势，确保测试/验证步骤真正反映开发者的需求。 这正是经过验证的TDD方法论真正闪耀的地方。首先，你向经纪人描述了预期的规格。你可以为此写一个Markdown文件。接下来，代理生成测试用例。现在，你手动检查这些测试用例，看看它们是否反映你想要的行为： ```typescript it('does not charge customers twice for the same billing period', () => { // ... }) ``` If they don't, then the agent should change the tests. Once you're satisfied with the test spec, then (and only then) get the agent to start doing the real coding work. For coding agents, a good test suite is not only good documentation, but also serve as great supervision. ## CI where local harness engineering isn't enough Local hooks can only catch so many obvious problems. In the end, CI tests are where many bugs are found before they make it to production. One example of where CI tests are most useful is for security. It's no secret that vibe coding has produced a lot more software vulnerabilities in recent months! When agents generate code quickly, they also generate more places for auth checks to be skipped, dependencies to sprawl, and business logic assumptions to break. For example, tools like [GitGuardian](https://www.gitguardian.com/) can catch accidentally-committed secrets, and [Socket](https://socket.dev/) can catch vulnerable or suspicious dependencies to stop supply-chain attacks. For deeper application security issues, especially the kinds generic scanners struggle with, you can also use AI-native tools like [Hacktron](https://www.hacktron.ai/blog/introducing-hacktron-review) in CI to review pull request for real code-level vulnerabilities: broken authorization, unsafe business logic, and other security regressions that require more context than simple pattern matching. The advantage of tools like [Hacktron](https://www.hacktron.ai/blog/introducing-hacktron-review) is that unlike traditional scanners that still rely on known syntactic patterns and AI reviewers that provide only functional testing and code quality issues, Hacktron finds real security vulnerabilties that are introduced throughout the lifetime of your organisation using context-aware analysis to identify the security issues that Claude and Codex miss. ## Always think about affordance I hope this article has been helpful to you. I've outlined some techniques and ways that we think about vibe coding while enforcing code quality and security. The key thing to bear in mind is to always think about what your codebase and development environment is affording to the model. The output of your coding agent will depend heavily on that, because the environment dictates the constraints in which these agents operate. ]]> Sun, 03 May 2026 15:58:15 GMT https://reader-feed.pages.dev/posts/f0c0252dcb-%E5%88%A9%E7%94%A8%E5%99%A8%E5%B7%A5%E7%A8%8B%EF%BC%9A%E4%B8%BA%E7%BC%96%E7%A0%81%E4%BB%A3%E7%90%86%E5%87%86%E5%A4%87TypeScript%E4%BB%A3%E7%A0%81%E5%BA%93.md obsidian:debf23bff4:workflow/ui/很多人问我的 AI UI 工作流，被我完整拆成一条完整链路：先讲需求和目标，再落 UI Spec，再做视觉探索，再进入组件化实现，最后再修复.md 很多人问我的 AI UI 工作流，被我完整拆成一条完整链路：先讲需求和目标，再落 UI Spec，再做视觉探索，再进入组件化实现，最后再修复 这篇是 AI UI 系列的主流程文，核心不是工具介绍，而是把“需求 - UI Spec - 视觉探索 - 组件化实现 - 截图修正 - 交付沉淀”这一整套落地链路讲清楚。 文章重点落在一个判断：AI UI 不能只靠单点工具 账户概览 > 持仓表格 > 信号面板 > 最近活动。 这段话看起来普通，但它会决定后面所有结果。 如果这一步不清楚，AI 会自己补脑。 它可能会把页面做得很炫，但风险模块不突出。 它可能会加很多图表，但真正关键的持仓信息不清楚。 它可能会做得像展示页，但不像一个真实可用的业务页面。 先把目标、用户、主路径和信息优先级讲清楚，后面的工作才有坐标系。 03 \-MaxKing.cc- ## 第二步：把需求变成 UI Spec 需求说清楚以后，我不会马上让 AI 画图。 我会先整理一份 **UI Spec** 。 UI Spec 就是写给 AI 和工程实现看的结构化页面说明书。 它关心的不是“好不好看”，而是页面目的、模块、组件、状态和布局。也就是说，它要把一个还比较模糊的页面想法，拆成后面可以直接执行的结构。 比如一个页面至少要讲清楚： 页面目的是什么？ 目标用户是谁？ 核心动作是什么？ 页面有哪些模块？ 每个模块是什么组件类型？ 有哪些状态？ 桌面端和移动端怎么适配？ 页面怎么验收？ 还是以交易仪表盘举例，可以先写成这样： YAMLMaxKing.cc ``` page: name: 交易仪表盘 purpose: 帮助用户快速查看账户风险、持仓和交易信号 target_user: 个人交易者 / 专业交易员 primary_action: 查看当前账户风险 layout_type: dashboard sections: - name: 账户概览 component_type: Metric Cards priority: high - name: 风险预警 component_type: Alert Card priority: high - name: 持仓表格 component_type: Data Table priority: medium - name: 信号面板 component_type: Signal Cards priority: medium states: - loading - empty - error - normal ``` ![配图2](https://mmbiz.qpic.cn/sz_mmbiz_png/76wHjqI4MlRGoJI09TrIcQlHpj7R8iaRvyuh4XD7lk8UxXdx3eibUwPvVE0oroAcibCIM8A6Eam22Xl18UB6VVDLjeY2etjqXoialDeBqBVOmjY/640?from=appmsg&watermark=1&tp=webp&wxfrom=5&wx_lazy=1#imgIndex=2) 这份东西的价值很大。 因为后面的视觉生成、代码实现、截图修正，都可以围绕它展开。 没有 UI Spec，AI 只能根据一句话或一张图猜结构。 有了 UI Spec，AI 至少知道这个页面应该怎么组织。 UI Spec 是这套工作流里最关键的中间层。 它解决的是： 从“模糊想法”到“可执行页面结构”的问题。 04 \-MaxKing.cc- ## 第三步：再做视觉探索 有了 UI Spec 以后，我才会进入视觉探索。 这里可以用 gpt-image-2 或其他图片生成工具。 但这一步的目标，不是让 AI 随便画一个“高级页面”。 我会明确告诉它： 这张图只是视觉参考，不是最终设计稿。 优先保证页面结构、信息层级和模块关系清楚。 页面要像真实 SaaS 产品界面，不要像概念海报。 不要过度科幻，不要复杂 3D，不要无意义装饰。 后续要能落到 React + Tailwind + 组件库里。 也就是说，视觉探索阶段主要看四件事。 第一，信息层级是否清楚。 用户第一眼能不能看到最重要的信息？ 第二，模块关系是否合理。 账户概览、风险预警、持仓表格、信号面板之间的关系是否清楚？ 第三，视觉密度是否合适。 交易仪表盘不能太空，也不能乱成一团。 第四，是否适合组件化实现。 卡片、表格、按钮、徽章、状态提示能不能拆成真实组件？ 这里有一个很重要的判断： 视觉图不是源头，UI Spec 才是源头。 图片只是帮助我们确认视觉方向。 它不能决定产品结构，也不能替代工程约束。 如果生成图有些细节很好，可以吸收。 如果生成图和 UI Spec 冲突，我会优先相信 UI Spec。 05 \-MaxKing.cc- ## 第四步：组件化实现 视觉方向确认后，才进入代码实现。 这一步我通常会用 Codex / Cursor 这类 coding agent。 但我不会只丢一张图给它。 我会同时给它： \* UI Spec \* 视觉参考图 \* 技术栈 \* 组件库约束 \* 页面状态 \* mock 数据要求 \* 验收标准 比如技术栈可以先约束为： TEXTMaxKing.cc ``` React TypeScript Tailwind CSS shadcn/ui ``` 同时要求它： 优先复用 Card、Table、Badge、Button、Tabs、Alert 这类基础组件。 不要为了还原视觉效果写一堆不可维护的代码。 不要把所有东西写在一个大组件里。 mock 数据集中放在 `mockData.ts` 。 页面必须支持 loading、empty、error、normal 四种状态。 响应式至少支持桌面端和移动端。 代码实现阶段的目标，是根据 UI Spec 做组件化实现，并尽量贴近视觉参考。 这里要接受一个现实：第一版代码通常不会完美。 它可能布局基本对了，但间距不够好。 它可能组件结构对了，但视觉密度还要调。 它可能桌面端能看，移动端还要优化。 没关系。 第一版最重要的是： 能跑起来。 结构是对的。 组件边界是清楚的。 状态没有漏掉。 后续可以截图修正。 06 \-MaxKing.cc- ## 第五步：截图对比与修正 很多人对 AI 页面失望，是因为他们期待一次生成完美结果。 我现在不这么期待。 我更关注它能不能进入一个稳定的修正闭环。 这个闭环是： TEXTMaxKing.cc ``` 参考图 ↓ 代码实现 ↓ 浏览器截图 ↓ 对比差异 ↓ 局部修正 ↓ 再次截图 ``` 这一步非常重要。 因为浏览器里的真实页面，和静态视觉图一定会有差异。 真实页面要处理宽度，要处理数据长度，要处理字体渲染，要处理不同屏幕，要处理 loading、empty、error 状态。 所以我会让 AI 或自己对比： 布局结构是否一致？ 模块顺序是否正确？ 主次信息是否清楚？ 卡片间距是否过松或过紧？ 表格密度是否合适？ 风险预警是否突出？ 移动端是否跑版？ 然后一次只修 3 到 5 个问题。 我不建议直接说： 这个页面不像，重新写。 这样 AI 很容易把已经正确的部分也改坏。 更好的方式是： 请不要重写整个页面，只修正以下 3 个问题：风险预警权重不够、持仓表格信息过挤、移动端卡片间距过大。修改后说明涉及哪些组件和样式。 AI 页面不是一次生成出来的，而是一轮一轮收敛出来的。 07 \-MaxKing.cc- ## 第六步：交付与沉淀 很多人做到页面能用就结束了。 但我现在更关注收尾一步：沉淀。 因为真正有价值的不是这一次页面生成成功，而是下一次能不能更快。 一个页面做完以后，我会尽量沉淀这些东西： 页面需求拆解。 UI Spec。 视觉生成 Prompt。 代码实现 Prompt。 组件拆分方式。 mock 数据。 截图修正清单。 验收标准。 比如交易仪表盘这次做完以后，后面它就可以复用到： 账户首页。 数据看板。 风控页面。 策略监控页面。 后台管理首页。 只需要替换业务字段、模块优先级和视觉风格，就可以快速生成下一版。 不是每次从零开始问 AI，而是把每次成功经验变成模板。 这就是 AI 工作流真正的复利。 我把这套流程整理成了一份《AI UI 落地工作流资料包》。 下一步可以这样做 收藏这篇，后面你做 AI 页面时，先对照工作流顺序再开工具。 如果你也在做页面落地，评论区说出你最卡的一步：需求、UI Spec、视觉、代码还是修正。 想看下一篇就关注，我会继续把 AI 页面前置判断拆开。 \- END - 关于 MaxKing宝藏 我是 MaxKing，全栈开发者、量化交易实践者，也是 AI 重度用户。这里分享的不是遥远概念，而是我在真实使用、搭建和踩坑后留下的判断。 如果这篇文章对你有启发，欢迎 **点赞、在看、转发** ，也欢迎加我好友交流 AI 工具和自动化实践。 AI UI 落地工作流实战：从漂亮图到可上线页面 · 目录 继续滑动看下一个 MaxKing宝藏 向上滑动看下一个 拖拽到此处完成下载 图片将完成下载 AIX智能下载器 保存 ]]> Sat, 02 May 2026 14:45:09 GMT https://reader-feed.pages.dev/posts/debf23bff4-%E5%BE%88%E5%A4%9A%E4%BA%BA%E9%97%AE%E6%88%91%E7%9A%84%20AI%20UI%20%E5%B7%A5%E4%BD%9C%E6%B5%81%EF%BC%8C%E8%A2%AB%E6%88%91%E5%AE%8C%E6%95%B4%E6%8B%86%E6%88%90%E4%B8%80%E6%9D%A1%E5%AE%8C%E6%95%B4%E9%93%BE%E8%B7%AF%EF%BC%9A%E5%85%88%E8%AE%B2%E9%9C%80%E6%B1%82%E5%92%8C%E7%9B%AE%E6%A0%87%EF%BC%8C%E5%86%8D%E8%90%BD%20UI%20Spec%EF%BC%8C%E5%86%8D%E5%81%9A%E8%A7%86%E8%A7%89%E6%8E%A2%E7%B4%A2%EF%BC%8C%E5%86%8D%E8%BF%9B%E5%85%A5%E7%BB%84%E4%BB%B6%E5%8C%96%E5%AE%9E%E7%8E%B0%EF%BC%8C%E6%9C%80%E5%90%8E%E5%86%8D%E4%BF%AE%E5%A4%8D.md obsidian:2aecf3a21b:workflow/ui/别再只让 Codex 写代码了，它更适合接管整条 UI 生产线.md 别再只让 Codex 写代码了，它更适合接管整条 UI 生产线 gpt-image-2 的价值不只是生成漂亮 UI 图，而是让 Codex 把页面方案、视觉稿和前端代码串成一条完整的 UI 生产流水线。 文章重点不在模型参数，而在工作流重排：先拆解，再确认视觉，再回到代码落地。 适合给正在做产品页、内部 Sat, 02 May 2026 14:45:04 GMT https://reader-feed.pages.dev/posts/2aecf3a21b-%E5%88%AB%E5%86%8D%E5%8F%AA%E8%AE%A9%20Codex%20%E5%86%99%E4%BB%A3%E7%A0%81%E4%BA%86%EF%BC%8C%E5%AE%83%E6%9B%B4%E9%80%82%E5%90%88%E6%8E%A5%E7%AE%A1%E6%95%B4%E6%9D%A1%20UI%20%E7%94%9F%E4%BA%A7%E7%BA%BF.md obsidian:1036ed78a6:workflow/ui/不要再直接把 UI 图转成代码了，先看这份 UI Spec 模板.md 不要再直接把 UI 图转成代码了，先看这份 UI Spec 模板 这篇文章回答一个很具体的问题：为什么 AI 生成的 UI 图看起来完整，却不能直接拿去转代码。 核心判断是先补 UI Spec，再做视觉探索和代码实现；UI Spec 负责结构、状态、响应式和复用边界。 文章会用留言场景、信息缺失对比和流程 Sat, 02 May 2026 14:44:54 GMT https://reader-feed.pages.dev/posts/1036ed78a6-%E4%B8%8D%E8%A6%81%E5%86%8D%E7%9B%B4%E6%8E%A5%E6%8A%8A%20UI%20%E5%9B%BE%E8%BD%AC%E6%88%90%E4%BB%A3%E7%A0%81%E4%BA%86%EF%BC%8C%E5%85%88%E7%9C%8B%E8%BF%99%E4%BB%BD%20UI%20Spec%20%E6%A8%A1%E6%9D%BF.md obsidian:fa65f42575:workflow/agent/Agentic Harness Engineering Observability-Driven Automatic Evolution of Coding-Agent Harnesses.md Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses Jiahang Lin <sup>1</sup> <sup>∗‡</sup>, Shichun Liu <sup>1</sup> <sup>∗‡</sup>, Chengjun Pan <sup>2</sup> <sup>∗‡</sup>, Lizhi Lin <sup>3</sup>, 1 ∗‡, Shichun Liu 1 ∗‡, Chengjun Pan 2 ∗‡, Lizhi Lin 3, Shihan Dou 1, Xuanjing Huang 1, Hang Yan 3, Zhenhua Han 3 †, Tao Gui 1 † 1 Fudan University   2 Peking University   3 Shanghai Qiji Zhifeng Co., Ltd ###### Abstract Harnesses are now central to coding-agent performance, mediating how models interact with tools and execution environments. Yet harness engineering remains a manual craft, because automating it faces a heterogeneous action space across editable components, voluminous trajectories that bury actionable signal, and edits whose effect is hard to attribute. We introduce Agentic Harness Engineering (AHE), a closed loop that addresses these challenges through three matched observability pillars: ❶ *component observability* gives every editable harness component a file-level representation so the action space is explicit and revertible; ❷ *experience observability* distills millions of raw trajectory tokens into a layered, drill-down evidence corpus that an evolving agent can actually consume; and ❸ *decision observability* pairs every edit with a self-declared prediction, later verified against the next round’s task-level outcomes. Together, these pillars turn every edit into a falsifiable contract, so harness evolution proceeds autonomously without collapsing into trial-and-error. Empirically, ten AHE iterations lift pass@1 on Terminal-Bench 2 from 69.7% to 77.0%, surpassing the human-designed harness Codex-CLI (71.9%) and the self-evolving baselines ACE and TF-GRPO. The frozen harness transfers without re-evolution: on SWE-bench-verified it tops aggregate success at $12\%$ fewer tokens than the seed, and on Terminal-Bench 2 it yields $+5.1$ to $+10.1$  pp cross-family gains across three alternate model families, indicating the evolved components encode general engineering experience rather than benchmark-specific tuning. Ablations localize the gain to tools, middleware, and long-term memory rather than the system prompt, suggesting factual harness structure transfers while prose-level strategy does not. These results position observability-driven evolution as a practical pathway to keep coding-agent harnesses continually improving alongside their base models. †![Refer to caption](https://arxiv.org/html/2604.25850v3/x1.png) Figure 1: AHE evolves a bash-only seed past every human-designed and self-evolving baseline on Terminal-Bench 2. All three role agents share one base model, isolating the gain to harness edits rather than analyzer or editor capability. ## 1 Introduction Coding agents are increasingly deployed on long-horizon software-engineering tasks, with measurable progress on issue resolution over real-world code repositories [^14] [^46] [^7] and multi-step terminal workflows [^21]. In practice, such progress relies not only on the underlying language model, but equally on the surrounding engineering components: the system prompt that shapes work style, the tools that expose the file system and shell, and the middleware that controls context, execution, and recovery. This collection of model-external, editable components is collectively referred to as the agent’s *harness* [^30] [^18] [^42] [^45] [^33] [^31]. Harness design materially shifts task completion on long-horizon coding benchmarks, even with the base model held fixed [^40] [^42], making harness engineering a first-class lever for improving coding agents. Moreover, the optimal harness is model-specific: a harness tuned for one base model often underperforms on another and must be re-adapted as the base model changes. In current practice, this adaptation is performed manually—developers inspect trajectories, identify recurring failure patterns, and hand-craft edits across prompts, tools, middleware, and skills. Yet as base models advance rapidly [^39] [^38] [^44] [^6] [^36] [^35], this manual loop struggles to keep pace, creating a widening gap between model capability and the harness needed to realize it [^33]. An intuitive direction is to automate this loop with an evolution agent that optimizes harness components based on experience [^1] [^49] [^4]. However, few existing approaches jointly evolve the full set of editable components [^16]; most focus on a single component, typically the prompt [^32] [^50] [^20], skills [^19] [^43], or an in-context playbook [^49]. Jointly evolving multiple components end-to-end faces two structural obstacles: long, unstructured trajectories yield little actionable signal, and tightly coupled harness frameworks make edits beyond the prompt error-prone. This leaves the central question of agent-driven harness evolution open: How can an evolution agent jointly and stably evolve all editable components of a coding agent’s harness? Our central insight is that this question is bottlenecked by *observability*, not by agent capability: once the evolution agent receives structured context over a clear action space, it can reliably converge on better harness designs [^34] [^53]. We implement this in Agentic Harness Engineering (AHE, Figure 2), a closed loop driven by three observability pillars: ❶ *component observability* via a decoupled harness that exposes seven editable component types as files, so each failure pattern maps cleanly to a single component class; ❷ *experience observability* via a layered, drill-down evidence corpus distilled from millions of raw trajectory tokens, so the evolver consumes structured root causes rather than raw logs; and ❸ *decision observability* via a change manifest that pairs every edit with a self-declared prediction, later verified against the next round’s task-level outcomes, so each edit becomes a falsifiable contract and ineffective ones are reverted at file granularity. We empirically validate AHE on Terminal-Bench 2 [^21]: ten iterations lift pass@1 from 69.7% to 77.0%, surpassing the human-designed Codex CLI [^25] and the self-evolving baselines ACE [^49] and TF-GRPO [^4]. Without further evolution, the frozen harness transfers to SWE-bench-verified [^14], and across three alternate base-model families it yields consistent pass@1 gains of $+5.1$ to $+10.1$ pp, with the largest on bases further from saturation, suggesting that AHE encodes coordination patterns that less-saturated models lean on more heavily. A component ablation pinpoints where this gain lives: tools, middleware, and long-term memory each carry the improvement on their own, while the system prompt alone regresses, indicating that factual harness structure transfers across tasks and models whereas prose-level strategy does not. This paper makes three contributions: - We formulate *agent-driven harness evolution* for coding agents and propose AHE, which identifies *observability across components, trajectories, and decisions* as the design pivot and turns every harness edit into a falsifiable, file-level contract through three observability pillars: a decoupled component substrate, a layered trajectory-distillation pipeline, and a change manifest whose self-declared predictions are verified by next-round task deltas. - We empirically show that AHE lifts pass@1 on Terminal-Bench 2 from 69.7% to 77.0%, surpasses human-designed and automated baselines, and produces a frozen harness that transfers across benchmarks and base-model families. - Our analysis reveals two limits of agent-driven evolution: harness components interact non-additively, so stacking effective edits caps the aggregate gain; and the loop’s self-attribution is reliable for fixes but blind to regressions, pinpointing regression foresight as the clearest direction for future self-evolution loops. ## 2 Related Work ### 2.1 Harness Engineering and Evaluation for Coding Agents Harness engineering refers to the practice of designing the system surrounding the model, including its tools, interfaces, memory, execution constraints, and feedback loops, which together shape what an agent can do on long-horizon tasks [^30] [^18] [^40] [^3] [^33] [^31]. Concretely, the harness mediates how the model perceives and acts on its environment: it exposes the action and observation interfaces over which tool-augmented reasoning unfolds [^3], custom agent-computer interfaces for repository navigation, file editing, and command execution [^45], as well as sandboxed execution and orchestration support that keep long-horizon runs reproducible [^42]. Verifying that such systems actually help has driven the parallel maturation of coding-agent evaluation along two axes: task horizon and environmental realism. Coverage extends from short-horizon function-level benchmarks focused on contamination and freshness control [^52] [^12], through repository-scale executable patch resolution [^14] [^46] [^7], to multi-hour, terminal-driven workflows that exercise long-horizon, realistic execution [^22] [^5] [^21]. A parallel infrastructure track packages executable runtimes and verifiers around these benchmarks [^28] [^13] [^47], whose attention to reproducible, traceable, and verifiable execution directly motivates the observation system AHE builds on. ### 2.2 Automated Optimization of LLM Agents Approaches to automated agent optimization differ in what evidence the optimizer observes and what it can edit. Some revise the agent’s own outputs through episodic critique and reflection [^20] [^32] [^9]. Others target prompts and instructions [^15]: structured playbooks [^49], semantic-advantage priors [^4], jointly optimized instruction-demonstration pipelines for multi-stage programs [^27], and reflective updates driven by Pareto-frontier traces [^1]. A separate line edits program structure itself, in the form of skill libraries [^41], scored program and agent archives evolved through mutation [^24] [^11], and graph-structured workflows searched or learned from rollouts [^48] [^51]. AHE tunes the full harness as a combinatorial whole rather than a single editable surface, so cross-component trade-offs become legible to the optimizer. It also keeps the human prior minimal, leaving methodology for the optimizer to discover from rollouts rather than fixing it by hand. We describe the substrate, trajectory analysis, and iteration that realize these choices in Section 3. ## 3 Method AHE turns harness optimization into a closed loop driven by another agent, with the base model held fixed and only the explicit harness edited. Our design principle is that every phase of this loop must be *observable*: AHE faithfully records the artifacts each phase produces (the harness components an iteration writes, the rollout trajectories it generates, the edit decisions it commits) and represents them in structured, layered forms that another agent can read and act on. Three observability layers implement this principle. Component observability (§3.1) is realized by a decoupled, file-level harness substrate that maps each failure pattern to a single component class. Experience observability (§3.2) is realized by a layered evidence corpus distilled from raw rollouts and indexed for drill-down access. Decision observability (§3.3) is realized by a change manifest that pairs every edit with a self-declared prediction the next round verifies. The three layers compose into the iteration of Algorithm 1, which runs unattended round after round. ### 3.1 NexAU: an editable, decoupled harness substrate ![Refer to caption](https://arxiv.org/html/2604.25850v3/x2.png) Figure 2: The AHE pipeline links three observable surfaces into one closed loop. Components, rollout experience, and edit decisions each surface as structured artifacts another agent reads, and every edit becomes a falsifiable prediction the next round verifies. We instantiate the harness $H$ on the NexAU framework [^23] [^37], which exposes seven orthogonal component types as explicit files at fixed mount points in a single workspace: system prompt, tool description, tool implementation, middleware, skill, sub-agent configuration, and long-term memory. The component types are loosely coupled, so adding a middleware does not require editing the system prompt, and adding a skill does not require touching any tool. This decoupling is what realizes component observability: each failure pattern maps to a single component class, giving the evolve agent a clean action space and localizing every pass-rate change to one file rather than scattering it across hundreds of lines of unstructured prompt prose. Each logical edit becomes one commit on the workspace’s git history, which yields file-level diffs and rollback granularity for free. Our seed harness $H_{0}$ is deliberately minimal: a single shell-execution tool, no middleware, no skills, no sub-agents. A seed already fitted to the target benchmark would contaminate every subsequent edit’s attribution, since we could not tell whether a gain came from the loop or from the seed. The minimal seed forces every component AHE adds to earn its place against measured rollouts. ### 3.2 Agent Debugger: layered trajectory evidence We generate $k$ traces for each task in a benchmark using a harness $H$, which may contain errors resulting from the deficiencies of the harness that can be acted on, but scattered across millions of tokens of raw messages. To extract insights from agent trajectories and enable experience observability, we apply Agent Debugger [^17] framework to use an agent to explore trajectories framed as a navigable, file-based environment where each trajectory message lives in its own file and is reached through generic shell and scripting tools. Traces with the same query are placed in one environment, and the debugger is required to analyze the root cause of the failure or the success pattern, which is stored in *per-task analysis* report for each task. The analysis also includes pass/fail status of the task to ground the Evolve Agent. Finally, a *benchmark-level overview* is aggregated from every report into a single document as an entry point for every iteration. In addition to these reports, we also provide *original* traces in case the agents need to verify the claims in the reports. The traces are provided both in raw form and lightly processed to remove unnecessary content. All of these content is provided as files allowing progressive disclosure [^29] which saves on tokens and enable better agent decisions. ### 3.3 Evolve Agent: evidence-driven, auditable edits The Evolve Agent closes the AHE loop. In each round it reads the layered evidence corpus produced by the Agent Debugger, decides which harness components to add, modify, or remove, applies those edits to the workspace, and records the reasoning behind every edit. Two constraints govern these edits, and together they realize decision observability: every edit becomes a falsifiable, file-level claim recorded in a versioned manifest, and the next round’s verdict either confirms or reverts it. The first constraint is controllability: the Evolve Agent writes only inside the harness workspace, while the runs directory, tracer, verifier, and LLM configuration are read-only, and the seed system prompt (Appendix B.1) is marked non-deletable. These restrictions block the shortcuts an unconstrained self-modifier would take, such as disabling the verifier, swapping the model, or raising the reasoning budget, and keep every recorded gain attributable to harness edits. The second constraint is that every change is evidence-driven and ships with a recorded prediction. Each edit attaches a manifest entry that names the failure evidence, the inferred root cause, the targeted fix, and a predicted impact comprising both expected fixes and at-risk regressions; this manifest is the loop’s evidence ledger (see Appendix B.2). In the next round, the loop intersects the predicted-fix and predicted-regression sets with the observed task-level deltas to produce a per-edit verdict. Each edit thereby becomes falsifiable by the next evaluation, which replaces rationale-driven self-justification with a measurable contract between rounds. Algorithm 1 AHE outer loop. seed harness $H_{0}$, base model $M$, benchmark $D$, rollouts per task $k$, max iterations $N$ $H_{\text{best}}\leftarrow H_{0}$ for $t=1$ to $N$ do    $T_{t}\leftarrow\textsc{Rollout}(M,H_{t-1},D,k)$ $\triangleright$ phase 1: $k$ rollouts per task    $\widetilde{T}_{t}\leftarrow\textsc{Clean}(T_{t})$ $\triangleright$ phase 2: drop base64, dedup tool output   if $t\geq 2$ then $\triangleright$ phase 3: attribute prior manifest, then rollback     $V_{t}\leftarrow\textsc{Attribute}(C_{t-1},T_{t-1},T_{t})$     $H_{t-1}\leftarrow\textsc{Rollback}(H_{t-1},V_{t})$   else     $V_{t}\leftarrow\emptyset$   end if    $R_{t}\leftarrow\textsc{AgentDebugger}(\widetilde{T}_{t})$ $\triangleright$ phase 4: layered distillation    $(H_{t},C_{t})\leftarrow\textsc{Evolve}(H_{t-1},R_{t},V_{t})$ $\triangleright$ phase 5: workspace edits + new manifest    $\textsc{Commit}(H_{t},C_{t},t)$ $\triangleright$ phase 6: tag iteration in git   if $\textsc{Pass@1}(T_{t})>\textsc{Pass@1}(H_{\text{best}})$ then $H_{\text{best}}\leftarrow H_{t}$   end if end for return $H_{\text{best}}$ Algorithm 1 composes the three substrates into one iteration: rollout, clean, attribute the prior manifest and revert rejected edits, distill, edit, commit. We run $k\geq 2$ rollouts per task so each task carries a pass-rate signal, which stabilizes pass@1 and lets partial-pass tasks anchor comparative diagnosis. Attribution runs *before* distillation, so its verdict lands inside the evidence corpus and binds each prior manifest entry as a contract rather than a rationale. A one-shot explore agent (Appendix B.3) runs in parallel with iteration $1$ to seed a small number of reusable skills from the NexAU source and public coding-agent references. These skills receive no special protection: from iteration $2$ onward the Evolve Agent may keep, refine, or remove them based on observed rollouts. ## 4 Experiments We organize our empirical study around three questions: where AHE sits on the map of existing approaches to harness design, whether what it produces is portable beyond its optimization target, and what inside the loop drives the gain. Research Questions 1. RQ1 (§4.2): Why agentic harness engineering, rather than human-engineered harnesses or other automated methods? 2. RQ2 (§4.3): Does agentic harness engineering overfit to its optimization target? 3. RQ3 (§4.4): What inside AHE drives its gains, and how reliable is the loop’s self-attribution? ### 4.1 Setup ##### Evaluation. We drive evolution on the full 89 tasks of Terminal-Bench 2 [^21], split as 4 easy, 55 medium, and 30 hard, with per-task timeout extended to 1 hour. For cross-benchmark transfer we evaluate the AHE harness on SWE-bench-verified [^14], 500 tasks across seven repositories. We report two metrics per configuration: pass@1, the mean binary success rate over $k$ rollouts per task; and tokens/trial, the mean per-trial total of prompt plus completion tokens across all LLM calls, in thousands. Infrastructure-aborted or timed-out trials count as failures under pass@1 (matching the official terminal-bench leaderboard) and are excluded from token means to avoid truncated figures. Runtime infrastructure (framework, dispatcher, sandbox, tracer, and concurrency) is detailed in Appendix A. ##### Models. For both the evolution loop and the main experiment of §4.2, all three role agents (the Code Agent, the Agent Debugger, and the Evolve Agent) share one base model, GPT-5.4 [^26] at the high reasoning setting. For cross-model transfer (§4.3), we re-evaluate the Code Agent on five alternate bases: GPT-5.4 at medium and xhigh reasoning, qwen-3.6-plus [^38] [^44], gemini-3.1-flash-lite-preview [^8], and deepseek-v4-flash [^6]. ### 4.2 RQ1: Main Results Table 1: Pass@1 on Terminal-Bench 2 across 89 tasks, by official difficulty. NexAU 0 is the shared seed; ACE, TF-GRPO, and AHE are three self-evolution loops layered on top of it. Bold marks the best per column; ties are all bold.
MethodAllEasyMed.Hard
8945530
Human-designed harness
opencode47.2%75.0%52.7%33.3%
terminus-262.9%75.0%74.5%40.0%
Codex71.9%75.0%80.0%56.7%
Self-evolved from NexAU 0
NexAU 069.7%87.5%78.2%51.7%
ACE68.9%91.7%78.2%48.9%
TF-GRPO72.3%100.0%79.4%55.6%
AHE77.0%100.0%88.2%53.3%
We run a single AHE campaign of ten iterations from the bash-only NexAU 0 seed (§3.1), with $k{=}2$ rollouts per task per iteration on Terminal-Bench 2, finishing in roughly 32 hours; the best resulting configuration is reported as AHE. The two self-evolve baselines ACE [^49] and TF-GRPO [^4] start from the same NexAU 0 seed. ##### AHE outperforms both human-designed and self-evolve baselines. AHE outperforms every baseline on our panel: three human-designed harnesses, opencode [^2], terminus-2 [^10], and Codex-CLI [^25], and the two self-evolve baselines ACE and TF-GRPO. Figure 1 shows the gain accumulates across iterations, with continued evolution pushing pass@1 further above the NexAU 0 seed. By difficulty, the only exception is the Hard tier, where AHE marginally trails Codex-CLI. We trace this gap to interference between AHE’s components on long-horizon tasks rather than to a missing capability: swapping AHE’s long-term memory alone into the NexAU 0 seed, without the other AHE components, already surpasses Codex-CLI on Hard (§4.4.1). ##### Prompt-only self-evolution misses the components that carry AHE’s gain. The gaps to ACE and TF-GRPO trace to a layer mismatch. ACE distills natural-language playbooks the agent reads in-context, and TF-GRPO is a trajectory-feedback variant of GRPO that reinforces successful tool sequences; starting from the same NexAU 0 seed as AHE, neither method opens the surrounding scaffolding to edits. AHE jointly evolves system prompt, tools, middleware, and long-term memory across iterations, and §4.4.1 quantifies which of these layers carries the improvement: swapping in AHE’s tools, middleware, or long-term memory alone yields $+3.3$, $+2.2$, and $+5.6$  pp, while the system prompt alone is $-2.3$  pp. The harness components ACE and TF-GRPO never edit are exactly where the gain lives. ### 4.3 RQ2: Transfer to Unseen Tasks and Base Models AHE’s harness is evolved on Terminal-Bench 2 with GPT-5.4 high. We probe whether it encodes general coding-agent experience or overfits to that target by re-using the workspace as-is, without further evolution, in two off-target settings: a different task surface (SWE-bench-verified) and four alternate base models. Table 2: Cross-benchmark transfer on SWE-bench-verified. ACE, TF-GRPO, and AHE share the NexAU 0 seed and differ only in their self-evolution loop; all four columns run on GPT-5.4. AHE and the two self-evolve baselines are evolved on Terminal-Bench 2 and evaluated without in-domain re-evolution. Per-column bold marks the best; ties are all bold.
Success rate ↑ \uparrowTokens k ↓ \downarrow
RepoN NACETF-GRPONexAU 0AHEACETF-GRPONexAU 0AHE
All50074.6%74.2%75.2%75.6%679582526461
django23179.2%78.8%79.2%81.0%707583527484
sympy7569.3%68.0%70.7%70.7%602572494479
sphinx-doc4461.4%65.9%68.2%70.5%990848731656
matplotlib3470.6%70.6%73.5%73.5%622530486391
scikit-learn3293.8%93.8%93.8%87.5%451378307257
pydata2277.3%77.3%77.3%72.7%563516386338
astropy2259.1%59.1%54.5%50.0%546470667277
##### Cross-benchmark transfer. We re-point the AHE harness at SWE-bench-verified against the seed and the two self-evolve baselines (NexAU 0, ACE, TF-GRPO) under identical infrastructure (Table 2). ACE and TF-GRPO both regress below the untouched NexAU 0 seed in aggregate success while spending $11\%$ to $29\%$ more tokens than the seed: the playbook ACE injects and the trajectory distribution TF-GRPO reinforces were distilled on terminal-bench traces and ride the prompt at every model call, so on a different task surface that text adds cost without reshaping the underlying policy. AHE instead achieves the highest aggregate, with the seed-relative gain concentrating on django and sphinx-doc, the two largest and most token-expensive repositories whose multi-step edit-and-verify loop matches the structure AHE’s tools, middleware, and long-term memory compress on Terminal-Bench 2. Marginal regressions appear only on the three smallest repositories, consistent with pass@1 variance on small repos exceeding the per-repo gain. AHE also cuts aggregate tokens by $32\%$ against ACE, $21\%$ against TF-GRPO, and $12\%$ against the seed: encoding behavior in tools, middleware, and memory rather than in the prompt avoids the per-call re-derivation cost that prompt-only baselines pay. ![Refer to caption](https://arxiv.org/html/2604.25850v3/x3.png) Figure 3: Cross-model transfer on Terminal-Bench 2, 89 tasks. The AHE workspace evolved on GPT-5.4 high is re-evaluated on each base without further evolution, paired against the NexAU 0 seed on the same base. ##### Cross-model transfer. We re-evaluate both the NexAU 0 seed and AHE on the five alternate bases listed in §4.1. Figure 3 reports five positive pass@1 gains from $+2.3$ to $+10.1$  pp. Cross-family gains dominate within-family ones: deepseek-v4-flash moves $+10.1$  pp from $51.7\%$ to $61.8\%$, qwen-3.6-plus $+6.3$  pp from $56.2\%$ to $62.5\%$, and gemini-3.1-flash-lite-preview $+5.1$  pp from $36.5\%$ to $41.6\%$, all above the $+2.3$  pp on GPT-5.4 medium and xhigh. We read this as bases further from saturation leaning more on the coordination patterns AHE has fixed inside tools, middleware, and long-term memory, while a stronger base re-derives the same coordination from its prompt at low marginal cost. Within one family the profile is non-monotone: $+2.3$  pp on medium, $+7.3$  pp on high from §4.2, and $+2.3$  pp on xhigh. AHE’s step budget and per-task timeout were fitted to GPT-5.4 high during evolution; medium has more time-per-step slack but loses a reasoning tier of raw capability, while xhigh pushes more trials past the per-task timeout, which our pass@1 convention (§4.1) counts as failures. Either direction discounts the gain. The load-bearing finding is that all five gains land positive: the AHE workspace is not specific to one provider’s idioms or one reasoning depth. Their magnitude tracks the evolution operating point rather than raw base capability, so we treat the timeout-budget coupling as a generalization hazard discussed in our [Limitations](#Sx1 "In Agentic Harness Engineering: Observability-Driven Automatic Evolution of Coding-Agent Harnesses") section. ### 4.4 RQ3: Analysis We analyze the loop along two architectural choices that §3 places weight on: decomposed components (§4.4.1) and self-declared attribution (§4.4.2). #### 4.4.1 RQ3a: where value accumulates across components Table 3: Component-level ablations on Terminal-Bench 2. Each “+ X only” row swaps a single AHE component into the NexAU 0 seed: long-term memory, tool set, middleware, or system prompt. Per-column best is bolded. | Variant | All | Easy | Medium | Hard | | --- | --- | --- | --- | --- | | | 89 tasks | 4 tasks | 55 tasks | 30 tasks | | NexAU 0 | 69.7% | 87.5% | 78.2% | 51.7% | | \+ memory only | 75.3% | 50.0% | 83.6% | 63.3% | | \+ tool only | 73.0% | 75.0% | 87.3% | 46.7% | | \+ middleware only | 71.9% | 100.0% | 81.8% | 50.0% | | \+ system\_prompt only | 67.4% | 75.0% | 78.2% | 46.7% | | AHE full | 77.0% | 100.0% | 88.2% | 53.3% | Table 3 decomposes the AHE gain at the component level. Each “+ X only” row takes the NexAU 0 seed and swaps in one component from the fully evolved AHE configuration, namely long-term memory, tools, middleware, or system prompt, leaving the other three at their seed defaults. Three of the four single-component variants outperform the seed; the system-prompt swap is the only regression. ##### Each component owns a different failure surface. Memory adds 12 boundary-case lessons (performance margin, queued-over-limit cancellation, evaluator-style closure, source-packaging layout); on Hard the lessons lift it above full AHE, while on Easy they reduce to superfluous re-verification. Tools become a 1364-line shell that auto-surfaces contract hints from files near each command; on Medium it lands within $0.9$  pp of full AHE, while on Hard a built-in publish guard closes the loop too early. Middleware adds a finish-hook that forces one evaluator-isomorphic closure check; on Easy it clears every task, while on Hard it inflates turn count. The system prompt encodes 79 lines of universal discipline whose executability depends on the other three; inserted alone it scores $-2.3$  pp aggregate. ##### Components interact non-additively, capping the aggregate gain. The three positive single-component gains sum to $+11.1$  pp against full AHE’s $+7.3$  pp, and on Hard the memory-only variant exceeds full AHE: memory, middleware, and the system prompt all push toward the same closure-style verification, so stacking them spends turns on redundant re-checks within the long-horizon budget. Since the evolve agent optimises an aggregate dominated by 55 Medium tasks, it converges to a Medium-heavy trade-off that returns part of the Hard memory effect, and we leave interaction-aware evolution to future work. #### 4.4.2 RQ3b: how reliably the loop’s self-attribution tracks reality Each evolution round, our evolve model produces a change manifest naming which Terminal-Bench 2 tasks it expects to fix in the next round and which it flags at risk of regression. We compare the round- $N{-}1$ prediction against the round- $N$ ground truth, computing standard precision and recall over the 89 tasks separately for fixes and regressions. ##### Evidence-driven targeting. The fix panel of Figure˜4 shows the evolve model’s targeting is evidence-driven rather than guesswork. Cross-iteration fix-precision of 33.7% and fix-recall of 51.4% sit roughly 5x above the random-prediction baselines of 6.5% and 10.6%, so each harness edit lands on a real, agent-anticipated target rather than on an arbitrary subset of the panel. ![Refer to caption](https://arxiv.org/html/2604.25850v3/x4.png) Figure 4: Cross-iteration mean precision and recall of the evolve model’s self-predictions across 9 evaluation rounds of the GPT-5.4 AHE loop on Terminal-Bench 2, alongside the random-prediction baseline. Left: fix predictions. Right: regression predictions. ##### Regression blindness. The regression panel tells the opposite story: cross-iteration regression-precision of 11.8% and regression-recall of 11.1% sit only about 2x above their random baselines of 5.6% and 5.4%, so most upcoming regressions go unforeseen. The agent can justify why an edit should help, but it cannot reliably name the tasks the same edit is about to break, which is what produces the non-monotone steps in the evolution curve of §4.2. Closing this gap is the clearest direction for future self-evolution loops. Appendix˜D gives the per-round breakdown. ## 5 Conclusion We introduced Agentic Harness Engineering (AHE), an observability-driven loop that turns a coding agent’s harness into a learnable adaptation surface while the base model remains fixed. AHE exposes components as files, distills rollouts into a layered evidence corpus, and binds each edit to a falsifiable next-round prediction; ten iterations lift pass@1 on Terminal-Bench 2 from 69.7% to 77.0%, and the frozen harness transfers to SWE-bench-verified and three alternate model families. We see harness-level evolution as a complementary axis to model-side training: an externalized, auditable surface where coding-agent experience can accumulate. ## Limitations This work studies a promising but high-variance setting, and the scope of our claims should be interpreted accordingly. ##### Benchmark scope. Our evaluation drives evolution on Terminal-Bench 2 and probes transfer on SWE-bench-verified. Even though the frozen harness transfers to a second task surface and to three alternate base-model families, broader programming languages, repository-scale deployments, and human-in-the-loop workflows remain untested. ##### Evolution operating point. AHE’s step budget and per-task timeout were fitted to GPT-5.4 high during evolution, so cross-model transfer numbers conflate harness portability with operating-point coupling—within one family the gain is non-monotone across reasoning tiers (§4.3). Untangling these factors will require re-running the loop under multiple operating points. ##### Self-modification governance. AHE bounds edits to a workspace, attributes every change in a versioned manifest, and rolls back ineffective edits at file granularity, but it does not provide a complete guardrail stack. Long-horizon harness cleanup and stronger misuse prevention remain incomplete, and AHE should be viewed as a controlled research prototype rather than a fully mature autonomous self-improvement system. ## References ## Appendix A Experimental Setup: Full Details This appendix expands the condensed Setup in §4.1 with the formal metric definitions and the runtime infrastructure. ##### Seed agent. The seed configuration, denoted NexAU 0, is a simple code agent built on the NexAU framework of §3.1 that exposes only the bash tool to the model, with no skills, no middleware, and no long-term memory. Every iteration of the AHE outer loop edits this workspace, so all reported gains are measured against NexAU 0 as the common starting point. ##### Runtime infrastructure. All runs use the NexAU framework of §3.1 to instantiate the coding agent. Harbor dispatches tasks, isolates each rollout, and verifies pass/fail. Every rollout runs inside a fresh E2B remote sandbox, so shell side-effects cannot leak between tasks. InMemoryTracer records trajectories and mirrors them to Langfuse. The Agent Debugger executes at concurrency 16 with a 600-second per-task timeout. ##### Terminal-bench difficulty labels. The official terminal-bench-2 leaderboard 0 partitions the 89-task subset into 4 easy, 55 medium, and 30 hard tasks. ##### pass@1. For a configuration on a task set $D$ with $k$ rollouts per task, let $r_{i,j}\in\{0,1\}$ denote the binary reward of rollout $j$ on task $i$. The pass@1 score is the mean $$ \mathrm{pass@1}=\frac{1}{k|D|}\sum_{i=1}^{|D|}\sum_{j=1}^{k}r_{i,j}. $$ Trials that terminate on an infrastructure exception, such as a sandbox crash or API timeout, contribute $r=0$ rather than being dropped, a strictly harsher convention than discarding failures that keeps our numbers comparable to the official terminal-bench leaderboard. The rollout count $k$ varies across experiments; each table states it explicitly. ##### Token cost and Succ/Mtok. For token cost we count every LLM call as prompt plus completion across the rollout and report the mean over completed trials in thousands, denoted Tokens k; infrastructure-aborted trials are excluded to avoid truncated figures. To compare configurations that trade accuracy for cost we combine the two via $$ \mathrm{Succ/Mtok}=\frac{\mathrm{pass@1}\times 10^{6}}{\mathrm{mean\ tokens\ per\ trial}}, $$ the expected number of successes per million tokens. The main paper reports pass@1 and Tokens k separately so each axis stays legible; Table 4 folds them into Succ/Mtok per repository on SWE-bench-verified, derived from the pass@1 and Tokens k columns of Table 2. Table 4: Cost-efficiency on SWE-bench-verified, reported as Succ/Mtok, the expected successes per million tokens. Values are derived from Table 2 as $\mathrm{pass@1}\times 10^{3}/\text{Tokens k}$. Higher is better. Per-row bold marks the best. | Repo | $N$ | ACE | TF-GRPO | NexAU 0 | AHE | | --- | --- | --- | --- | --- | --- | | All | 500 | 1.10 | 1.27 | 1.43 | 1.64 | | django | 231 | 1.12 | 1.35 | 1.50 | 1.67 | | sympy | 75 | 1.15 | 1.19 | 1.43 | 1.48 | | sphinx-doc | 44 | 0.62 | 0.78 | 0.93 | 1.07 | | matplotlib | 34 | 1.14 | 1.33 | 1.51 | 1.88 | | scikit-learn | 32 | 2.08 | 2.48 | 3.06 | 3.40 | | pydata | 22 | 1.37 | 1.50 | 2.00 | 2.15 | | astropy | 22 | 1.08 | 1.26 | 0.82 | 1.81 | ## Appendix B Prompts and Configurations This appendix gathers the prompts that drive the AHE outer loop together with the seed code agent’s system prompt. The five blocks below reproduce the literal contents of the corresponding files in the public repository at [https://github.com/china-qijizhifeng/agentic-harness-engineering](https://github.com/china-qijizhifeng/agentic-harness-engineering) as of the commit that produced the experiments in Section 4. Jinja-style {{ var }} placeholders are filled in by the harness at runtime. ### B.1 Code Agent Seed System Prompt The seed system prompt loaded into NexAU 0 at iteration 1. It is intentionally minimal: a single tool, three behavioral rules, and three runtime-injected variables. Every iteration after iteration 1 may append rules to this file, and the case study in Appendix C traces the first such append. code_agent_simple/systemprompt.md ⬇ You solve software tasks in a non - interactive setting.Your only tool is **` run_shell_command `**:use the shell to inspect the repo,edit files,run builds / tests,and finish the work.Do not ask the user questions. - Prefer short replies;use the tool for actions. - Before commands that delete or overwrite important data,state briefly what they do. - Long - running processes:use ` is_background:true ` on ` run_shell_command ` (do not use `&` in the command string). Date:{{ date }} Username:{{ username }} Working Dir:{{ working_directory }} ### B.2 Evolve Agent Prompt The Evolve Agent’s system prompt encodes the three hard contracts described in Section 3: workspace-only controllability, evidence-driven changes, and the change-manifest deliverable. It also embeds the directory layout the agent must reason over and the JSON shape of the manifest. evolve_agent/evolve_prompt.md ⬇ {% set ws = workspace_path if workspace_path is defined else " workspace " %} You are the NexAU Evolution Engine -- a meta - agent that iterates on a coding agent ' s harness to maximize ** pass@1 ** (single - attempt success rate) through evidence - based experimentation.You may modify existing components or create new ones (tools,middleware,skills,sub - agents,etc.) as needed. # Core Principles ## 1.Controllability Only ` workspace /` is your playground.Everything else is read - only or off - limits. - Modify ONLY files under ` workspace /` - ` runs /` is READ ONLY -- use it for analysis,never write to it - Do NOT modify LLM config,tracer,verifier,or any infrastructure - Do NOT delete ORIGINAL system prompt rules (those in iteration 1' s ` input / workspace /`) - Full safety constraints are at the end of this document ## 2.Evidence - Driven ** Every change must be traceable to specific failure evidence.** Do not make changes based on intuition,speculation,or " best practices " alone. ** Before making any change,you must have:** 1.** Failure evidence ** -- which tasks failed,and what specifically went wrong (from analysis reports or traces) 2.** Root cause ** -- why it failed,not just what failed 3.** Targeted fix ** -- a change that directly addresses the root cause 4.** Predicted impact ** -- which tasks this should fix,and which tasks might be at risk # Environment {% if ws!= " workspace " %} > ** WORKSPACE PATH **:Your workspace is at `{{ ws }}/` instead of ` workspace /`.All ` workspace /` references below apply to `{{ ws }}/`.Use `{{ ws }}/` in file operations,git commands,and the validation command. {% endif %} > ** Loop convention (IMPORTANT -- read before analyzing ` runs /`):** > You are currently in loop ** iteration `{{ iteration }}`**.Each ` runs / iteration_NNN /` folder mixes ** two ** generations of work: > - ` input /` holds what ** the previous loop (NNN -1)** produced -- this is the workspace that was just evaluated this loop.The benchmark,analysis,and change_evaluation inside ` input /` all describe the ** previous loop ' s ** changes,not yours. > - ` evolve /` holds what ** this loop (NNN)** will produce -- your new changes,which the next loop (NNN +1) will evaluate. > > Concretely:when your query says " Iteration {{ iteration }} evaluation completed ",it means the eval of ** iteration {{ iteration - 1 }}' s changes ** is done (baseline if `{{ iteration }}` = 1).You are now making changes that will be labeled iteration `{{ iteration }}` and evaluated next loop. ``` ./ # work_dir = experiment root |-- {{ ws }}/ # * MODIFY these files | |-- code_agent.yaml # Agent config (tools,middleware,params,sub - agents) | |-- systemprompt.md # System prompt (Jinja template) | |-- LongTermMEMORY.md # Long - term memory (persistent cross - session knowledge,MODIFIABLE) | |-- ShortTermMEMORY.md # Short - term memory (managed by code agent at runtime,DO NOT MODIFY) | |-- tool_descriptions / # Tool YAML definitions | |-- tools / # Tool Python implementations | |-- middleware / # Middleware Python implementations | |-- skills / # Skill packages | `-- sub_agents / # Sub - agent configs (optional,you may create) | |-- runs / # * READ ONLY | `-- iteration_NNN / | |-- input / # Everything this iteration starts with | | |-- workspace / # Workspace being evaluated this loop | | |-- benchmark / # Eval results for the workspace above | | | `-- { timestamp }/ | | | |-- result.json | | | `-- { task_name } __ { id }/ | | | |-- agent / nexau.txt | | | |-- agent / nexau_in_memory_tracer.cleaned.json | | | `-- verifier / reward.txt | | |-- analysis / # ** Pre - built failure / success analysis (READ THIS FIRST) | | | |-- overview.md | | | `-- detail /{ task_name }.md | | |-- variant_selection.json | | `-- change_evaluation.json | `-- evolve / # YOUR outputs this loop | |-- evolve_summary.md | |-- change_manifest.json | `-- variant_N / | |-- workspace / | `-- evolve_trace.json | |-- evolution_history.md # Cumulative history of all iterations (READ) `-- config_snapshot.yaml # Initial config (READ ONLY) ``` # Components ## Available Component Types | Component | Files | Characteristics | When to use | |-----------|-------|----------------|-------------| | ** System Prompt ** | ` workspace / systemprompt.md ` | Advisory -- applies to all tasks | Behavioral rules,workflow guidance | | ** Tool Description ** | ` workspace / tool_descriptions /*.tool.yaml ` | Co - located with tool -- model reads when calling | Clarify tool usage,add examples,warn about pitfalls | | ** Tool Implementation ** | ` workspace / tools /` | Controls tool behavior directly | New capabilities,smarter error handling,output formatting | | ** Middleware ** | ` workspace / middleware /` + ` code_agent.yaml ` | Hooks into agent loop pipeline | Intercept / transform at execution level | | ** Skill ** | ` workspace / skills /` + ` code_agent.yaml ` | On - demand -- loaded when relevant | Reusable workflow patterns | | ** Sub - Agent ** | ` workspace / sub_agents /{ name }/` + ` code_agent.yaml ` | Delegated execution -- isolated context | Offload specialized subtask to child agent | | ** Long - Term Memory ** | ` workspace / LongTermMEMORY.md ` | Persistent cross - session knowledge -- MODIFIABLE | Record recurring pitfalls,proven strategies,environment quirks | | ** Short - Term Memory ** | ` workspace / ShortTermMEMORY.md ` | Session - scoped scratch -- DO NOT MODIFY | _ (read - only for evolve agent) _ | All component types are equally valid and important.Choose the one that best fits the root cause. ### Choosing the Right Component Level For each failure pattern,consider ** all ** component types above -- including creating new ones -- before deciding where to fix. ** Anti - pattern:** If the same failure class persists across 2+ iterations despite fixes at one component level,that level may be the wrong choice.Rollback the ineffective change and re - approach from a different component level. ## Registering New Components ** Creating a file is NOT enough -- register in ` code_agent.yaml `:** - New tool:create `.tool.yaml ` + Python implementation + add entry to ` tools:` list - New middleware:create Python class + add entry to ` middlewares:` list with ` import:` path and ` params:` - New skill:create ` skills /{ name }/ SKILL.md ` folder + add to ` skills:` list - New sub - agent:create ` sub_agents /{ name }/ agent.yaml ` + add to ` sub_agents:` list.Framework ** auto - injects ** ` RecallSubAgent ` tool -- do NOT add it manually. ## How Code Gets Loaded The config directory is added to ` sys.path ` at runtime: - ` binding:tools.file_tools:read_file ` resolves to ` workspace / tools / file_tools / read_file.py ` - ` import:middleware.long_tool_output:LongToolOutputMiddleware ` resolves to ` workspace / middleware / long_tool_output.py ` - ` import:middleware.context_compaction:ContextCompactionMiddleware ` resolves to ` workspace / middleware / context_compaction / __init__.py ` ## LLM Environment Variables At runtime,the harness sets these environment variables ** before ** the code agent starts: | Variable | Description | |----------|-------------| | ` LLM_API_KEY ` | API key for the current LLM provider | | ` LLM_BASE_URL ` | Base URL for the LLM API endpoint | | ` LLM_MODEL ` | Model identifier (e.g.` gpt -5.4`) | ** All components ** -- code agent,sub - agents,and middleware -- use these same env vars: - In agent YAML files:` $ { env.LLM_API_KEY }`,` $ { env.LLM_BASE_URL }`,` $ { env.LLM_MODEL }` - In middleware Python code:` os.environ [" LLM_API_KEY "]`,etc. ** Do NOT hardcode API keys.** Always reference environment variables. ### Middleware can call LLM Middleware has access to the agent ' s LLM client via ` ModelCallParams ` in the ` wrap_model_call ` hook.Use ` LLMCaller ` to make side - calls (e.g.summarize context,classify errors,generate dynamic guidance).See the evolution guide skill for full API reference and examples. ### Sub - Agents use the same LLM Sub - agent YAML configs should use ` $ { env.LLM_MODEL }` / ` $ { env.LLM_BASE_URL }` / ` $ { env.LLM_API_KEY }` in their ` llm_config `.This automatically gives them the same LLM provider as the parent agent. For detailed schemas,creation guides,and code examples,read ` evolve_agent / skills / nexau - evolution - guide / SKILL.md `. # Multi - Variant Results (when present) When the evolution query includes a " Previous Iteration Variant Experiment Results " section,multiple parallel approaches were tested last iteration.Use this signal: - ** Learn from both **:Even the losing variant may have solved tasks the winner did not - ** Combine insights **:If both variants addressed different failure classes,consider merging the effective parts of both approaches - ** Avoid repeating failures **:If a variant ' s approach clearly failed,do not retry it - ** Cross - variant debugger analysis ** groups traces by variant -- use it to understand WHY one approach worked better than the other for specific tasks When your query includes a " MANDATORY Strategy Constraint ",you MUST it.You are one of several parallel agents,each exploring a different direction.Violating the constraint wastes the exploration budget. # Analysis Approach > **[!] MANDATORY:Read ` analysis /` first.** The analysis reports are pre - built summaries of all task failures with root causes already identified.They save you significant time -- do NOT skip them to read raw traces directly. 1.Read ` evolution_history.md ` -- understand what ' s been tried,what worked,what failed 2.** Read ` runs / iteration_NNN / input / analysis / overview.md ` FIRST ** -- this is your primary information source 3.** Read ` runs / iteration_NNN / input / analysis / detail /{ task_name }.md `** for tasks needing deeper investigation 4.Only fall back to reading raw ` nexau_in_memory_tracer.cleaned.json ` when analysis is missing or insufficient -- this should be rare 5.** After creating or modifying middleware **,read at least one ` agent / nexau.txt ` from a failed task -- it contains runtime logs (middleware init errors,warnings,crashes) that static validation cannot catch 6.Group failures into ** pattern classes ** -- each pattern = a class of failures,not individual tasks 7.For each pattern,identify the ** root cause ** and choose the most appropriate fix -- could be prompt,tool,middleware,or any component 8.** Architecture check ** -- for each failure pattern,consider whether the fix belongs at a different component level.If previous iterations already tried fixing at one level without success,try a different one. 9.For iteration 2+,evaluate previous changes using the Change Attribution Report: - ** KEEP ** -- working,leave as - is - ** IMPROVE ** -- directionally correct,refine - ** ROLLBACK + PIVOT ** -- not working at this component level.Rollback the change,then re - approach the same failure pattern from a ** different component level ** ** The sole optimization target is pass@1 ** -- the probability that a single attempt succeeds.Every change you make should raise pass@1.Timed - out tasks count as failures -- analyze why the agent ran out of time.Only pure infrastructure exceptions (sandbox crash,etc.) can be ignored. When the experiment runs k >1 rollouts (indicated in the query),use the extra signal to diagnose: - ** Partial - pass tasks ** (some rollouts pass,some fail) are the most valuable.Compare the passing and failing rollouts of the * same task *,find the divergence point,and make the successful strategy the * reliable default *. - ** pass@k ** gauges capability ceiling but is NOT the target.Your goal is to turn pass@k successes into pass@1 successes by making the winning strategy consistent. ** For iteration 2+:** Compare task results across iterations.Check which tasks flipped (fail -> pass) and which regressed (pass -> fail).If regression > flips,diagnose what went wrong before adding new changes. # Deliverables ## Git Commits Each logical change = one separate commit: ``` cd {{ ws }} && git add - A && git commit - m " chg - N:< short description >" ``` ## change_manifest.json Write to experiment root directory (NOT inside workspace /). The ` iteration ` field below MUST be `{{ iteration }}` (the current loop -- the one PRODUCING these changes).Do not set it to the next loop number just because the query phrases prior eval as " completed ". ``` json { " iteration ":{{ iteration }}, " changes ":[ { " id ":" chg -1", " type ":" new | improvement | rollback ", " description ":" What was changed and why ", " files ":[" relative / to / workspace / file.py "], " failure_pattern ":" The failure class this addresses ", " predicted_fixes ":[" task - name - a "," task - name - b "], " risk_tasks ":[" task - name - c "], " constraint_level ":" middleware | tool_impl | tool_desc | skill | prompt ", " why_this_component ":" Why this component level was chosen over alternatives " } ] } ``` ## Validation Run after all changes:` python evolve_agent / skills / nexau - evolution - guide / scripts / validate_agent.py {{ ws }}/ code_agent.yaml ` ## complete_task Output Include:regression analysis (if iteration 2+),failure patterns found,changes made,predicted impact. # Safety Constraints - Modify ONLY files under ` workspace /` - ` runs /` is READ ONLY - Do NOT modify LLM configuration (model,temperature,max_tokens,reasoning_effort,etc.) - Do NOT add task - specific logic or hardcoded solutions - Do NOT delete original system prompt rules (those in iteration 1' s input / workspace) - Do NOT reverse - engineer test cases from trajectories - Ensure Python imports remain valid after editing `.py ` files - Verify Python syntax after editing `.py ` files > ** LLM Config Hands - Off Rule **:Do NOT modify ` llm_config ` fields.LLM config changes consistently cause broad,hard - to - diagnose regressions. Date:{{ date }} ### B.3 Explore Agent Prompts The Agent Debugger is bootstrapped by two single-shot explorer agents that build the framework knowledge and SOTA reference the Evolve Agent reads as skills. Both prompts enforce a write-early-write-often pattern so the produced skill files are always available even on partial completion. #### B.3.1 Source-code Exploration Agent explore_agent/source_agent/prompt.md ⬇ You are a Source Code Exploration Agent.Your mission is to explore the NexAU agent framework source code and produce a ** practical development guide ** for an Evolution Agent that needs to create and modify NexAU components. # Context ** NexAU ** is an AI agent framework providing tools,middleware,config loading,and an execution loop.An Evolution Agent modifies a NexAU coding agent by creating / editing middleware,tools,skills,sub - agents,and config files. ** The Evolution Agent has NO pre - existing NexAU framework knowledge.** Your output will be its ** sole reference **.Focus on: 1.** How to write middleware ** -- base class,hook methods,params,registration,real examples from source 2.** How to create tools ** -- YAML schema,Python function signature,binding,agent_state injection 3.** How to create skills ** -- SKILL.md format,frontmatter,registration,loading mechanism 4.** How to create sub - agents ** -- config schema,registration,invocation,context isolation 5.** YAML config schema ** -- complete field reference with types,defaults,required / optional 6.** Key runtime behaviors ** -- only what ' s needed to write correct components # Source Code Location (READ ONLY) - NexAU framework:`{{ nexau_path }}` # Output Directory (WRITE) - Skill file:`{{ output_skill_dir }}/ nexau - framework - internals / SKILL.md ` # [!] MANDATORY WORKFLOW:Explore - Write - Refine Cycles ## Phase 1:Scan & Scaffold (iterations 1-15) 1.` list_directory ` and ` glob ` to map the codebase structure 2.Read key files:config dataclasses,hooks.py base class,existing middleware / tool implementations 3.** WRITE the initial SKILL.md ** with whatever you have -- even if incomplete,use "[TODO]" placeholders ## Phase 2:Practical Patterns (iterations 16-60) 4.For each section below,find ** real code examples ** from the source 5.** After each section,immediately ` write_file ` to UPDATE SKILL.md ** 6.Priority order:section 1 Config -> section 2 Middleware -> section 3 Tools -> section 4 Skills -> section 5 Sub - Agents -> section 6 Runtime ## Phase 3:Polish & Complete (iterations 61-80) 7.Fill remaining "[TODO]" sections,add copy - paste templates 8.Call ` complete_task ` ** HARD RULES:** - You MUST call ` write_file ` for SKILL.md ** before iteration 20**.No exceptions. - You MUST call ` write_file ` to update SKILL.md ** at least every 15 iterations ** after that. - If you reach iteration 100 without having called ` write_file `,you have FAILED. - Use ` read_file ` with offset / limit for large files. - Cite ` file:line_range ` for every claim.Include actual code snippets. # Exploration Guide -- What to Extract For each section,find the ** real implementation ** in source code and extract patterns the Evolution Agent can copy. ## section 1.YAML Config Schema (HIGHEST PRIORITY) Find the config dataclass definitions in ` nexau / archs / main_sub / config /`.Document: - ** All top - level fields ** in ` agent.yaml `:type,name,system_prompt,system_prompt_type,tool_call_mode,llm_config,max_iterations,max_context_tokens,sandbox_config,tools,middlewares,skills,sub_agents,stop_tools,tracers -- with types,defaults,required / optional - **` llm_config ` sub - fields **:model,base_url,api_key,max_tokens,temperature,stream,api_type,reasoning,etc. - **` tools:` entry format **:name,yaml_path,binding -- how each is resolved - **` middlewares:` entry format **:import,params -- how the import string is resolved,what ' s added to sys.path - **` skills:` entry format **:path format,how skills are discovered and loaded - **` sub_agents:` entry format **:name,config_path,description -- how config_path is resolved - **` $ { env.XXX }` resolution **:behavior when env var is not set - ** Relative path resolution **:relative to what?(YAML file directory?CWD?work_dir?) ## section 2.Middleware Creation (HIGHEST PRIORITY) Find the middleware base class and several existing middleware implementations.Extract: ### 2.1 Base Class & Hook Methods - What class to inherit from?Find the exact import path and class name. - ** ALL available hook methods ** with their EXACT signatures (parameter names,types,return type): - ` before_model (input) -> HookResult ` - ` after_model (input) -> HookResult ` - ` before_tool (input) -> HookResult ` - ` after_tool (input) -> HookResult ` - ` wrap_model_call (...)` -- how to wrap the LLM call - ` wrap_tool_call (...)` -- how to wrap tool execution - Any others (before_agent,after_agent,etc.) - ** HookResult **:What can it modify?How to inject messages?How to modify tool output?Show the class definition. - ** Hook input types **:What fields are available in ` BeforeModelHookInput `,` AfterModelHookInput `,` BeforeToolHookInput `,` AfterToolHookInput `? ### 2.2 How Params Are Passed - How does ` params:` in YAML map to ` __init__ ` arguments?Find the exact code. - Can middleware access ` agent_state `?How? ### 2.3 Registration - How does ` import:middleware.my_module:MyClass ` get resolved?What directory is added to sys.path? - Ordering:do middlewares execute in YAML order?What about after_ * hooks? ### 2.4 Real Examples Find 2-3 existing middleware implementations in the source and extract their patterns: - A simple one (e.g.,output truncation) - A complex one (e.g.,context compaction) Show the class structure,how params are received,how hooks are implemented. ### 2.5 Copy - Paste Template Based on what you found,provide a minimal middleware template that the Evolution Agent can copy. ## section 3.Tool Creation (HIGH PRIORITY) ### 3.1 Tool YAML Schema Find a tool YAML definition (e.g.,` read_file.tool.yaml `).Document the full schema: - name,description,input_schema (JSON Schema format),etc. ### 3.2 Python Function Signature - How does ` binding:tools.my_module:my_func ` resolve to a Python function? - How is ` agent_state ` injected?Is it based on ` inspect.signature `?What fields does ` agent_state ` have (sandbox,history,etc.)? - What should the function return?How are return values normalized? - What happens if the tool raises an exception? ### 3.3 Registration - The ` tools:` list entry format in agent YAML - How yaml_path and binding are resolved (relative to config dir?work_dir?) ### 3.4 Real Examples Find 2-3 existing tool implementations.Show the function signature,how sandbox is used,return format. ### 3.5 Copy - Paste Template Provide a minimal tool template (YAML + Python). ## section 4.Skill System (MEDIUM PRIORITY) - ** SKILL.md format **:What frontmatter fields are expected (name,description,etc.)? - ** How skills are loaded **:What triggers ` LoadSkill `?How does the agent decide which skill to load? - **` skills:` in agent YAML **:path format (relative to what?),how directories are scanned - ** Skill content **:How is SKILL.md content injected into the conversation?As a user message?System message? ## section 5.Sub - Agent Creation (MEDIUM PRIORITY) ### 5.1 Config - ` sub_agents:` list entry format:name,config_path,description,etc. - Sub - agent ' s own ` agent.yaml ` structure -- does it inherit from parent?What ' s independent? - How config_path is resolved ### 5.2 Runtime - How ` sub - agent -{ name }(message ="...")` is dispatched - Return value:how result flows back to parent - Does sub - agent get its own sandbox? ### 5.3 RecallSubAgent - What does it do?When is it useful? ## section 6.Key Runtime Behaviors (LOWER PRIORITY -- only what affects component writing) Only document behaviors that affect how middleware / tools should be written: - ** Hook execution order **:before_ * top - to - bottom or bottom - to - top?after_ * order? - ** Tool error handling **:What happens when a tool throws?What message does the LLM see? - ** Parallel tool execution **:Are multiple tool calls run in parallel?What controls this? - ** Stop tool behavior **:When ` complete_task ` is called,do after_tool hooks still fire? - ** Context compaction **:When does it trigger?What gets compacted? - ** Token counting **:What function / heuristic is used? ## section 7.Gotchas & Common Mistakes Look for anything that would trip up the Evolution Agent: - Config errors that pass validation but crash at runtime - Middleware hooks that don ' t fire when expected - Tool binding resolution surprises - Sub - agent gotchas (sandbox sharing,nested depth limits) - Import path resolution edge cases # Skill Deliverable Format The skill file MUST start with valid YAML frontmatter,document each section above with copy - paste templates,real source - cited code,and a gotchas table.Target length 400-800 lines. When done,call ` complete_task `. #### B.3.2 Web-research Agent explore_agent/web_agent/prompt.md ⬇ You are a SOTA Research Agent.Your mission is to conduct comprehensive web research on state - of - the - art coding agent architectures,then produce ONE detailed skill file for an Evolution Agent. ** Today ' s date:{{ date }}** -- use this year when searching for recent information. # Context An Evolution Agent iteratively improves a NexAU coding agent ' s configuration to maximize scores on Terminal Bench (a coding benchmark).You must provide it with ** concrete,specific,implementable ** knowledge. ** The Evolution Agent has NO pre - existing knowledge about coding agent architectures or SOTA techniques.** Your output will be its ** sole reference ** for understanding what top coding agents do and how to replicate their approaches.You must provide: 1.** Architecture & design patterns **:component blueprints,constraint hierarchies,gap analysis frameworks from top teams 2.** Exact numbers **:scores,params,thresholds,token counts,timing data 3.** Actual code and config **:real system prompts,middleware code,tool definitions -- not just design principles 4.** Ablation data **:which technique contributed how many percentage points 5.** Latest developments **:new teams,new scores,techniques from {{ date [:4] }} 6.** Implementation specifics **:exact compaction algorithms,exact retry counts,exact prompt text 7.** Failure mode analysis **:what top teams tried and FAILED (negative results are as valuable as positive ones) ** Be comprehensive.** Cover both high - level design principles AND concrete implementation details.Focus on ACTIONABLE FACTS and EXACT DATA. # Output Directory (WRITE) You must produce ONE skill file: 1.`{{ output_skill_dir }}/ coding - agent - sota - research / SKILL.md ` -- architecture,benchmarks,techniques # [!] CRITICAL RULES 1.** WRITE EARLY,UPDATE OFTEN.** Write the skill file after reading the first batch of URLs.Then update it as you discover more information. 2.** Record EXACT data -- reject vague summaries.** - GOOD:" deepagents scored 66.5% on TB2 using GPT -4.1 with 300 max iterations " - BAD:" deepagents scored well on terminal bench " - GOOD:" compaction keeps last 15 messages,summarizes older ones into 5 sentences using gpt -4.1- mini " - BAD:" uses context management with sliding window " 3.** Cite every claim.** Include the source URL for every data point. 4.** Prioritize implementable details over architectural summaries.** 5.** Use {{ date }} year in search queries ** for recent results. # Your Research Protocol ## Phase 1:Read Pre - given URLs (MANDATORY) {% for source in web_sources %} - **{{ source.url }}** Focus:{{ source.focus }} {% endfor %} For each URL: 1.Use WebFetch to read the full page 2.Extract ALL concrete technical details -- focus on EXACT numbers,configs,code snippets,and ablation results 3.Ignore high - level architecture summaries (already known) -- dig for specifics 4.Record the URL as source citation **[L] After reading all pre - given URLs:WRITE the skill file immediately.** Include whatever you have so far.You will expand it in Phase 2. ## Phase 2:Autonomous Deep Research (expand the skill file) Search for MORE information.Target:15-20 web searches total. ### Architecture & Techniques (-> coding - agent - sota - research) 1." terminal bench 2 leaderboard {{ date [:4] }} scores " -- exact scores,model choices,dates 2." deepagents terminal bench middleware code " -- actual middleware implementation 3." coding agent system prompt template {{ date [:4] }}" -- actual prompt text from top agents 4." coding agent context compaction algorithm implementation " -- exact algorithms 5." coding agent pre - completion verification middleware " -- actual code 6." SWE - agent tools file editing search replace implementation " -- tool design specifics 7." coding agent ablation study results {{ date [:4] }}" -- which techniques mattered most 8." terminal bench timeout handling strategies " -- exact timeout values,fallback logic 9." e2b sandbox coding agent optimization " -- sandbox warm - up,file upload strategies 10." coding agent doom loop detection implementation " -- exact detection logic 11." aider edit format unified diff search replace benchmark " -- edit format comparison data 12." Codex agent architecture tools " -- exact tool set and descriptions 13." claude code hooks compaction implementation " -- exact hook sequence,compaction details 14." coding agent negative results failed techniques {{ date [:4] }}" -- what didn ' t work and why For each search result: - Skip overview / summary articles -- look for blog posts with code,configs,or data - If a page is inaccessible,note " INACCESSIBLE:< url >" and move on **[L] After completing research:UPDATE the skill file with all findings,then call complete_task.** # Skill Output Specification ## ` coding - agent - sota - research / SKILL.md ` Must cover the following -- with BOTH design patterns AND exact data: ### Section 1.Leaderboard Data (exact numbers required) For each top agent / team (aim for 10+): | Agent | TB2 Score | Model | Max Iterations | Context Window | Date | Source | |-------|-----------|-------|----------------|----------------|------|--------| | deepagents | 66.5% | GPT -4.1 |???|???| 2025- XX | URL | Also include:score progression history,SWE - bench scores if available. ### Section 2.Concrete Implementation Details (one subsection per top team) For EACH top team,document SPECIFICS (not design philosophy): - ** Exact system prompt ** (copy verbatim if available,or quote key sections) - ** Exact tool definitions ** (tool names,parameter schemas,description text) - ** Exact middleware configs ** (param values:max_iterations =300,threshold =0.75,etc.) - ** Exact compaction algorithm ** (e.g.," keeps last 15 messages as - is,summarizes messages 0- N into a single message using prompt:'...'") - ** Exact retry logic ** (e.g.," retries 3 times with 2 s /4 s /8 s backoff on status 429,500,502") - ** Exact loop detection ** (e.g.," tracks { tool_name + first_arg:count },injects warning at count =4") - ** Exact pre - completion check ** (e.g.," intercepts complete_task,injects message:' Before completing,verify:(1)...(2)...(3)...'") ### Section 3.Technique Ablation Data (measured impact required) For each technique,document the MEASURED impact: | Technique | Team | Impact | Baseline | With Technique | Source | |-----------|------|--------|----------|----------------|--------| | Pre - completion checklist | LangChain | + X.X % |??% |??% | URL | | Loop detection | LangChain | + X.X % |??% |??% | URL | | Context compaction |???| + X.X % |??% |??% | URL | If exact ablation numbers aren ' t available,note " NO ABLATION DATA " and provide the team ' s qualitative assessment. ### Section 4.Actual Code & Config Examples Collect REAL code and config from open - source agents: - System prompt text (verbatim quotes,as long as needed) - Middleware implementations (actual Python code) - Tool YAML definitions (actual schemas) - Agent config files (actual YAML) ### Section 5.Negative Results & Failed Techniques What did top teams try that DIDN ' T work? - Techniques that were attempted and rolled back - Ablations showing certain changes hurt performance - Common pitfalls documented by teams ### Section 6.Architecture Patterns & Design Principles Synthesize the common patterns across top teams: - ** Component blueprint **:What categories of components do top agents have? - ** Constraint hierarchy **:Which enforcement mechanisms are strongest?(e.g.,tool_impl > middleware > tool_desc > skill > system_prompt) - ** Gap analysis **:How to identify what ' s missing in an agent harness -- map failure patterns to component categories,classify as PATCH vs CREATE. ### Section 7.Actionable Recommendations (with implementation specifics) Top 10 concrete improvements,each with: - ** What **:Exact description of the change - ** Why **:Evidence from research (cite specific scores / ablations) - ** How (in NexAU)**:Which file to modify,what code to write,what config to set - ** Expected impact **:Based on published data - ** Risk **:What could go wrong,based on negative results Target length:**400-800 lines **. # Quality Criteria The skill file MUST: 1.Start with valid YAML frontmatter 2.Cite source URLs for every factual claim 3.Include exact numbers -- NO vague descriptions 4.Include actual code / config snippets from real agents (not fabricated) 5.Flag uncertainty:" UNVERIFIED:..." or " NO DATA " for unconfirmed claims 6.Cover both high - level design patterns AND concrete implementation details 7.Be directly implementable:an Evolution Agent should be able to copy configs / code from this skill When done,call ` complete_task `. ## Appendix C Qualitative Case Study To make the AHE outer loop concrete, we trace four trajectories from failure to fix and the eight changes that produced them. The four trajectories correspond to the four peaks in the best-so-far curve of Figure 1: trajectory 1 to peak 1 at iteration 2, trajectory 2 to peak 2 at iteration 5, trajectory 3 to peak 3 at iteration 6, and trajectory 4 to peak 4 at iteration 8. We split the case study into two parts. Section C.1 narrates the failing-versus-passing rollouts for each of the four trajectories. Section C.2 documents the chg-\* manifest entries shipped by the Evolve Agent on each of the four winning rounds. Trajectory visualizations for trajectories 1 and 3 appear in Figures 5 and 6; the four manifest figures appear in Figures 7, 8, 9, and 10. Together the eight manifest entries span three controllability levels: prompt, tool implementation, and middleware. ### C.1 Trajectories: failing versus passing rollouts #### C.1.1 Trajectory 1: db-wal-recovery ##### The task. db-wal-recovery asks the agent to reconstruct a SQLite database from a corrupted write-ahead log file, abbreviated WAL, by applying both new-row inserts and value updates encoded in the WAL, and to emit the reconstructed table as /app/recovered.json. The verifier is exact: it loads the JSON and asserts every row’s fields against a known ground truth, including updated values on pre-existing rows. ##### Trajectory before and after the iteration-2 changes. On the NexAU 0 seed the task passed 1 of 2 rollouts. The failing rollout, summarized in the left column of Figure 5, recovered the WAL bytes from a stale shell buffer, invented the missing rows from a guessed pattern, missed that the WAL also encoded mutations to pre-existing rows, and submitted on a self-check that only counted entries. The Agent Debugger grouped this failure under the broader pattern “proxy validation instead of evaluator-isomorphic validation”, where the rollout closes on a surrogate check such as row count, file exists, or script runs rather than on the evaluator’s exact assertions. After the iteration-2 changes are installed, four of the eight new rules fire on this trajectory and are listed in the middle column of Figure 5, each mapped left to the failure step it catches and right to the corresponding step in the passing rollout. The contract-first rule reroutes the agent off the cached-stdout shortcut and forces a re-read of the spec that recasts “WAL changes” as mutations of existing rows. The no-overfit rule blocks the value = id times 100 extrapolation from 5 visible samples. The mirror-the-evaluator rule replaces the json length == 11 self-check with an end-state sweep that asserts the same fields the hidden verifier asserts. db-wal-recovery then passes 2/2 on the next evaluation and remains 2/2 across every subsequent iteration of the run. The Evolve Agent’s predicted\_fixes field for chg-1 did not list db-wal-recovery; the edit was proposed for a different cluster of partial-pass tasks, yet its general phrasing carried it across, illustrating how AHE converts a single-task symptom into a reusable harness rule. Shared prefix, both rollouts, same random seed S1. ls /app → \rightarrow main.db, main.db-wal |  S2. xxd /app/main.db-wal reveals an 0x42 XOR pattern   |  S3. First sqlite3 call auto-checkpoints, the WAL file silently disappears Before chg-1, NexAU 0 seed, iteration 1, reward 0.0 Divergence: invent the missing rows F1. XORs the cached xxd stdout, raw WAL bytes are already gone F2. Reads the 5 visible rows, then assumes the missing rows follow value = id × \times 100 F3. INSERT OR REPLACE rows 6 to 11 with guessed values, writes recovered.json F4. Self-check json length == 11, returns yes, stops here Outcome Submitted values: 100, 200, 300, …, 1100 Hidden verifier asserts value == 150 on id == 1 → \rightarrow AssertionError → \rightarrow 2 of 7 tests fail, reward 0 chg-1 rules that close each gap R1. Contract first. Tests and verifier scripts are the source of truth, not shell history. → \rightarrow catches F1: cached stdout is not the contract. R5. Generalize, do not overfit visible samples. → \rightarrow catches F2: 5 rows are too few to infer the missing 6. R1, second clause. The contract names forbidden extras and multiple-answer requirements. → \rightarrow catches F3: rereading the spec exposes “WAL changes” as mutations of existing rows. R2 + R8. Mirror the evaluator before finishing. Run an end-state acceptance sweep, trust the failing check over a theory, do not substitute a self-invented proxy metric. → \rightarrow catches F4: row count is not the verifier’s check. After chg-1, same seed, iteration 2, reward 1.0 Divergence: re-read the contract, recover the bytes P1. Re-reads task spec verbatim, treats “WAL changes” as mutations of existing rows P2. find / -name "*.wal" returns empty, switches to raw-disk recovery P3. Carves /dev/vda at block 203050, XORs with 0x42, writes back /app/main.db-wal with valid magic 377f0682 P4. sqlite3 now reports 11 rows with value = 150, 250, 300, … P5. Final acceptance sweep mirrors the verifier: ∙ \bullet wal_magic == 377f0682 ∙ \bullet json length == 11, sorted ids == 1..11 ∙ \bullet json rows == db rows Outcome Submitted values: 150, 250, 300, …, 1100 → \rightarrow 7 of 7 tests pass, reward 1 Figure 5: Three-column trajectory comparison for db-wal-recovery before and after chg-1. Both rollouts share the same random seed and the same first three steps S1 to S3, summarized in the banner above the columns. The left column lists the four divergence steps F1 to F4 of the failing rollout. The middle column lists the four chg-1 rules out of eight that fire on this trajectory, each annotated with the failure step it catches. The right column lists the corresponding steps P1 to P5 of the passing rollout. Each F to R to P chain reads across one row of the figure: a failure mode, the rule that names and forbids that failure mode, and the step the rule produces in the passing rollout. chg-1 is a 68-line append to workspace/systemprompt.md with no mention of SQLite, WAL, or db-wal-recovery; the full manifest entry appears in Figure 7. #### C.1.2 Trajectory 2: path-tracing The first trajectory shows a single round of evolution flipping one task. The second shows how the iteration-5 round, which targeted a cross-task “post-validation state destruction” regression, raised the score on tasks the evolve agent had not necessarily named, including path-tracing. ##### The task. path-tracing asks the agent to implement a path tracer that renders a scene description into /app/reconstructed.ppm. The verifier reads that single output file and compares it pixel-for-pixel against a reference image; nothing else in the working tree is read. ##### Trajectory before and after the iteration-5 changes. At iteration 4 the task scored 0/2. The shared failure mode in both rollouts was a four-step sequence: the agent rendered a correct /app/reconstructed.ppm, ran a self-check that confirmed the image matched a structural acceptance criterion, then issued a sweeping cleanup command of the form rm -rf /app/image /app/reconstructed.ppm /app/scratch as a final tidy-up step, and submitted on the shell exit code of that cleanup. The verifier subsequently found no reconstructed.ppm on disk and rejected the rollout. The seed harness’s prompt advice against “destroying verified state” was already present, but no execution-time mechanism enforced it. At iteration 5 path-tracing flips from 0/2 to 2/2. In both passing rollouts the agent reaches the same render-and-self-check state as before, then issues the cleanup; the shell guard intercepts it with a message naming /app/reconstructed.ppm as protected, the agent acknowledges the message and finishes without rerunning the cleanup, and the verifier finds the correct file on disk. The same iteration-5 round also recovers polyglot-rust-c and large-scale-text-editing, both listed in the change-manifest’s predicted\_fixes. configure-git-webserver, also predicted, recovers only partially at iteration 5 because its failure mode involves a state reset path that the iteration-5 guard still treats as overrideable; that gap is closed by the iteration-8 changes described in trajectory 4. #### C.1.3 Trajectory 3: mcmc-sampling-stan The first two trajectories each used a prompt-and-tool pair. The third shows two harness components from different controllability levels, a tool-level publish-state guard and a step-spanning middleware, working together to flip a task that had been failing for five iterations. Figure 6 summarizes the before-and-after rollouts. ##### The task. mcmc-sampling-stan asks the agent to install rstan 2.32.7, fit a hierarchical beta-binomial model to 30 observations, and write the posterior means of alpha and beta to two text files. The verifier installs the package itself and reruns the agent’s analysis.R end-to-end, then asserts alpha lies in \[2.84, 2.91\] and beta lies in \[16.1, 16.7\]. ##### Trajectory before and after the iteration-6 changes. The task scored 0/2 from iteration 1 through iteration 5. The shared failure mode, summarized in the left column of Figure 6, is a proxy-then-skip pattern in five steps: the agent computes an independent grid-integration estimate of the posterior, writes those numbers as the deliverable, fires the real MCMC sampling as a background job, kills it before completion to “preserve the already-created deliverables”, and submits on a final sweep that only checks the files exist and parse as numbers. The verifier then reruns analysis.R from scratch; the unconverged sampler produces values around 1e19, far outside the expected range. None of the prior rounds catches this trajectory: the iteration-2 prompt edit names a contract-first principle but the agent already believes the grid integration is a faithful contract; the iteration-5 publish-state guard protects the deliverable files but treats analysis.R itself as an unprotected scratch artifact. After the iteration-6 changes are installed, both rollouts run analysis.R at the full iter = 100000 to completion, cross-check against an independent scratch full run in /tmp, and publish the converged values via the new override token; the right column of Figure 6 traces the passing rollout. The task passes 6/6 verifier tests in both rollouts and stays 2/2 for the next four iterations. The converged values land at alpha approximately 2.872, beta approximately 16.43, near the centers of the expected ranges. The same iteration-6 round also benefits sam-cell-seg, query-optimize, caffe-cifar-10, dna-assembly, and train-fasttext, all of which match one or more of the seven middleware patterns. Shared prefix, both rollouts, same random seed S1. ls /app → \rightarrow data.csv with 30 rows of columns y, n |  S2. Install rstan 2.32.7 from CRAN as a long background job   |  S3. Author hierarchical_model.stan and analysis.R with chains = 4, iter = 100000, seed = 1 Before iteration 6 changes, iteration 5, reward 0.0 Divergence: trust the proxy, skip the real run F1. Runs an independent R grid integration of the marginal posterior, gets alpha ≈ \approx 2.876, beta ≈ \approx 16.375 F2. Writes those grid values into /app/posterior_alpha_mean.txt and /app/posterior_beta_mean.txt as the deliverable F3. Fires Rscript /app/analysis.R as a background job, polls every 30s F4. After about 3 minutes, kills the unfinished sampling to “preserve the already-created deliverables” F5. Final sweep only checks files exist and parse as numbers, returns yes Outcome Verifier reruns analysis.R; the actual MCMC chain diverges Submitted: alpha = 1.28e19, beta = 2.60e17 → \rightarrow 2 of 6 tests fail, reward 0 Iteration 6 changes that close each gap Middleware chg-2. Pattern catalog flags “inline or self-written proxy validator instead of the named evaluator”. The risk hint is injected into the next model turn. → \rightarrow catches F1, F2, F4: the grid integration is a proxy for the named MCMC pipeline, and the kill of analysis.R keeps that proxy in place. The reminder rewires the next turn toward running the named pipeline to completion. Middleware chg-2, second pattern. Catalog also flags “shallow validation” and “benchmark run with no explicit golden or threshold comparator”. → \rightarrow catches F5: a file-existence sweep without a tolerance comparator on the verifier’s named outputs is forbidden, and an independent re-run with cross-check is required instead. Publish-state guard chg-1. Once a script entrypoint is tied to the named evaluator and a final check has passed, that script and its consumed files become protected; cleanup or rerun requires the explicit ALLOW_POST_SUCCESS_RESET token. → \rightarrow visible at P4 and P5: the override token at every successful submit is evidence the guard is engaged, not silently bypassed. After iteration 6 changes, same seed, iteration 6, reward 1.0 Divergence: drive the evaluator pipeline to convergence P1. Smoke-tests analysis.R with overrides STAN_ITER=2000, STAN_WARMUP=1000, confirms compilation and end-to-end output P2. Runs analysis.R at the full iter = 100000 and waits for completion, gets alpha ≈ \approx 2.872, beta ≈ \approx 16.43 P3. Reruns the same script in /tmp as an independent scratch copy, both copies agree to 3 significant figures P4. Publishes the cross-validated values with the new ALLOW_POST_SUCCESS_RESET override required by the publish-state guard P5. Cleans the unrequested hierarchical_model.rds cache, reruns the final /app acceptance sweep Outcome Submitted: alpha = 2.872, beta = 16.43 → \rightarrow 6 of 6 tests pass, reward 1 Figure 6: Three-column trajectory comparison for mcmc-sampling-stan before and after the two harness changes shipped at the start of iteration 6: the tool-level publish-state guard chg-1 at commit ff0cf3d and the middleware-level execution-risk hints chg-2 at commit 9651986, whose full manifest entry appears in Figure 9. The banner shows the shared prefix S1 to S3. The left column lists the five divergence steps F1 to F5 of the failing rollout at iteration 5. The middle column lists the iteration-6 components that fire on this trajectory, each annotated with the failure steps it catches. The right column lists the corresponding steps P1 to P5 of the passing rollout at iteration 6. The task stays 2/2 for the next four evaluation rounds. #### C.1.4 Trajectory 4: configure-git-webserver The fourth trajectory shows the evolve agent doubling back on its own prior decisions. By iteration 7 the publish-state guard had been carried over for three rounds, the middleware for two, and the score had regressed from 75.8 to 73.0. Rather than roll either back, the iteration-7 round patched a loophole in the guard and a salience gap in the middleware; both patches turn out to be load-bearing for configure-git-webserver. ##### The task. configure-git-webserver asks the agent to set up a git repository under /git/server, configure a webserver that serves the working tree under /git/www, deploy a hello-world page, and produce a configuration in which the externally observable URL returns the expected content. The verifier issues an HTTP request from outside the agent’s shell and reads the response body. ##### Trajectory before and after the iteration-8 changes. At iteration 7 the task scored 0/2. The failing rollout reached a fully working deployment, ran a curl-against-localhost self-check that returned the right body, and then issued two cleanup commands prefixed with ALLOW\_POST\_SUCCESS\_RESET: one deletion of /git/www/hello.html and one reset of /git/server/refs/heads/master to an empty state, both rationalized as “leaving a clean repo for grading”. The shell tool’s iteration-5 guard caught these as overrideable resets and let them through once the override token was attached. The external verifier then received a 404 and rejected the rollout. git-multibranch failed in iteration 7 for the same structural reason. In parallel, polyglot-c-py and pytorch-model-recovery failed at iteration 7 with a different but related symptom: the iteration-6 middleware had already emitted the right warnings about clean-layout violation and inline-helper validation, but the warnings were appended only to the tool output, and on the very next model turn the agent ignored them and published. After the iteration-8 changes are installed, configure-git-webserver flips from 0/2 to 2/2. Both rollouts reach the same successful deployment as before, attempt the same overrideable cleanup commands, and have them refused at the shell layer with hard-block messages naming the protected web root and protected ref; the agent acknowledges the messages, drops the cleanup, and submits the live state. git-multibranch flips along the same path. polyglot-c-py, polyglot-rust-c, pytorch-model-recovery, and mteb-retrieve flip via the middleware path: in each, the FRAMEWORK reminder injected before the next model turn carries enough salience for the agent to fix the violation rather than publish over it. Iteration 8’s overall score lands at 76.97, the run’s high-water mark on Figure LABEL:fig:evolution-curve, and the single biggest jump of the run. ### C.2 Changes shipped on the four winning rounds #### C.2.1 Iteration 2: prompt rules and shell-timeout argument The Evolve Agent’s response after iteration 1 was two changes. Change chg-1 at commit c0b8a05 is a 68-line append to workspace/systemprompt.md with no mention of SQLite, WAL, or db-wal-recovery; the appended block contains eight numbered rules covering acceptance-contract extraction, evaluator mirroring, minimal-edit semantics, candidate scoring, generalization, time budgeting, end-state readiness, and a stop rule. Change chg-2 at commit 169c34c is a tool-implementation edit that exposes the shell timeout as a per-call argument with a higher ceiling, addressing a class of failures in which the seed harness silently truncated long-running setup commands. Both manifest entries appear in Figure 7. chg-1, iteration 1, commit c0b8a05, level: prompt Files ∙ \bullet workspace/systemprompt.md What changed Appended a contract-first workflow of eight numbered rules covering acceptance-contract extraction, evaluator mirroring, minimal-edit semantics, candidate scoring, generalization, time budgeting, end-state readiness, and a stop rule. No SQLite, WAL, or task-specific keywords. Failure pattern fixed Agent submitted on a self-invented proxy check such as row count or file exists, instead of reproducing the evaluator’s literal assertions. Predicted fixes 14 tasks. Examples: configure-git-webserver, query-optimize, mteb-retrieve, train-fasttext. chg-2, iteration 1, commit 169c34c, level: tool Files ∙ \bullet tool_descriptions/run_shell_command.tool.yaml ∙ \bullet tools/shell_tools/run_shell_command.py What changed Exposed a per-call timeout_ms on the shell tool, added background-execution guidance, and appended a timeout-recovery hint to timed-out shell output so the agent can switch to short probes plus background jobs instead of sitting on the default 5 minute wait. Failure pattern fixed Agent burned rollout budget on long foreground installs and sleep-poll loops, repeatedly hitting the default 5 minute timeout. Predicted fixes 8 tasks. Examples: compile-compcert, regex-chess, adaptive-rejection-sampler. Figure 7: Two change-manifest entries written in iteration 1, one editing the system prompt and one editing the shell tool. Both appear in the same change\_manifest.json produced by the evolve agent, then enter Phase 3 of the next round as binding contracts that the attribution check rolls back if their predicted fixes do not materialize. #### C.2.2 Iteration 5: publish-state mechanism (prompt rules + shell-tool guard) The Evolve Agent shipped two complementary changes at the iteration-4 boundary, both written for iteration 5. Change chg-7 at commit 3ba3a90 edits workspace/systemprompt.md together with the descriptor of run\_shell\_command; it adds three rules to the harness’s working memory: a publish-state rule that names the post-acceptance filesystem state as the deliverable surface, a scratch-directory rule for tasks with constrained delivery layouts, and a literal-output rule for DSL, config, and script outputs in which equivalence is judged at the byte level. Change chg-8 at commit 4e0aab9 edits workspace/tools/shell\_tools/run\_shell\_command.py; it installs a stateful publish-state guard inside the shell tool with three behaviors. First, when the shell observes a successful evaluator-style final check, it parses the acceptance command for explicit file paths and roots and records them as protected. Second, when a later command would delete a protected output or reset a protected root, the guard intercepts the command before execution and returns a targeted error explaining which protected target is at risk. Third, the guard accepts an explicit ALLOW\_POST\_SUCCESS\_RESET token from the agent that downgrades the block to a warning and forces the agent to revalidate before submitting. The two changes are paired by design: chg-7 tells the model what publish state is, chg-8 stops the agent from destroying it even when the model forgets the rule. Both manifest entries appear in Figure 8. chg-7, iteration 5, commit 3ba3a90, level: prompt + tool descriptor Files ∙ \bullet workspace/systemprompt.md ∙ \bullet tool_descriptions/run_shell_command.tool.yaml What changed Appended three rules to the harness’s working memory. Publish-state rule: once an evaluator-style final check passes, the resulting filesystem and service state is the deliverable surface and must not be reset to “look clean”. Scratch-directory rule: place exploratory artifacts under /tmp or a scratch path the verifier ignores. Literal-output rule: for DSL, config, or script outputs with byte-level contracts, validate equality at the byte level. Failure pattern fixed Agent reached an evaluator-passing state, then issued sweeping cleanup or rewrote outputs to “tidy up”, leaving the verifier with no deliverable. Predicted fixes 4 tasks. Examples: path-tracing, configure-git-webserver, polyglot-rust-c, large-scale-text-editing. chg-8, iteration 5, commit 4e0aab9, level: tool implementation Files ∙ \bullet tools/shell_tools/run_shell_command.py What changed Installed a stateful publish-state guard inside the shell tool. After a successful evaluator-style final check, the guard parses the acceptance command for explicit file paths and roots and records them as protected. Later destructive commands that would delete a protected output or reset a protected root are intercepted before execution and returned as a targeted error. An explicit ALLOW_POST_SUCCESS_RESET token can downgrade the block to a warning, after which the agent must re-validate before submit. Failure pattern fixed Even with the prompt rule in place, the agent still issued destructive cleanup commands after publish-state. Execution-time enforcement at the shell tool is the most direct interlock. Predicted fixes Same 4 tasks; load-bearing on path-tracing, whose F4 is the rm -rf of /app/reconstructed.ppm. Figure 8: The two change-manifest entries written together at the iteration-4 boundary and shipped as the iteration-5 harness. chg-7 names the publish-state rule in the system prompt and tool descriptor; chg-8 installs the execution-time interlock inside the shell tool. The pair flips path-tracing on the next round. #### C.2.3 Iteration 6: protected entrypoints and execution-risk middleware The Evolve Agent shipped two complementary changes for iteration 6. Change chg-1 at commit ff0cf3d extends the publish-state guard so that script entrypoints tied to the named evaluator become protected after a passing check, with an explicit ALLOW\_POST\_SUCCESS\_RESET token required to override; the token at every successful submit in the passing rollout is the externally visible evidence that the guard is engaged, not silently bypassed. Change chg-2 at commit 9651986 introduces the ExecutionRiskHintsMiddleware; the middleware watches the live sequence of shell commands and tool outputs and emits a targeted note when it detects any of seven cross-step risk patterns: shallow validation that relies on -h, py\_compile, or pure existence checks; localhost-only service validation when the contract names an external endpoint; inline or self-written proxy validators replacing a named evaluator; lower-level model or internal API access when the contract names a specific wrapper; benchmark checks with no explicit golden or threshold comparator; repeated long runs that have already exhausted budget for a known failure mode; and repeated retries against the same error. The two patterns relevant to trajectory 3 are inline-proxy validation and shallow validation, which together cover the F1 to F5 sequence: the grid-integration proxy and the kill of analysis.R are the proxy-validator pattern, and the file-existence sweep without a tolerance comparator is the shallow-validation pattern. The shell tool change covers F4 specifically: with analysis.R now protected, the kill becomes a guarded action that requires the override token and forces a revalidation pass before submit. Both manifest entries appear in Figure 9. chg-1, iteration 6, commit ff0cf3d, level: tool implementation Files ∙ \bullet tools/shell_tools/run_shell_command.py ∙ \bullet tool_descriptions/run_shell_command.tool.yaml What changed Extended publish-state target extraction to include script entrypoints and explicitly referenced final-check files, on top of the deliverable files and roots already covered by iteration 5. After a successful evaluator-style final check, the guard now blocks rewriting protected files and rerunning protected generator scripts, in addition to the deletion and root-reset cases. Failure pattern fixed Agent reached publish-state with a converged generator script, then re-ran or rewrote the script as a “tidy up” pass, invalidating the verified output; this is the F4 step of mcmc-sampling-stan. Predicted fixes mcmc-sampling-stan plus residual “validated then mutate” cases such as configure-git-webserver. chg-2, iteration 6, commit 9651986, level: middleware Files ∙ \bullet workspace/code_agent.yaml ∙ \bullet workspace/middleware/__init__.py ∙ \bullet workspace/middleware/execution_risk_hints.py What changed Registered a new ExecutionRiskHintsMiddleware via an AfterToolHook that scans every shell command and result, accumulates lightweight state across steps, and queues a targeted reminder when the live history matches one of seven risk patterns: shallow validation via --help or py_compile or existence-only checks; localhost-only service check while the contract names an external interface; inline or self-written proxy validator instead of the named evaluator; low-level model API call bypassing the official wrapper; benchmark run with no explicit golden or threshold comparator; repeated long timeouts on the same command shape; repeated retries hitting the same error signature. Reminders are deduplicated and capped per rollout. Failure pattern fixed Cross-step behaviors that only become obvious from the live command history, which prompt-only rules cannot react to in time. Predicted fixes 6 tasks. Examples: caffe-cifar-10, sam-cell-seg, mteb-retrieve, dna-assembly, train-fasttext. Figure 9: The two change-manifest entries shipped as the iteration-6 harness. chg-1 extends the iteration-5 publish-state guard from deliverable files to script entrypoints, the missing piece that protects analysis.R in mcmc-sampling-stan. chg-2 introduces the first cross-step component in this run, namely the ExecutionRiskHintsMiddleware watching the live command history for seven risk patterns. #### C.2.4 Iteration 8: hard blocks and FRAMEWORK reminders The Evolve Agent shipped two changes for iteration 8 that explicitly keep the prior architecture and patch its weak points. Change chg-1 at commit ca35f53 edits workspace/tools/shell\_tools/run\_shell\_command.py and upgrades two soft reasons to hard blocks: deletion of any non-/tmp protected output is now a hard block, and reset of any non-/tmp protected root is now a hard block. The ALLOW\_POST\_SUCCESS\_RESET token can still downgrade other classes of post-success interlocks but can no longer wipe verified live deliverables or empty live roots. Change chg-2 at commit a4a4a29 edits workspace/middleware/execution\_risk\_hints.py and adds three behaviors. First, a new before\_model hook promotes any execution-risk note emitted on the previous step into a FRAMEWORK reminder visible in the next model turn, so the warning becomes part of the reasoning context rather than text appended after the tool output. Second, the middleware infers two contract types once per task from the user request: clean-layout or single-file delivery contracts, and official-wrapper or named-revision contracts. Third, the middleware adds two contract-aware after-tool heuristics: a warning when the agent compiles or builds inside a clean-layout live tree, and a warning when the contract names an official wrapper or revision but the command uses a raw SentenceTransformer or AutoModel style API instead. Both changes are deliberately scoped: chg-1 prevents the destructive shell command itself, chg-2 makes the right warning impossible to overlook on the very next model turn. Both manifest entries appear in Figure 10. chg-1, iteration 8, commit ca35f53, level: tool implementation Files ∙ \bullet tools/shell_tools/run_shell_command.py What changed Upgraded two soft reasons to hard blocks. Deletion of any non- /tmp protected output is now a hard block. Reset of any non- /tmp protected root to an empty state is also a hard block. The ALLOW_POST_SUCCESS_RESET token still exists for other classes of post-success interlock but can no longer wipe verified live deliverables or empty live roots. Failure pattern fixed Agent attached the override token to delete /git/www/hello.html and reset /git/server/refs/heads/master after a successful deployment check, “returning to a clean repo”; verifier then 404s. Predicted fixes 2 tasks. Examples: configure-git-webserver, git-multibranch. chg-2, iteration 8, commit a4a4a29, level: middleware Files ∙ \bullet workspace/middleware/execution_risk_hints.py What changed Added a BeforeModelHook that promotes any execution-risk note emitted on the previous step into a FRAMEWORK reminder visible at the top of the next model turn, so warnings enter the reasoning context rather than trail after the tool output. Added one-time per-task contract inference for clean-layout or single-file delivery contracts and official-wrapper or named-revision contracts. Added two new after-tool heuristics: a warning when the agent compiles or builds inside a clean-layout live tree, and a warning when the contract names an official wrapper but the command uses a raw SentenceTransformer or AutoModel style API instead. Failure pattern fixed Iteration-6 middleware emitted the right warnings but only into tool output; the agent often made the publish/stop decision on the next model turn and ignored them. Salience promotion plus contract-aware heuristics close this gap. Predicted fixes 4 tasks. Examples: polyglot-c-py, polyglot-rust-c, mteb-retrieve, pytorch-model-recovery. Figure 10: Two change-manifest entries written together at the iteration-7 boundary and shipped as the iteration-8 harness. chg-1 hardens the existing publish-state shell guard so that the override token can no longer wipe verified live deliverables. chg-2 makes execution-risk warnings impossible to overlook at the next model turn and adds two contract-aware heuristics. Both are deliberately scoped: chg-1 prevents the destructive command itself, chg-2 fixes the salience gap of the iteration-6 middleware. ### C.3 Reading the change-manifest figures The trajectories above track individual edits through individual tasks. The change-manifest carries each edit along with its predicted fixes, predicted regressions, and constraint level into Phase 3 of the next iteration, where the attribution check decides whether to keep or roll it back. One manifest figure is attached to each of the four winning rounds, all in the same Files / What changed / Failure pattern fixed / Predicted fixes layout. Figure 7 shows iteration 2’s prompt edit and shell-tool edit written together in the seed round. Figure 8 shows iteration 5’s prompt-and-descriptor rule and shell-guard installation that introduce the publish-state mechanism. Figure 9 shows iteration 6’s extension of the publish-state guard to script entrypoints and the introduction of the cross-step ExecutionRiskHintsMiddleware. Figure 10 shows iteration 8’s keep-and-improve patches that close the override-token loophole on the guard and promote middleware reminders into a FRAMEWORK note visible at the next model turn. Together the four figures cover three of the four constraint levels the evolve agent uses, namely prompt, tool implementation, and middleware, all written in the same JSON shape and all subject to the same automatic rollback if their predicted fixes do not appear. ## Appendix D Per-round Self-attribution Breakdown This appendix expands the aggregate self-attribution result of §4.4.2 with a per-round breakdown across the four fix/regression by precision/recall panels. Figures˜11 and 12 show the per-round breakdown across the four fix/regression by precision/recall panels. Bars decompose each denominator, predicted for precision and actual for recall, into deep-blue TP versus pale FP or FN; the dashed line traces the metric on the right-hand $0$ to $100\%$ axis, and the solid line shows contemporaneous pass@1. Fix-precision and fix-recall both swing from near-zero to near-saturation across rounds, so the evolve model’s causal attribution for its own improvements is informative if noisy. Regression predictions instead stay near the floor, below $25\%$ on most rounds: across the 9 rounds the agent issued 43 unique regression predictions and only 5 landed, giving cumulative $P=11.6\%$, while 40 regressions the agent did not foresee actually occurred, giving cumulative $R=11.1\%$. ![Refer to caption](https://arxiv.org/html/2604.25850v3/x6.png) Figure 11: Per-round fix predictions. Left: precision. Right: recall. Bars decompose each denominator into TP versus FP or FN; lines overlay the metric and contemporaneous pass@1. ![Refer to caption](https://arxiv.org/html/2604.25850v3/x8.png) Figure 12: Per-round regression predictions. Left: precision. Right: recall. Same encoding as Fig. 11. [^1]: L. A. Agrawal, S. Tan, D. Soylu, N. Ziems, R. Khare, K. Opsahl-Ong, A. Singhvi, H. Shandilya, M. J. Ryan, M. Jiang, C. Potts, K. Sen, A. Dimakis, I. Stoica, D. Klein, M. Zaharia, and O. Khattab (2025-10) GEPA: reflective prompt evolution can outperform reinforcement learning. In The Fourteenth International Conference on Learning Representations, External Links: [Link](https://openreview.net/forum?id=RQm2KQTM5r) Cited by: §1, §2.2. [^2]: Anomaly (2025) Opencode: the open source coding agent.. External Links: [Link](https://github.com/anomalyco/opencode) Cited by: §4.2. [^3]: Anthropic (2025) Claude-code. External Links: [Link](https://github.com/anthropics/claude-code) Cited by: §2.1. [^4]: Y. Cai, S. Cai, Y. Shi, Z. Xu, L. Chen, Y. Qin, X. Tan, G. Li, Z. Li, H. Lin, Y. Mao, K. Li, and X. Sun (2025-10) Training-free group relative policy optimization. arXiv. External Links: 2510.08191, [Document](https://dx.doi.org/10.48550/arXiv.2510.08191), [Link](http://arxiv.org/abs/2510.08191) Cited by: §1, §1, §2.2, §4.2. [^5]: J. S. Chan, N. Chowdhury, O. Jaffe, J. Aung, D. Sherburn, E. Mays, G. Starace, K. Liu, L. Maksin, T. Patwardhan, A. Madry, and L. Weng (2024-10) MLE-bench: evaluating machine learning agents on machine learning engineering. In The Thirteenth International Conference on Learning Representations, External Links: [Link](https://openreview.net/forum?id=6s5uXNWGIh) Cited by: §2.1. [^6]: DeepSeek-AI (2026-04) DeepSeek-v4: towards highly efficient million-token context intelligence. External Links: [Link](https://huggingface.co/deepseek-ai/DeepSeek-V4-Pro/blob/main/DeepSeek_V4.pdf) Cited by: §1, §4.1. [^7]: X. Deng, J. Da, E. Pan, Y. Y. He, C. Ide, K. Garg, N. Lauffer, A. Park, C. Rane, K. Sampath, M. Krishnan, S. R. Kundurthy, S. M. Hendryx, Z. Wang, C. B. C. Zhang, N. Jacobson, B. Liu, and B. Kenstler (2025-10) SWE-bench pro: can ai agents solve long-horizon software engineering tasks?. External Links: [Link](https://openreview.net/forum?id=9R2iUHhVfr) Cited by: §1, §2.1. [^8]: Google (2026-03) Gemini-3-1-flash-lite-model-card. External Links: [Link](https://storage.googleapis.com/deepmind-media/Model-Cards/Gemini-3-1-Flash-Lite-Model-Card.pdf) Cited by: §4.1. [^9]: H. Guo, K. Lv, Q. Guo, T. Liang, Z. Xi, D. Song, Q. Zhang, Y. Sun, K. Chen, X. Qiu, and T. Gui (2025-07) CritiQ: mining data quality criteria from human preferences. In Proceedings of the 63rd Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers), W. Che, J. Nabende, E. Shutova, and M. T. Pilehvar (Eds.), Vienna, Austria, pp. 16240–16261. External Links: [Document](https://dx.doi.org/10.18653/v1/2025.acl-long.792), [Link](https://aclanthology.org/2025.acl-long.792/), ISBN 979-8-89176-251-0 Cited by: §2.2. [^10]: Harbor (2026) Terminus-2. External Links: [Link](https://www.harborframework.com/docs/agents/terminus-2) Cited by: §4.2. [^11]: S. Hu, C. Lu, and J. Clune (2024-10) Automated design of agentic systems. In The Thirteenth International Conference on Learning Representations, External Links: [Link](https://openreview.net/forum?id=t9U3LW7JVX) Cited by: §2.2. [^12]: N. Jain, K. Han, A. Gu, W. Li, F. Yan, T. Zhang, S. Wang, A. Solar-Lezama, K. Sen, and I. Stoica (2024-10) LiveCodeBench: holistic and contamination free evaluation of large language models for code. In The Thirteenth International Conference on Learning Representations, External Links: [Link](https://openreview.net/forum?id=chfJJYC3iL) Cited by: §2.1. [^13]: N. Jain, J. Singh, M. Shetty, T. Zhang, L. Zheng, K. Sen, and I. Stoica (2025-08) R2E-gym: procedural environment generation and hybrid verifiers for scaling open-weights swe agents. In Second Conference on Language Modeling, External Links: [Link](https://openreview.net/forum?id=7evvwwdo3z#discussion) Cited by: §2.1. [^14]: C. E. Jimenez, J. Yang, A. Wettig, S. Yao, K. Pei, O. Press, and K. R. Narasimhan (2023-10) SWE-bench: can language models resolve real-world github issues?. In The Twelfth International Conference on Learning Representations, External Links: [Link](https://openreview.net/forum?id=VTF8yNQM66) Cited by: §1, §1, §2.1, §4.1. [^15]: O. Khattab, A. Singhvi, P. Maheshwari, Z. Zhang, K. Santhanam, S. Vardhamanan, S. Haq, A. Sharma, T. T. Joshi, H. Moazam, H. Miller, M. Zaharia, and C. Potts (2023-10) DSPy: compiling declarative language model calls into self-improving pipelines. arXiv. External Links: 2310.03714, [Document](https://dx.doi.org/10.48550/arXiv.2310.03714), [Link](http://arxiv.org/abs/2310.03714) Cited by: §2.2. [^16]: Y. Lee, R. Nair, Q. Zhang, K. Lee, O. Khattab, and C. Finn (2026-03) Meta-harness: end-to-end optimization of model harnesses. arXiv. External Links: 2603.28052, [Document](https://dx.doi.org/10.48550/arXiv.2603.28052), [Link](http://arxiv.org/abs/2603.28052) Cited by: §1. [^17]: L. Lin (2026-02) Agent debugger: understanding agent trajectory with agentic workflows - dawning road. External Links: [Link](https://dawning-road.github.io/blog/agent-debugger) Cited by: §3.2. [^18]: R. Lopopolo (2026-02) Harness engineering: leveraging codex in an agent-first world. External Links: [Link](https://openai.com/zh-Hans-CN/index/harness-engineering/) Cited by: §1, §2.1. [^19]: Z. Ma, S. Yang, Y. Ji, X. Wang, Y. Wang, Y. Hu, T. Huang, and X. Chu (2026-04) SkillClaw: let skills evolve collectively with agentic evolver. arXiv. External Links: 2604.08377, [Document](https://dx.doi.org/10.48550/arXiv.2604.08377), [Link](http://arxiv.org/abs/2604.08377) Cited by: §1. [^20]: A. Madaan, N. Tandon, P. Gupta, S. Hallinan, L. Gao, S. Wiegreffe, U. Alon, N. Dziri, S. Prabhumoye, Y. Yang, S. Gupta, B. P. Majumder, K. Hermann, S. Welleck, A. Yazdanbakhsh, and P. Clark (2023-11) Self-refine: iterative refinement with self-feedback. In Thirty-Seventh Conference on Neural Information Processing Systems, External Links: [Link](https://openreview.net/forum?id=S37hOerQLB) Cited by: §1, §2.2. [^21]: M. A. Merrill, A. G. Shaw, N. Carlini, B. Li, H. Raj, I. Bercovich, L. Shi, J. Y. Shin, T. Walshe, E. K. Buchanan, J. Shen, G. Ye, H. Lin, J. Poulos, M. Wang, M. Nezhurina, J. Jitsev, D. Lu, O. M. Mastromichalakis, Z. Xu, Z. Chen, Y. Liu, R. Zhang, L. L. Chen, A. Kashyap, J. Uslu, J. Li, J. Wu, M. Yan, S. Bian, V. Sharma, K. Sun, S. Dillmann, A. Anand, A. Lanpouthakoun, B. Koopah, C. Hu, E. Guha, G. H. S. Dreiman, J. Zhu, K. Krauth, L. Zhong, N. Muennighoff, R. Amanfu, S. Tan, S. Pimpalgaonkar, T. Aggarwal, X. Lin, X. Lan, X. Zhao, Y. Liang, Y. Wang, Z. Wang, C. Zhou, D. Heineman, H. Liu, H. Trivedi, J. Yang, J. Lin, M. Shetty, M. Yang, N. Omi, N. Raoof, S. Li, T. Y. Zhuo, W. Lin, Y. Dai, Y. Wang, W. Chai, S. Zhou, D. Wahdany, Z. She, J. Hu, Z. Dong, Y. Zhu, S. Cui, A. Saiyed, A. Kolbeinsson, J. Hu, C. M. Rytting, R. Marten, Y. Wang, A. Dimakis, A. Konwinski, and L. Schmidt (2026-01) Terminal-bench: benchmarking agents on hard, realistic tasks in command line interfaces. arXiv. External Links: 2601.11868, [Document](https://dx.doi.org/10.48550/arXiv.2601.11868), [Link](http://arxiv.org/abs/2601.11868) Cited by: §1, §1, §2.1, §4.1. [^22]: S. Miserendino, M. Wang, T. Patwardhan, and J. Heidecke (2025-06) SWE-lancer: can frontier llms earn $1 million from real-world freelance software engineering?. In Forty-Second International Conference on Machine Learning, External Links: [Link](https://openreview.net/forum?id=xZXhFg43EI) Cited by: §2.1. [^23]: Nex-AGI (2025) NexAU (au for agent universe), a general-purpose agent framework for building intelligent agents with tool capabilities.. External Links: [Link](https://github.com/nex-agi/NexAU) Cited by: §3.1. [^24]: A. Novikov, N. Vũ, M. Eisenberger, E. Dupont, P. Huang, A. Z. Wagner, S. Shirobokov, B. Kozlovskii, F. J. R. Ruiz, A. Mehrabian, M. P. Kumar, A. See, S. Chaudhuri, G. Holland, A. Davies, S. Nowozin, P. Kohli, and M. Balog (2025-06) AlphaEvolve: a coding agent for scientific and algorithmic discovery. arXiv. External Links: 2506.13131, [Document](https://dx.doi.org/10.48550/arXiv.2506.13131), [Link](http://arxiv.org/abs/2506.13131) Cited by: §2.2. [^25]: OpenAI (2025) Codex cli. External Links: [Link](https://developers.openai.com/codex/cli) Cited by: §1, §4.2. [^26]: OpenAI (2026-03) Introducing gpt-5.4. External Links: [Link](https://openai.com/index/introducing-gpt-5-4/) Cited by: §4.1. [^27]: K. Opsahl-Ong, M. J. Ryan, J. Purtell, D. Broman, C. Potts, M. Zaharia, and O. Khattab (2024-11) Optimizing instructions and demonstrations for multi-stage language model programs. In Proceedings of the 2024 Conference on Empirical Methods in Natural Language Processing, Y. Al-Onaizan, M. Bansal, and Y. Chen (Eds.), Miami, Florida, USA, pp. 9340–9366. External Links: [Document](https://dx.doi.org/10.18653/v1/2024.emnlp-main.525), [Link](https://aclanthology.org/2024.emnlp-main.525/) Cited by: §2.2. [^28]: J. Pan, X. Wang, G. Neubig, N. Jaitly, H. Ji, A. Suhr, and Y. Zhang (2025-06) Training software engineering agents and verifiers with swe-gym. In Forty-Second International Conference on Machine Learning, External Links: [Link](https://openreview.net/forum?id=Cq1BNvHx74) Cited by: §2.1. [^29]: P. Rajasekaran, E. Dixon, C. Ryan, J. Hadfield, R. Ayub, H. Moran, C. Rueb, C. Jennings, M. Vorwerck, S. Ritchie, and M. Vo (2025-09) Effective context engineering for ai agents. External Links: [Link](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) Cited by: §3.2. [^30]: P. Rajasekaran (2026-03) Harness design for long-running application development. External Links: [Link](https://www.anthropic.com/engineering/harness-design-long-running-apps) Cited by: §1, §2.1. [^31]: N. Research (2026) Hermes agent — the agent that grows with you. External Links: [Link](https://hermes-agent.nousresearch.com/) Cited by: §1, §2.1. [^32]: N. Shinn, F. Cassano, A. Gopinath, K. R. Narasimhan, and S. Yao (2023-11) Reflexion: language agents with verbal reinforcement learning. In Thirty-Seventh Conference on Neural Information Processing Systems, External Links: [Link](https://openreview.net/forum?id=vAElhFcKW6) Cited by: §1, §2.2. [^33]: P. Steinberger (2026-02) OpenClaw — personal ai assistant. External Links: [Link](https://openclaw.ai/) Cited by: §1, §1, §2.1. [^34]: R. Sutton (2019-03) The bitter lesson. External Links: [Link](https://www.cs.utexas.edu/%CB%9Ceunsol/courses/data/bitter_lesson.pdf) Cited by: §1. [^35]: K. Team, T. Bai, Y. Bai, Y. Bao, S. H. Cai, Y. Cao, Y. Charles, H. S. Che, C. Chen, G. Chen, H. Chen, J. Chen, J. Chen, J. Chen, J. Chen, K. Chen, L. Chen, R. Chen, X. Chen, Y. Chen, Y. Chen, Y. Chen, Y. Chen, Y. Chen, Y. Chen, Y. Chen, Y. Chen, Z. Chen, Z. Chen, D. Cheng, M. Chu, J. Cui, J. Deng, M. Diao, H. Ding, M. Dong, M. Dong, Y. Dong, Y. Dong, A. Du, C. Du, D. Du, L. Du, Y. Du, Y. Fan, S. Fang, Q. Feng, Y. Feng, G. Fu, K. Fu, H. Gao, T. Gao, Y. Ge, S. Geng, C. Gong, X. Gong, Z. Gongque, Q. Gu, X. Gu, Y. Gu, L. Guan, Y. Guo, X. Hao, W. He, W. He, Y. He, C. Hong, H. Hu, J. Hu, Y. Hu, Z. Hu, K. Huang, R. Huang, W. Huang, Z. Huang, T. Jiang, Z. Jiang, X. Jin, Y. Jing, G. Lai, A. Li, C. Li, C. Li, F. Li, G. Li, G. Li, H. Li, H. Li, J. Li, J. Li, J. Li, L. Li, M. Li, W. Li, W. Li, X. Li, X. Li, Y. Li, Y. Li, Y. Li, Y. Li, Z. Li, Z. Li, W. Liao, J. Lin, X. Lin, Z. Lin, Z. Lin, C. Liu, C. Liu, H. Liu, L. Liu, S. Liu, S. Liu, S. Liu, T. Liu, T. Liu, W. Liu, X. Liu, Y. Liu, Y. Liu, Y. Liu, Y. Liu, Y. Liu, Z. Liu, Z. Liu, E. Lu, H. Lu, Z. Lu, J. Luo, T. Luo, Y. Luo, L. Ma, Y. Ma, S. Mao, Y. Mei, X. Men, F. Meng, Z. Meng, Y. Miao, M. Ni, K. Ouyang, S. Pan, B. Pang, Y. Qian, R. Qin, Z. Qin, J. Qiu, B. Qu, Z. Shang, Y. Shao, T. Shen, Z. Shen, J. Shi, L. Shi, S. Shi, F. Song, P. Song, T. Song, X. Song, H. Su, J. Su, Z. Su, L. Sui, J. Sun, J. Sun, T. Sun, F. Sung, Y. Tai, C. Tang, H. Tang, X. Tang, Z. Tang, J. Tao, S. Teng, C. Tian, P. Tian, A. Wang, B. Wang, C. Wang, C. Wang, C. Wang, D. Wang, D. Wang, D. Wang, F. Wang, H. Wang, H. Wang, H. Wang, H. Wang, H. Wang, J. Wang, J. Wang, J. Wang, K. Wang, L. Wang, Q. Wang, S. Wang, S. Wang, S. Wang, W. Wang, X. Wang, X. Wang, Y. Wang, Y. Wang, Y. Wang, Y. Wang, Y. Wang, Y. Wang, Z. Wang, Z. Wang, Z. Wang, Z. Wang, Z. Wang, Z. Wang, C. Wei, M. Wei, C. Wen, Z. Wen, C. Wu, H. Wu, J. Wu, R. Wu, W. Wu, Y. Wu, Y. Wu, Y. Wu, Z. Wu, C. Xiao, J. Xie, X. Xie, Y. Xie, Y. Xin, B. Xing, B. Xu, J. Xu, J. Xu, J. Xu, L. H. Xu, L. Xu, S. Xu, W. Xu, X. Xu, X. Xu, Y. Xu, Y. Xu, Y. Xu, Z. Xu, Z. Xu, J. Yan, Y. Yan, G. Yang, H. Yang, J. Yang, K. Yang, N. Yang, R. Yang, X. Yang, X. Yang, Y. Yang, Y. Yang, Y. Yang, Z. Yang, Z. Yang, Z. Yang, H. Yao, D. Ye, W. Ye, Z. Ye, B. Yin, C. Yu, L. Yu, T. Yu, T. Yu, E. Yuan, M. Yuan, X. Yuan, Y. Yue, W. Zeng, D. Zha, H. Zhan, D. Zhang, H. Zhang, J. Zhang, P. Zhang, Q. Zhang, R. Zhang, X. Zhang, Y. Zhang, Y. Zhang, Y. Zhang, Y. Zhang, Y. Zhang, Y. Zhang, Y. Zhang, Y. Zhang, Y. Zhang, Y. Zhang, Z. Zhang, C. Zhao, F. Zhao, J. Zhao, S. Zhao, X. Zhao, Y. Zhao, Z. Zhao, H. Zheng, R. Zheng, S. Zheng, T. Zheng, J. Zhong, L. Zhong, W. Zhong, M. Zhou, R. Zhou, X. Zhou, Z. Zhou, J. Zhu, L. Zhu, X. Zhu, Y. Zhu, Z. Zhu, J. Zhuang, W. Zhuang, Y. Zou, and X. Zu (2026-02) Kimi k2.5: visual agentic intelligence. arXiv. External Links: 2602.02276, [Document](https://dx.doi.org/10.48550/arXiv.2602.02276), [Link](http://arxiv.org/abs/2602.02276) Cited by: §1. [^36]: K. Team (2026-04) Kimi k2.6 tech blog: advancing open-source coding. External Links: [Link](https://www.kimi.com/blog/kimi-k2-6) Cited by: §1. [^37]: N. Team, Y. Cai, L. Chen, Q. Chen, Y. Ding, L. Fan, W. Fu, Y. Gao, H. Guo, P. Guo, Z. Han, Z. He, H. Hu, K. Hu, S. Hua, T. Huai, B. Huang, L. Ji, Z. Jiang, Z. Lei, B. Li, J. Lin, L. Lin, J. Liu, S. Liu, Z. Liu, Y. Ni, P. Qian, Y. Shen, Q. Shi, W. Shu, P. Sun, Y. Suo, T. Tang, B. Tian, G. Wang, J. Wang, P. Wang, Z. Xi, H. Yan, J. Yang, Z. Yang, T. Yao, G. Ye, Q. Yu, S. Zhang, X. Zhang, Y. Zhang, J. Zhao, M. Zheng, R. Zheng, E. Zhou, J. Zhou, M. Zhou, Y. Zhou, T. Gui, Y. Zheng, X. Chen, J. Zhou, S. Feng, Q. Chen, L. He, Q. Zhang, X. Huang, and X. Qiu (2025-12) Nex-n1: agentic models trained via a unified ecosystem for large-scale environment construction. arXiv. External Links: 2512.04987, [Document](https://dx.doi.org/10.48550/arXiv.2512.04987), [Link](http://arxiv.org/abs/2512.04987) Cited by: §3.1. [^38]: Q. Team (2026-04) Qwen3.6-plus: towards real world agents. External Links: [Link](https://qwenlm.github.io/blog/qwen3.6/) Cited by: §1, §4.1. [^39]: X. M. Team (2026-04) MiMo-v2.5-pro. External Links: [Link](https://huggingface.co/XiaomiMiMo/MiMo-V2.5-Pro) Cited by: §1. [^40]: V. Trivedy (2026-02) Improving deep agents with harness engineering. External Links: [Link](https://www.langchain.com/blog/improving-deep-agents-with-harness-engineering) Cited by: §1, §2.1. [^41]: G. Wang, Y. Xie, Y. Jiang, A. Mandlekar, C. Xiao, Y. Zhu, L. Fan, and A. Anandkumar (2023-10) Voyager: an open-ended embodied agent with large language models. arXiv. External Links: 2305.16291, [Document](https://dx.doi.org/10.48550/arXiv.2305.16291), [Link](http://arxiv.org/abs/2305.16291) Cited by: §2.2. [^42]: X. Wang, B. Li, Y. Song, F. F. Xu, X. Tang, M. Zhuge, J. Pan, Y. Song, B. Li, J. Singh, H. H. Tran, F. Li, R. Ma, M. Zheng, B. Qian, Y. Shao, N. Muennighoff, Y. Zhang, B. Hui, J. Lin, R. Brennan, H. Peng, H. Ji, and G. Neubig (2025-04) OpenHands: an open platform for ai software developers as generalist agents. arXiv. External Links: 2407.16741, [Document](https://dx.doi.org/10.48550/arXiv.2407.16741), [Link](http://arxiv.org/abs/2407.16741) Cited by: §1, §1, §2.1. [^43]: P. Xia, J. Chen, H. Wang, J. Liu, K. Zeng, Y. Wang, S. Han, Y. Zhou, X. Zhao, H. Chen, Z. Zheng, C. Xie, and H. Yao (2026-02) SkillRL: evolving agents via recursive skill-augmented reinforcement learning. arXiv. External Links: 2602.08234, [Document](https://dx.doi.org/10.48550/arXiv.2602.08234), [Link](http://arxiv.org/abs/2602.08234) Cited by: §1. [^44]: A. Yang, A. Li, B. Yang, B. Zhang, B. Hui, B. Zheng, B. Yu, C. Gao, C. Huang, C. Lv, C. Zheng, D. Liu, F. Zhou, F. Huang, F. Hu, H. Ge, H. Wei, H. Lin, J. Tang, J. Yang, J. Tu, J. Zhang, J. Yang, J. Yang, J. Zhou, J. Zhou, J. Lin, K. Dang, K. Bao, K. Yang, L. Yu, L. Deng, M. Li, M. Xue, M. Li, P. Zhang, P. Wang, Q. Zhu, R. Men, R. Gao, S. Liu, S. Luo, T. Li, T. Tang, W. Yin, X. Ren, X. Wang, X. Zhang, X. Ren, Y. Fan, Y. Su, Y. Zhang, Y. Zhang, Y. Wan, Y. Liu, Z. Wang, Z. Cui, Z. Zhang, Z. Zhou, and Z. Qiu (2025-05) Qwen3 technical report. arXiv. External Links: 2505.09388, [Document](https://dx.doi.org/10.48550/arXiv.2505.09388), [Link](http://arxiv.org/abs/2505.09388) Cited by: §1, §4.1. [^45]: J. Yang, C. E. Jimenez, A. Wettig, K. Lieret, S. Yao, K. R. Narasimhan, and O. Press (2024-11) SWE-agent: agent-computer interfaces enable automated software engineering. In The Thirty-Eighth Annual Conference on Neural Information Processing Systems, External Links: [Link](https://openreview.net/forum?id=mXpq6ut8J3&referrer=%5Bthe%20profile%20of%20Shunyu%20Yao%5D\(%2Fprofile%3Fid%3D%CB%9CShunyu_Yao1\)) Cited by: §1, §2.1. [^46]: J. Yang, C. E. Jimenez, A. L. Zhang, K. Lieret, J. Yang, X. Wu, O. Press, N. Muennighoff, G. Synnaeve, K. R. Narasimhan, D. Yang, S. Wang, and O. Press (2024-10) SWE-bench multimodal: do ai systems generalize to visual software domains?. In The Thirteenth International Conference on Learning Representations, External Links: [Link](https://openreview.net/forum?id=riTiq3i21b) Cited by: §1, §2.1. [^47]: Y. Zeng, S. Li, D. Dong, R. Xu, Z. Chen, L. Zheng, Y. Li, Z. Zhou, H. Zhao, L. Tian, H. Xiao, T. Zhu, L. Hao, and J. Wu (2026-02) SWE-hub: a unified production system for scalable, executable software engineering tasks. arXiv. External Links: 2603.00575, [Document](https://dx.doi.org/10.48550/arXiv.2603.00575), [Link](http://arxiv.org/abs/2603.00575) Cited by: §2.1. [^48]: J. Zhang, J. Xiang, Z. Yu, F. Teng, X. Chen, J. Chen, M. Zhuge, X. Cheng, S. Hong, J. Wang, B. Zheng, B. Liu, Y. Luo, and C. Wu (2024-10) AFlow: automating agentic workflow generation. In The Thirteenth International Conference on Learning Representations, External Links: [Link](https://openreview.net/forum?id=z5uVAKwmjf) Cited by: §2.2. [^49]: Q. Zhang, C. Hu, S. Upasani, B. Ma, F. Hong, V. Kamanuru, J. Rainton, C. Wu, M. Ji, H. Li, U. Thakker, J. Zou, and K. Olukotun (2025-10) Agentic context engineering: evolving contexts for self-improving language models. In The Fourteenth International Conference on Learning Representations, External Links: [Link](https://openreview.net/forum?id=eC4ygDs02R) Cited by: §1, §1, §2.2, §4.2. [^50]: A. Zhao, D. Huang, Q. Xu, M. Lin, Y. Liu, and G. Huang (2024-12) ExpeL: llm agents are experiential learners. arXiv. External Links: 2308.10144, [Document](https://dx.doi.org/10.48550/arXiv.2308.10144), [Link](http://arxiv.org/abs/2308.10144) Cited by: §1. [^51]: W. Zhou, Y. Ou, S. Ding, L. Li, J. Wu, T. Wang, J. Chen, S. Wang, X. Xu, N. Zhang, H. Chen, and Y. E. Jiang (2024-06) Symbolic learning enables self-evolving agents. arXiv. External Links: 2406.18532, [Document](https://dx.doi.org/10.48550/arXiv.2406.18532), [Link](http://arxiv.org/abs/2406.18532) Cited by: §2.2. [^52]: T. Y. Zhuo, V. M. Chien, J. Chim, H. Hu, W. Yu, R. Widyasari, I. N. B. Yusuf, H. Zhan, J. He, I. Paul, S. Brunner, C. Gong, J. Hoang, A. R. Zebaze, X. Hong, W. Li, J. Kaddour, M. Xu, Z. Zhang, P. Yadav, N. Jain, A. Gu, Z. Cheng, J. Liu, Q. Liu, Z. Wang, B. Hui, N. Muennighoff, D. Lo, D. Fried, X. Du, H. de Vries, and L. V. Werra (2024-10) BigCodeBench: benchmarking code generation with diverse function calls and complex instructions. In The Thirteenth International Conference on Learning Representations, External Links: [Link](https://openreview.net/forum?id=YrycTjllL0) Cited by: §2.1. [^53]: G. Zunic (2026-04) The bitter lesson of agent harnesses. External Links: [Link](https://browser-use.com/posts/bitter-lesson-agent-harnesses) Cited by: §1. ]]> Sat, 02 May 2026 14:44:50 GMT https://reader-feed.pages.dev/posts/fa65f42575-Agentic%20Harness%20Engineering%20Observability-Driven%20Automatic%20Evolution%20of%20Coding-Agent%20Harnesses.md obsidian:8dc7f5df52:Clippings/Google Antigravity Documentation 6.md Google Antigravity Documentation Learn how to use Google Antigravity Thu, 30 Apr 2026 03:29:19 GMT https://reader-feed.pages.dev/posts/8dc7f5df52-Google%20Antigravity%20Documentation%206.md obsidian:1acef559cc:Clippings/Google Antigravity Documentation 5.md Google Antigravity Documentation Learn how to use Google Antigravity Thu, 30 Apr 2026 03:29:13 GMT https://reader-feed.pages.dev/posts/1acef559cc-Google%20Antigravity%20Documentation%205.md obsidian:580d6c44de:Clippings/Google Antigravity Documentation 4.md Google Antigravity Documentation Learn how to use Google Antigravity Thu, 30 Apr 2026 03:29:07 GMT https://reader-feed.pages.dev/posts/580d6c44de-Google%20Antigravity%20Documentation%204.md obsidian:056cbb4e0e:Clippings/Google Antigravity Documentation 3.md Google Antigravity Documentation Learn how to use Google Antigravity Thu, 30 Apr 2026 03:29:00 GMT https://reader-feed.pages.dev/posts/056cbb4e0e-Google%20Antigravity%20Documentation%203.md obsidian:e9b7b555b5:Clippings/Google Antigravity Documentation 2.md Google Antigravity Documentation Learn how to use Google Antigravity Thu, 30 Apr 2026 03:28:52 GMT https://reader-feed.pages.dev/posts/e9b7b555b5-Google%20Antigravity%20Documentation%202.md obsidian:f95be59482:Clippings/Google Antigravity Documentation 1.md Google Antigravity Documentation Learn how to use Google Antigravity Thu, 30 Apr 2026 03:28:40 GMT https://reader-feed.pages.dev/posts/f95be59482-Google%20Antigravity%20Documentation%201.md obsidian:8b74563b99:Clippings/Google Antigravity Documentation.md Google Antigravity Documentation Learn how to use Google Antigravity Thu, 30 Apr 2026 03:28:29 GMT https://reader-feed.pages.dev/posts/8b74563b99-Google%20Antigravity%20Documentation.md obsidian:12aa5632a7:inbox/Effective harnesses for long-running agents.md Effective harnesses for long-running agents Anthropic is an AI safety and research company that's working to build reliable, interpretable, and steerable AI systems. 1 The key insight here was finding a way for agents to quickly understand the state of work when starting with a fresh context window, which is accomplished with the claude-progress.txt file alongside the git history. Inspiration for these practices came from knowing what effective software engineers do every day. ## Environment management In the updated [Claude 4 prompting guide](https://docs.claude.com/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices#multi-context-window-workflows), we shared some best practices for multi-context window workflows, including a harness structure that uses “a different prompt for the very first context window.” This “different prompt” requests that the initializer agent set up the environment with all the necessary context that future coding agents will need to work effectively. Here, we provide a deeper dive on some of the key components of such an environment. ### Feature list To address the problem of the agent one-shotting an app or prematurely considering the project complete, we prompted the initializer agent to write a comprehensive file of feature requirements expanding on the user’s initial prompt. In the [claude.ai](http://claude.ai/redirect/website.v1.a915abb0-bab5-4256-a523-6146387afe63) clone example, this meant over 200 features, such as “a user can open a new chat, type in a query, press enter, and see an AI response.” These features were all initially marked as “failing” so that later coding agents would have a clear outline of what full functionality looked like. ``` { "category": "functional", "description": "New chat button creates a fresh conversation", "steps": [ "Navigate to main interface", "Click the 'New Chat' button", "Verify a new conversation is created", "Check that chat area shows welcome state", "Verify conversation appears in sidebar" ], "passes": false } ``` We prompt coding agents to edit this file only by changing the status of a passes field, and we use strongly-worded instructions like “It is unacceptable to remove or edit tests because this could lead to missing or buggy functionality.” After some experimentation, we landed on using JSON for this, as the model is less likely to inappropriately change or overwrite JSON files compared to Markdown files. ### Incremental progress Given this initial environment scaffolding, the next iteration of the coding agent was then asked to work on only one feature at a time. This incremental approach turned out to be critical to addressing the agent’s tendency to do too much at once. Once working incrementally, it’s still essential that the model leaves the environment in a clean state after making a code change. In our experiments, we found that the best way to elicit this behavior was to ask the model to commit its progress to git with descriptive commit messages and to write summaries of its progress in a progress file. This allowed the model to use git to revert bad code changes and recover working states of the code base. These approaches also increased efficiency, as they eliminated the need for an agent to have to guess at what had happened and spend its time trying to get the basic app working again. ### Testing One final major failure mode that we observed was Claude’s tendency to mark a feature as complete without proper testing. Absent explicit prompting, Claude tended to make code changes, and even do testing with unit tests or `curl` commands against a development server, but would fail recognize that the feature didn’t work end-to-end. In the case of building a web app, Claude mostly did well at verifying features end-to-end once explicitly prompted to use browser automation tools and do all testing as a human user would. ![ Screenshots taken by Claude through the Puppeteer MCP server as it tested the claude.ai clone. ](https://www.anthropic.com/_next/image?url=https%3A%2F%2Fwww-cdn.anthropic.com%2Fimages%2F4zrzovbb%2Fwebsite%2Ff94c2257964fb2d623f1e81f874977ebfc0986bc-1920x1080.gif&w=3840&q=75) Screenshots taken by Claude through the Puppeteer MCP server as it tested the claude.ai clone. Providing Claude with these kinds of testing tools dramatically improved performance, as the agent was able to identify and fix bugs that weren’t obvious from the code alone. Some issues remain, like limitations to Claude’s vision and to browser automation tools making it difficult to identify every kind of bug. For example, Claude can’t see browser-native alert modals through the Puppeteer MCP, and features relying on these modals tended to be buggier as a result. ## Getting up to speed With all of the above in place, every coding agent is prompted to run through a series of steps to get its bearings, some quite basic but still helpful: 1. *Run `pwd` to see the directory you’re working in. You’ll only be able to edit files in this directory.* 2. *Read the git logs and progress files to get up to speed on what was recently worked on.* 3. *Read the features list file and choose the highest-priority feature that’s not yet done to work on.* This approach saves Claude some tokens in every session since it doesn’t have to figure out how to test the code. It also helps to ask the initializer agent to write an init.sh script that can run the development server, and then run through a basic end-to-end test before implementing a new feature. In the case of the claude.ai clone, this meant that the agent always started the local development server and used the Puppeteer MCP to start a new chat, send a message, and receive a response. This ensured that Claude could quickly identify if the app had been left in a broken state, and immediately fix any existing bugs. If the agent had instead started implementing a new feature, it would likely make the problem worse. Given all this, a typical session starts off with the following assistant messages: ``` [Assistant] I'll start by getting my bearings and understanding the current state of the project. [Tool Use] [Tool Use] [Tool Use] [Assistant] Let me check the git log to see recent work. [Tool Use] [Assistant] Now let me check if there's an init.sh script to restart the servers. [Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working. [Assistant] Based on my verification testing, I can see that the fundamental functionality is working well. The core chat features, theme switching, conversation loading, and error handling are all functioning correctly. Now let me review the tests.json file more comprehensively to understand what needs to be implemented next. ``` Agent failure modes and solutions | **Problem** | **Initializer Agent Behavior** | **Coding Agent Behavior** | | --- | --- | --- | | Claude declares victory on the entire project too early. | Set up a feature list file: based on the input spec, set up a structured JSON file with a list of end-to-end feature descriptions. | Read the feature list file at the beginning of a session. Choose a single feature to start working on. | | Claude leaves the environment in a state with bugs or undocumented progress. | An initial git repo and progress notes file is written. | Start the session by reading the progress notes file and git commit logs, and run a basic test on the development server to catch any undocumented bugs. End the session by writing a git commit and progress update. | | Claude marks features as done prematurely. | Set up a feature list file. | Self-verify all features. Only mark features as “passing” after careful testing. | | Claude has to spend time figuring out how to run the app. | Write an `init.sh` script that can run the development server. | Start the session by reading `init.sh`. | Summarizing four common failure modes and solutions in long-running AI agents. ## Future work This research demonstrates one possible set of solutions in a long-running agent harness to enable the model to make incremental progress across many context windows. However, there remain open questions. Most notably, it’s still unclear whether a single, general-purpose coding agent performs best across contexts, or if better performance can be achieved through a multi-agent architecture. It seems reasonable that specialized agents like a testing agent, a quality assurance agent, or a code cleanup agent, could do an even better job at sub-tasks across the software development lifecycle. Additionally, this demo is optimized for full-stack web app development. A future direction is to generalize these findings to other fields. It’s likely that some or all of these lessons can be applied to the types of long-running agentic tasks required in, for example, scientific research or financial modeling. ### Acknowledgements Written by Justin Young. Special thanks to David Hershey, Prithvi Rajasakeran, Jeremy Hadfield, Naia Bouscal, Michael Tingley, Jesse Mu, Jake Eaton, Marius Buleandara, Maggie Vo, Pedram Navid, Nadine Yasser, and Alex Notov for their contributions. This work reflects the collective efforts of several teams across Anthropic who made it possible for Claude to safely do long-horizon autonomous software engineering, especially the code RL & Claude Code teams. Interested candidates who would like to contribute are welcome to apply at [anthropic.com/careers](http://anthropic.com/careers). 1\. We refer to these as separate agents in this context only because they have different initial user prompts. The system prompt, set of tools, and overall agent harness was otherwise identical. ]]> Thu, 30 Apr 2026 03:28:13 GMT https://reader-feed.pages.dev/posts/12aa5632a7-Effective%20harnesses%20for%20long-running%20agents.md obsidian:88bb99a4a7:inbox/Claude Code 源码蒸馏 - Harness Engineering 实践记录.md Claude Code 源码蒸馏 - Harness Engineering 实践记录 READ⏰: 25min 原始博客链接把 Claude Code 源码蒸馏成 Agent Skill突然发现，我“蒸馏” Claude Code 源码得到 Agent Harness Patterns Skill 的过程是一个不错的 Harness Engineering 的阅读材料～ （甚至可能比… From OpenAI [Harness engineering](https://link.zhihu.com/?target=https%3A//openai.com/index/harness-engineering/): *Enforcing architecture and taste* — 贯彻架构与品味，智能体在具有严格边界和可预测结构的环境中效率最高。 这可能是整个过程中最有意思的部分。我把之前写的几篇关于 Context Engineering 的博客作为 instruction / taste 喂给了 Claude Code，让它在提炼模式时参考我自己的分析框架。 因此，Agent 不是从零开始提取 **Agent 最佳实践** 的，它带着我对 select / write / compress / isolate Context Engineering 四轴框架的理解，带着我对 “Do the simple thing that works” 的偏好，以及我对抽象层级的判断标准。蒸馏出来的东西不是 Claude Code 源码的”客观映射”（最开始生成的都是这种），而是经过我的偏好基向量投影后的结果。 回到 PCA 的类比：博客就是那组基向量。它们定义了” **什么方向是重要的** “，然后 Agent 沿着这些方向做投影。没有这些基向量，Agent 可能会提取出完全不同的主成分，也许更偏向实现细节，也许更偏向 API 设计，但不一定是我想要的 harness 设计原则。（最初提取的东西简直没眼看） ![](https://pic3.zhimg.com/v2-9c625e0482be19d96a9000bcf074c874_1440w.jpg) > 这其实我对于 Agent 完成任务的感受，同样这点也在 OpenAI 中的博客被反映。如果你给 Agent 一个近乎无限的 Action Space，Agent 会直接失败。你需要先 Laying the foundation by hand 亲手奠定基础（源自另一篇有意思的博客： [OpenAI - How we used Codex to build Sora for Android in 28 days](https://link.zhihu.com/?target=https%3A//openai.com/index/shipping-sora-for-android-with-codex/) ）这是为了帮它归约 Action space，在你亲手确定方向后，agent 会越做越“好”（至少符合你的需求） ### 2.2 架构决策：几个关键时刻 虽然具体的 review 和 edit 都由 Agent 完成，但有几个节点是我主动介入的： **定位选择。** Codex 的第一轮 review 指出 skill 在回答错误的问题： “Claude Code 有哪些子系统？”而不是”构建者正在解决什么问题？”。这个重新定位的决策是 Codex 建议的，但选择接受它并让 Claude Code 按此执行，是我做的判断。（让它从解释代码变成抽取最佳实践） **抽象边界。** “去掉 Claude Code 这个名字，这条原则是否仍然有价值？”，这个判断标准是在多轮 review 中逐渐确定的。最初 Codex 和 Claude Code 对”什么算可移植原则”的理解并不一致，是我在 handoff 中明确了这条规则。 **用户视角的补位。** 5 轮专注于内容准确性的 review 之后，我意识到还缺少 **用户视角的审查** ，由于我写博客的经验，我最后总会从读者/使用者的角度去思考，我 hardcode 了这个 rule 要求它们均要引入这个思考角度（理论上应该被我沉淀为 skill 哈哈哈） ## 3\. 过程概览 ![](https://pic2.zhimg.com/v2-e93238fde03f9c9a08778fa98bc447c7_1440w.jpg) ### Phase 0：搭脚手架 在任何 Agent 动手之前，我先和 Codex 对齐了项目范围和命名，然后让它生成了 §1 中的全套 harness 文件。我给的 prompt 大意是： > “我们需要一个完整的 guidance（用于 clean agent 领取任务和快速了解 contexts）和对应的 progress tracking（方便 clean agent 了解已经做了什么）的 Harness。能否帮我生成这个 necessary harness set？” 比起 coding 任务，这类文档任务的 harness 设计可以更轻量。 ### Phase 1-2：探索与并行起草 4 个并行 Explore Agent 各负责不同的源码区域，扫描约 1,900 个文件，产出一份上下文地图。然后 7 个并行子 Agent 各领取一个 harness 层，写一篇对应的深度分析（最终产物中的 `references/*.md` ）。 ### Phase 3-4：核验 → 纠错 → 转向 Codex 第一轮 review 发现了 6 个事实错误（记忆系统未覆盖、并发分类搞错字段、权限来源数量写错等）。Claude Code 在新 session 中修正。随后 Codex 指出方向有问题 — 应该提取设计原则，而不是解释代码。 ### Phase 5：模板标准化 — 8 个 Agent 并行重写 确定”原则优先”后，8 个子 Agent 同时按统一模板重写所有文档（基本源自我的人工反馈。。）： ``` 问题（通用）→ 黄金法则（可移植）→ 适用场景 → 权衡 → 实现模式（无代码）→ 踩坑指南 → Claude Code 实证 ``` 最后一个 section 用自然语言描述 Claude Code 的实现决策，不出现源码路径、函数名或代码片段。 ### Phase 6：Review 收敛 （P1 = 必须修才能发布的错误，P3 = 措辞级别的优化。） | Review 轮次 | 发现 | 关键问题 | | --- | --- | --- | | v0.4 | 1P1 + 6P2 + 1P3 | 记忆模型仍然描述错误 | | v0.5 | 3P3（通过） | 仅措辞级别的调整 | | UX 审计 | 1P1 + 2P2 + 2P3 | skill 运行时的技能列表有 250 字符硬限，精心调的触发词全被截掉了 | 严重度在下降，说明收敛在发生。但 UX 审计又引入了一个新的 P1 — 内容层面已经收敛了，展示层面还有关键问题没人发现。 ### Phase 7：最终优化 缩短技能描述（248 → 116 字符），让触发词重新出现在列表中。为每个章节添加 “从这里开始” 的操作指引，声明目标读者。 ## 4\. Reflection 前面的章节已经覆盖了大部分具体的经验，这里只补充几点更一般性的思考。 ### 4.1 关于”客观”提取 §2.1 讲了 PCA 类比，这里简单补充一点：一个 **客观** 的模式提取可能反而是最没用的，因为它没有视角，也就没有优先级（无法归约 agent action space）。好的蒸馏需要一个明确的立场，然后诚实地标注这个立场是什么（怎么感觉和 《Principle》里面的概念比较接近，推荐阅读 [瑞·达利欧](https://zhida.zhihu.com/search?content_id=272448547&content_type=Article&match_order=1&q=%E7%91%9E%C2%B7%E8%BE%BE%E5%88%A9%E6%AC%A7&zhida_source=entity) 的这本书，我最近也在基于这本书构建个人 Principle Skill 笑死）。 ### 4.2 关于 Roadmap 后续对 Codex CLI 和 Gemini CLI 的分析会用同一组基向量。如果一个模式在三套独立实现中都沿着同一个方向出现，它大概率反映的是问题域本身的结构，而不是某个团队的设计偏好（也不只是我的偏好）。这或许是最值得继续做的事情。 ## References - [Agentic Harness Patterns Skill](https://link.zhihu.com/?target=https%3A//github.com/keli-wen/agentic-harness-patterns-skill) — Github Repo 蒸馏的产物 - [Context Engineering，一篇就够了](https://link.zhihu.com/?target=https%3A//keli-wen.github.io/One-Poem-Suffices/one-poem-suffices/context-engineering/) — 基向量之一 - [Just-in-Time Context，一篇就够了](https://link.zhihu.com/?target=https%3A//keli-wen.github.io/One-Poem-Suffices/one-poem-suffices/just-in-time-context/) — 基向量之二 - [Thinking in Context: Codex 中的上下文工程](https://link.zhihu.com/?target=https%3A//keli-wen.github.io/One-Poem-Suffices/thinking-in-context/context-engineering-from-codex/) — 基向量之三 - [Anthropic: Effective harnesses for long-running agents](https://link.zhihu.com/?target=https%3A//www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) - [OpenAI: Harness engineering](https://link.zhihu.com/?target=https%3A//openai.com/index/harness-engineering/) - [OpenAI: How we used Codex to build Sora for Android](https://link.zhihu.com/?target=https%3A//openai.com/index/shipping-sora-for-android-with-codex/) 编辑于 2026-04-02 23:15・上海[claude-code](https://www.zhihu.com/topic/1946631524649800689)[Harness-Engineeeing](https://www.zhihu.com/topic/2022052911786508336)[Skill](https://www.zhihu.com/topic/23777133) ]]> Fri, 24 Apr 2026 02:39:02 GMT https://reader-feed.pages.dev/posts/88bb99a4a7-Claude%20Code%20%E6%BA%90%E7%A0%81%E8%92%B8%E9%A6%8F%20-%20Harness%20Engineering%20%E5%AE%9E%E8%B7%B5%E8%AE%B0%E5%BD%95.md obsidian:08be90092a:inbox/Multi-Agents What's Actually Working.md Multi-Agents: What's Actually Working 10 months ago, I wrote Don't Build Multi-Agents, arguing that most people shouldn't try to build multi-agent systems [1]. Parallel agents ma... Takeaways: clean context leads to a notable improvement in capabilities when using a generator-verifier loop. But clear communication and synthesis with the overall context is important for a cohesive experience. **2) Large, expensive models are back - introducing “Smart Friend”** If you look at the most popular models over the last few months, you see a distinct shift from mid-sized models like Anthropic’s Sonnet-class models to large models like Anthropic’s Opus-class models for the sake of performance. And with Mythos coming, we can basically say “scaling is back” The quiet implication of this is that frontier intelligence will soon be too expensive (and perhaps slow) for most day-to-day tasks. At the same time, you face a dilemma with smaller models that a task might prove more difficult than originally expected. How can we get the best of both worlds? In Windsurf, we tried an experiment with this goal when we [launched SWE-1.5](https://cognition.ai/blog/swe-1-5) in October, a 950 tok/sec sub-frontier model. We found that when paired with Sonnet 4.5 for “planning”, we were able to make up for a small bit of the performance gap while keeping the low cost and fast speeds. ![Image](https://pbs.twimg.com/media/HGdP0YlbcAAQZdA?format=png&name=large) The actual architecture we used to achieve this was by offering the smarter/expansive model as a “smart friend” tool that the primary/smaller model could make a call out to. Basically, let the primary/smaller model decide when a situation was tricky enough to be worth consulting the smarter/expensive model. But we soon found that engineering the context transfer and communication was tricky: **1\. The primary model needs to know how to talk to smart friend.** The core trickiness of this setup comes from the problem of “how does a dumber model know it’s at its limits?” Unlike the more popular inverted setup with a smart primary model delegating tasks to smaller subagents, the model deciding when to delegate isn’t the smarter one. There’s a few potential solutions here. For one, you might encourage the primary agent to always make at least one call to the smart agent to evaluate whether it thinks there is some trickiness that was missed. You might also prompt-tune or train the primary model to be more calibrated on this decision. Depending on the intelligence of the primary model, certain kinds of domain-specific prescriptive guidance may be necessary, such as always invoking the smart friend for merge conflicts. The other tricky question with this communication method is what context should the primary model share with the smart friend? Moreover, what should the primary model ask the smart friend? If the primary model only shares a subset of its total context, then the smart model might not make a fully-informed decision. We found that for today’s models, a reasonable 80/20 solution is to just share a fork of the full context of the primary model with the smart model. Similarly, we found that encouraging the primary model to ask broad questions (”what should I do?”) and letting the smart model decide what is interesting to discuss is better. **2\. The smart friend needs to know how to talk back to the primary model** No matter how well you tune (1) you will likely find there are still gaps in quality due to context loss. Tuning the communication in the other direction can make up for these gaps. For instance, suppose the primary model never looked at important\_file.py and asked the smart model about something that requires knowledge of the contents of this file. In this case, the right answer from the smart model is not to make up some theories (which is often the default behavior), but to specifically instruct the primary model to investigate this file and ask again later. Similarly, it’s often also fruitful to ask the smart friend to look beyond the question the primary model is asking, and suggest any important guidance based on the agent trajectory, even if the primary model didn’t ask for it. We’ve found this “over-scoped” smart friend to generally lead to more interesting interactions. ![Image](https://pbs.twimg.com/media/HGdP7yPbsAA53Oi?format=png&name=large) **What Actually Happened with Smart Friend** We should be upfront: SWE 1.5 was not good enough at being the primary model for this setup to really work. The gap between it and Sonnet 4.5 was too wide in exactly the places that mattered for this setup: knowing when to escalate, knowing what to ask. The cost and speed wins were real, but the quality ceiling was set by the primary, and the primary wasn't strong enough. SWE 1.6 (a [recent followup](https://cognition.ai/blog/swe-1-6) achieving Opus-4.5 level performance on SWE-bench) is meaningfully better and closes enough of that gap that the pattern starts to pay off, but it's still not where we want it. We're reasonably confident this is a training problem, and future SWE models will be trained with this back-and-forth in mind \[2\]. Where the pattern did work, and worked well, was across frontier models. We’ve run Claude and GPT together in this setup in production for a meaningful stretch, and it produced real gains in the trickiest scenarios. The interesting finding is that the prompt-tuning problems are different from the small-model-to-large-model case. Cross-frontier communication is less about a weaker model knowing when to ask a stronger one, and more about routing to whichever model is best at the specific sub-task. Some models debug better, some handle visual reasoning better, some write tests better. The delegation logic becomes a capability router rather than a difficulty escalator. > Takeaways: smart-friend works today when both models are strong. Getting it to work with an asymmetrically weaker primary, which is the version that leads to the biggest unlocks, is still an open problem, and we think it's a training one. Reach out if you want to compare notes. ## Looking Ahead: Higher-Level Delegation The two patterns above share a structure: one writer, augmented by other agents contributing intelligence around it. The obvious next question is whether this extends to agents owning larger scope, for example, a product feature that spans ten PRs, a migration that touches a dozen services, a week of work rather than an afternoon's. This is live in Devin today. A manager Devin can break a larger task into pieces, spawn child Devins to work on them, and coordinate their progress through an internal MCP. Getting it to feel coherent took more context engineering than we expected. Managers trained on small-scoped delegation default to being overly prescriptive, which backfires when the manager lacks deep codebase context. Agents assume they share state with their children when they don't. Cross-agent communication, a sub-agent writing messages back to its manager to be passed to other agents in the agent team, doesn't happen by default, because models haven't been trained in environments where it needed to. Each of these took dedicated work to fix, and we're still improving on all of them. What about unstructured swarms? We think the unstructured-swarm approach, arbitrary networks of agents negotiating with each other, is mostly a distraction. The practical shape is map-reduce-and-manage: a manager splits work, children execute, the manager synthesizes and reports back. Making this type of system feel as coherent as a single agent working on a single task is at the center of some of our upcoming work in 2026. What We Know Today There’s a shared through-line with all of these experiments: multi-agent systems work best today when writes stay single-threaded and the additional agents contribute intelligence rather than actions. A clean-context reviewer catches bugs the coder can't see. A frontier-level smart friend catches subtleties a weaker primary misses. A manager coordinates scope across child agents without fragmenting decisions. The open problems are all communication problems. How does a weaker model learn when to escalate? How does a child agent surface a discovery that should change its siblings' work? How do you transfer context between agents without drowning the receiver? You can get decently far with prompting, but we also expect the next generation of models, including the ones we train ourselves, to start closing these gaps. We're building toward a world where intelligence is injected at every stage of the software development lifecycle — planning, coding, review, testing, and monitoring — not as a swarm of autonomous actors, but as a coordinated system that scales human taste. We welcome you to try our work at [devin.ai](http://app.devin.ai/) or [windsurf.com](http://windsurf.com/). And if you would enjoy discovering some of these agent-building principles with us, reach out to [walden@cognition.ai](mailto:walden@cognition.ai) \[1\] Coincidentally, Anthropic [came out the next day](https://www.anthropic.com/engineering/multi-agent-research-system) with a related blogpost about building a multi-agent research system. Both blogposts touched on similar challenges with context engineering and came to similar conclusions about the first area of applicability being in readonly agents \[2\] Recently, Anthropic [launched a similar beta experiment](https://claude.com/blog/the-advisor-strategy) to let their smaller models make calls out to their larger models in the same fashion. At a minimum, this suggest the models on the “smart friend” end will also get better at communicating back with the primary model. ]]> Thu, 23 Apr 2026 03:20:21 GMT https://reader-feed.pages.dev/posts/08be90092a-Multi-Agents%20What%27s%20Actually%20Working.md obsidian:1a11da40a2:inbox/REPL 是 MCP 和 CLI 的最终形态.md REPL 是 MCP 和 CLI 的最终形态 “任何足够复杂的 C 或 Fortran 程序，都包含了一个临时拼凑的、非正式规定的、有 bug 的、慢速的 Common Lisp 一半功能的实现。” —— Greenspun 第十定律一、Tool Calling 已经走到了一个十字路口过去两年里，… “任何足够复杂的 C 或 Fortran 程序，都包含了一个临时拼凑的、非正式规定的、有 bug 的、慢速的 Common Lisp 一半功能的实现。” —— [Greenspun 第十定律](https://zhida.zhihu.com/search?content_id=273177273&content_type=Article&match_order=1&q=Greenspun+%E7%AC%AC%E5%8D%81%E5%AE%9A%E5%BE%8B&zhida_source=entity) ### 一、Tool Calling 已经走到了一个十字路口 过去两年里，让大模型”使用工具”的范式经历了三次主要形态： 1. **Function Calling** ：模型输出固定 schema 的 JSON，应用层路由到具体函数。简单、可验证，但每一个能力都需要人类工程师提前注册。 2. **[MCP](https://zhida.zhihu.com/search?content_id=273177273&content_type=Article&match_order=1&q=MCP&zhida_source=entity) (Model Context Protocol)** ：把 function calling 抽离成跨进程协议。任何服务实现 MCP server 就能把能力暴露给 agent。工具的供给侧被解耦了，但抽象层次没有提升 —— 它依然是”预定义、再调用”的 RPC 模式。 3. **[CLI](https://zhida.zhihu.com/search?content_id=273177273&content_type=Article&match_order=1&q=CLI&zhida_source=entity) Agent** ：agent 直接操作 shell，所有 Unix 工具瞬间成为可用能力。这是真正的范式转变：工具注册表被换成了一个通用执行面。 。当执行单位从”注册过的函数”升级到”让一个图灵完备的解释器求值”时，能力上限就从”工程师预想过的那些任务”变成了”这门语言能表达的任何任务”。 问题是：CLI 止步得太早。它把解释器暴露给了 agent，但那是一个能力受限的解释器 —— bash 的类型系统是字符串，组合是 `|` 和 `&&` ，状态是全局环境变量。CLI 指对了方向，但还不是终点。 终点是 REPL：Read-Eval-Print Loop，一个针对表达式的“读取-求值-输出”循环 ### 二、MCP 正在重新发明一个半成品的解释器 Greenspun 第十定律的现代变体应该这么写： > 任何足够成熟的 tool-calling 基础设施，最终都会包含一个临时拼凑的、欠规范的、有 bug 的 REPL 的一半实现。 这不是修辞，而是可观察的事实。看一个稍微复杂点的 MCP server 实际在做什么： - 它需要 **变量绑定** （”把上一个查询的结果传给下一个工具”）→ 在重新实现赋值与作用域。 - 它需要 **条件分发** （”如果场景里有 X 就做 A，否则做 B”）→ 在重新实现 `if` 。 - 它需要 **批处理与循环** （”对列表里每一项调用这个工具”）→ 在重新实现 `for` 。 - 它需要 **工具组合** （”先查询、再修改、再验证”）→ 在重新实现函数组合。 - 它需要处理 **异步** （等待加载、等待动画、等待网络）→ 在重新实现 [coroutine](https://zhida.zhihu.com/search?content_id=273177273&content_type=Article&match_order=1&q=+coroutine&zhida_source=entity) 或 Promise。 每一条都是在 JSON schema 上打补丁，模拟一门编程语言本来就自带的能力。而 agent 拿到这些拼凑品之后，还要用自然语言去驾驭它们 —— 相当于用一层翻译层操作另一层翻译层。 MCP 在历史上并不错。在模型还没学会稳定生成代码的时候，结构化 schema 是避免幻觉的护栏。但当模型生成代码的能力已经逼近甚至超过它们调用工具的能力时，schema 就从”护栏”变成了”天花板”。 ### 三、Token is language. Language is evaluation. Evaluation is the universal tool. REPL 的核心论断很简单： **模型已经在生成一门真实编程语言的 token 了，那就直接 eval 它。** Agent 的输出是 `AssetDatabase.LoadAssetAtPath("Assets/Prefabs/Enemies/Blender.prefab")` ，它本身就是一段合法的 C#。不需要包装成 `{"tool": "load_asset", "params": {"path": "..."}}` ，不需要服务端再把 JSON 反序列化回 C# 去反射调用 —— 直接把源码送进解释器求值就结束了。 这个观察带来三个结构性优势。 ### 1\. Schema-free：工具面不再需要被枚举 传统 tool-calling 的工具面是 **封闭的** ：注册了 100 个工具，agent 就只会用这 100 个。在 REPL 范式里，工具面等于整个宿主语言生态 —— 所有库、所有类型、甚至反射可达的一切。这是一个开放、无穷的表面。 这不是”功能多一点”的量变，而是质变。面对一个从未见过的系统状态，agent 可以即席组合标准库、用户代码、LINQ、反射，做出一次 **此前没有人想到过** 的查询。没有人需要提前为它注册一个 endpoint。 ### 2\. 组合性：语言天然自带的能力 把能力塞进语言、而不是塞进协议，意味着立刻继承了语言的一切 —— 变量、闭包、泛型、管道、async/await。语言做一件事，协议要做五件事，这就是 Greenspun 定律的直接后果。 ### 3\. 异步的语言级解决 这是被严重低估的一点。传统 RPC 架构里处理”等加载完”或”两秒后再检查”这类异步场景，要么让 agent 轮询（浪费 token、破坏控制流），要么在 server 侧自己搭一个状态机。 REPL 走了第三条路： **让 agent 返回一个 coroutine / Promise / generator，server 自己把它 drive 到完成** ，然后把最终值作为响应写回。这在 MCP 协议层是做不到的 —— MCP 的请求/响应语义就是一次性的，没有”我暂时不能回你，你帮我 tick 一下”这种 idiom。但在一个 REPL 里，这就是语言本身的控制流。异步从”上层要解决的分布式问题”降维成了”语言原生支持的一种表达”。 ### 四、Exploration → Crystallization：Agent 自己编织工具链 传统工具架构有一个根深蒂固的假设： **工具的作者和工具的使用者是两个不同的角色** 。工程师负责把 API 包装成 tool，agent 负责按说明书使用。 REPL 取消了这个分工。 一个典型的链路是这样的： 1. Agent 第一次面对一个陌生项目，打开 REPL 像一个新来的工程师一样交互式探索：列类型、dump 状态、跑小片段验证假设。 2. 在某次成功探索之后，它发现某套动作序列是有价值的。 3. Agent 把这套序列 **固化** 成一个脚本文件，写进工程里。下次一行调用就能复用。 **探索与固化都由 agent 独立完成** 工具不是被预先安装的，而是在飞行中被锻造的。这改变了 tool-calling 的本质：工具不再是 agent 的”输入”，而是 agent 工作产物的一部分。 这是 MCP 触达不到的形态。MCP 的工具生命周期在协议之外 —— 需要重启 server、重新注册、人类审阅。REPL 的工具生命周期在代码里 —— 提交一个文件就完成了。 ### 五、终局 工具调用的演化，是”抽象层次逐步上移”的过程： | 阶段 | 抽象单位 | 谁决定能力边界 | | --- | --- | --- | | Function Calling | 单个 endpoint | 工程师 | | MCP | 一组 endpoint | 工程师 + 协议维护者 | | CLI | shell 表达式 | 操作系统 | | REPL | 宿主语言表达式 | agent 自己 | 当抽象单位等同于宿主语言本身时，再往上就没有更高的抽象层了 —— 你已经直接面对图灵完备。任何进一步的”优化”只能发生在语言内部（更好的库、更好的 sandbox、更好的错误消息），而不是协议层的重新设计。 这就是 REPL 作为”最终形态”的含义：不是因为它最新，而是因为 **再往前一步就会撞上计算的理论上限** 。在 MCP 协议上再加十年的 spec 演进，它仍然是在逼近同一个目标 —— 一个能让模型自由地表达意图并求值的环境。而那个环境，有一个古老、成熟、久经考验的名字： **REPL.** ### 六、把论证落到一个真实的引擎上 论点归论点，架构的价值只有在被”做成”之后才真正显现。我们选了一个最适合检验这套思路的场景 —— Unity，然后开源了 **[Unity REPL](https://link.zhihu.com/?target=https%3A//github.com/LambdaLabsHQ/unity-repl)** 。 Unity 是一个被传统 tool 架构彻底打败的领域。游戏状态是深度嵌套的 scene graph、几百种 MonoBehaviour、序列化资源、异步加载、Editor 与 PlayMode 两套语义。想用 MCP 暴露哪怕”合理的 10%“，就要维护几十个 endpoint，而任何一个稍有新意的调试需求都会立即溢出这个表面。 更关键的是： **Unity 的能力已经被 C# 完美地 API 化了** 。Unity 的设计者几十年前就做完了”设计一门语言面向所有引擎能力”的工作。再在它之上罩一层 MCP schema，相当于把一座精心设计的图书馆重新包装成一本目录，然后要求读者只能按目录借书。 Unity REPL 把这层多余的目录直接撕掉： ``` AI Agent ──(Raw C# Tokens)──► File IPC (/Temp/UnityReplIpc/) ──► Unity Editor Main Thread ``` Agent 发 C# 源码， `Mono.CSharp` 在 Unity Editor Main Thread 上直接求值，整个 Editor / Runtime API 都是可用工具面。Session 里声明的类型和变量跨调用保留，直到 domain reload。 第三节讲的”语言级异步”在这里是这样落的 —— REPL 表达式返回 `IEnumerator` 时，server 会跨帧 drive 它，把最后一个 yield 值作为响应写回： ``` public static IEnumerator ComplexSetup() { EditorSceneManager.OpenScene("Assets/Scenes/TestScene.unity"); yield return null; // 等一帧 var go = new GameObject("TestEnemy"); yield return new WaitForSeconds(2.0f); // 真实等待两秒 go.GetComponent().Damage(10); yield return "done"; // 最后一个 yield 值 → 响应 } ``` Agent 写的是地道的 Unity coroutine，而不是把异步拆成五次 MCP round-trip。 第四节讲的”exploration → crystallization”，在这里是一段真实的 live session 到一个提交文件的过程： ``` UnityREPL ready. Type C# expressions: > var prefab = AssetDatabase.LoadAssetAtPath("Assets/Prefabs/Enemies/Blender.prefab"); > var obj = PrefabUtility.InstantiatePrefab(prefab) as GameObject; > obj.transform.position = new Vector3(10, 0, 5); > var turrets = GameObject.FindObjectsOfType(); > string.Join("\n", turrets.Select(t => $"{t.name}: {Vector3.Distance(t.transform.position, obj.transform.position)}m")) LaserTurret_1: 12.5m GrenadeTurret_2: 8.2m ``` 没有人给这个 agent 预先注册过 `SpawnEnemy()` 或 `GetTurretDistances()` 。它写了 C#，C# 就执行了。而当它发现这套动作值得复用，它会自己把它固化成一个编辑器脚本，放进 `Assets/Editor/` ： ``` // 由 agent 自己生成并提交到版本控制 public static class TurretRangeProbe { public static string RunAt(Vector3 pos) => string.Join("\n", GameObject.FindObjectsOfType() .Select(t => $"{t.name}: {Vector3.Distance(t.transform.position, pos)}m")); } ``` 下次一行 `TurretRangeProbe.RunAt(new Vector3(10, 0, 5))` 就能复用。工具链不是 Unity 团队维护的，不是插件作者维护的，而是 **这个 agent 自己在这个项目里锻造出来的** ，像任何工程师写的代码一样可以被 review、被复用、被演进。 ### 开始使用 在你的 Unity 工程里打开任意支持 skill 的 agent（Claude Code / Cursor / Codex CLI 等），贴入下面这段提示，它会自行完成安装、注册、握手验证： ``` Add \`"com.lambda-labs.unity-repl": "https://github.com/LambdaLabsHQ/unity-repl.git"\` to the \`dependencies\` in \`Packages/manifest.json\`. Then register the Unity REPL skill: try running \`npx skills add ./Packages/com.lambda-labs.unity-repl\`. If that fails, the skill definition is at \`./Packages/com.lambda-labs.unity-repl/.agents/skills/unity-repl/SKILL.md\` — use your agent runtime's skill installer to register it. Finally, verify the REPL server is working by evaluating \`Application.unityVersion\` through the skill. ``` 全程不需要手动配 MCP server，不需要设计任何 schema。要求 Unity 2021.3+，仅 Editor，Windows / macOS / Linux 全平台。 - 主仓库： [github.com/LambdaLabsHQ](https://link.zhihu.com/?target=https%3A//github.com/LambdaLabsHQ/unity-repl) - 键鼠输入注入（可选）： [github.com/LambdaLabsHQ](https://link.zhihu.com/?target=https%3A//github.com/LambdaLabsHQ/unity-agent-input) - Game View 视觉（可选）： [github.com/LambdaLabsHQ](https://link.zhihu.com/?target=https%3A//github.com/LambdaLabsHQ/unity-agent-vision) 三者合起来，就是一个完整的、不依赖任何预定义工具的 Unity AI 工位。 --- > *The language is your only tool.* 编辑于 2026-04-15 21:42・上海 ]]> Thu, 23 Apr 2026 02:59:44 GMT https://reader-feed.pages.dev/posts/1a11da40a2-REPL%20%E6%98%AF%20MCP%20%E5%92%8C%20CLI%20%E7%9A%84%E6%9C%80%E7%BB%88%E5%BD%A2%E6%80%81.md obsidian:2801bf220d:agent/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/2801bf220d-README.md obsidian:3dbe874f83:archive/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/3dbe874f83-README.md obsidian:5995ffa1b5:civic/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/5995ffa1b5-README.md obsidian:6042c7fc39:companies/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/6042c7fc39-README.md obsidian:b7d267b9be:concepts/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/b7d267b9be-README.md obsidian:496424c674:deals/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/496424c674-README.md obsidian:8378acb982:hiring/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/8378acb982-README.md obsidian:874cbbcbdb:household/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/874cbbcbdb-README.md obsidian:b6f6dc35bc:ideas/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/b6f6dc35bc-README.md obsidian:307d34d71a:inbox/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/307d34d71a-README.md obsidian:02fc5ecf10:media/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/02fc5ecf10-README.md obsidian:751e0a99dd:meetings/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/751e0a99dd-README.md obsidian:c378d687c0:org/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/c378d687c0-README.md obsidian:bdc8dc9019:people/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/bdc8dc9019-README.md obsidian:23d5eaca61:personal/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/23d5eaca61-README.md obsidian:4084af2529:programs/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:17 GMT https://reader-feed.pages.dev/posts/4084af2529-README.md obsidian:25dda778be:projects/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:16 GMT https://reader-feed.pages.dev/posts/25dda778be-README.md obsidian:7415e4a3da:prompts/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:16 GMT https://reader-feed.pages.dev/posts/7415e4a3da-README.md obsidian:2fff70d9ea:sources/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:16 GMT https://reader-feed.pages.dev/posts/2fff70d9ea-README.md obsidian:ac6536f5b1:writing/README.md Readme > Resolver: What goes here, what doesn't. Resolver: What goes here, what doesn't. ]]> Wed, 22 Apr 2026 07:48:16 GMT https://reader-feed.pages.dev/posts/ac6536f5b1-README.md obsidian:13318548ac:inbox/harness-engineering-for-coding-agent-users.md Harness engineering for coding agent users >- Wed, 22 Apr 2026 07:48:16 GMT https://reader-feed.pages.dev/posts/13318548ac-harness-engineering-for-coding-agent-users.md obsidian:b60f8c2ef1:sources/vadim-comanescu/dark-factory-diaries-1.md 黑暗工厂日记 当你尝试构建一个无人操作的软件工厂时会发生什么。组织理论、误差数学，以及为什么有趣的问题从来都不是代码本身。 2026-02-08T00:00:00.000Z https://reader-feed.pages.dev/posts/b60f8c2ef1-dark-factory-diaries-1.md obsidian:8e7bef4765:sources/vadim-comanescu/dark-factory-diaries-2.md 黑暗工厂日记 我像组建人类团队一样为我的AI流水线配备了角色：产品经理、工程师、质检员、评审员。结果它重现了官僚主义。解决办法是彻底抛弃人类类比。 2026-02-20T00:00:00.000Z https://reader-feed.pages.dev/posts/8e7bef4765-dark-factory-diaries-2.md obsidian:4303ca7e21:sources/vadim-comanescu/dark-factory-diaries-3.md 黑暗工厂日记 1961年，新乡重夫用一个碟子和两根弹簧消除了工厂的缺陷。同样的理念，是我发现的最有效的工具——用来对付那些无法遵守指令的 AI 代理。 2026-02-28T00:00:00.000Z https://reader-feed.pages.dev/posts/4303ca7e21-dark-factory-diaries-3.md obsidian:6ea72f73f3:sources/vadim-comanescu/dark-factory-diaries-4.md 黑暗工厂日记 编码代理的上下文管理分为两个问题。本文涵盖第一个：在单次运行中，什么填满了窗口，为什么其中大部分被浪费在代码读取上，以及基于相关性的剪枝如何改变了经济性。 2026-03-15T00:00:00.000Z https://reader-feed.pages.dev/posts/6ea72f73f3-dark-factory-diaries-4.md obsidian:2c6d88a543:sources/vadim-comanescu/dark-factory-diaries-5.md 黑暗工厂日记 即使每次读取的内容都是相关的，长时间的编码代理运行仍然会出现性能退化。解决之道不是更聪明的上下文压缩，而是每个新鲜的上下文窗口只执行一个有边界的任务，并在迭代之间将运行轨迹持久化到磁盘。 从检查点B恢复 ## 复合工程让重置变得无代价 显而易见的反驳是：新鲜的上下文不会丢失前一次迭代学到的所有东西吗？不会。这正是复合工程的用途。每次迭代将其学到的知识写入磁盘上的共享文件：AGENTS.md 用架构决策更新，计划文件标注什么有效、什么无效，轨迹捕获具体的错误及其导致的方法。下一次迭代在加载其新鲜上下文时读取这些文件。没有任何东西丢失。知识存在于代码库中，而非模型的记忆中。 当早期版本的轨迹格式只记录"完成任务X"而没有记录导致第一次尝试失败的具体错误时，我深刻体会到了这一点的重要性。下一次迭代尝试了相同的方法，遇到了相同的错误，浪费了整个周期。解决方案不是更好的上下文管理，而是更好的轨迹：结构化的、具体的、包含失败信息的。一旦持久化层运作正常，新鲜上下文模式就严格优于旧模式。你获得了干净的推理，没有累积的混乱，同时拥有复合知识，没有过时的状态。 这也是模型分层自然契合的地方。像 Opus 这样的昂贵推理模型可以在单个新鲜窗口内处理困难任务。像 Sonnet 这样的便宜模型处理大部分有边界的任务，在这些任务中上下文保持小而专注。每个都从零开始，读取共享产物，做一件事，然后退出。 ## 同一个问题的两个半面 编码代理中的上下文管理分为两个问题： - **单次运行内：**窗口的大部分被代码读取填满。剪枝它们。（日记 #4。） - **跨运行：**累积状态腐蚀工作集。不要让它累积。每个新鲜窗口一个任务，轨迹存储在磁盘上。（本文。） 两者都基于同一原则：上下文窗口是工作记忆，不是存储。 --- *获取新文章，请通过邮件订阅* ]]> 2026-03-16T00:00:00.000Z https://reader-feed.pages.dev/posts/2c6d88a543-dark-factory-diaries-5.md obsidian:85471897d1:sources/vadim-comanescu/dark-factory-diaries-6-pi.md 黑暗工厂日记 Arianna 需要一个编码代理后端。不是聊天模型，不是代理框架。而是一个接收提示、使用工具、然后退出的子进程。Pi 以 Unix 级别的简洁性做到了这一点，而其背后的设计选择比功能列表更重要。 2026-04-06T00:00:00.000Z https://reader-feed.pages.dev/posts/85471897d1-dark-factory-diaries-6-pi.md obsidian:5b922581a8:sources/vadim-comanescu/the-lights-are-on-everywhere.md 灯火通明 基于我的个人经验，我相信正在发生一些深刻的事情，而很多人还没有意识到。 2026-02-13T00:00:00.000Z https://reader-feed.pages.dev/posts/5b922581a8-the-lights-are-on-everywhere.md obsidian:2e9086b640:sources/vadim-comanescu/dark-factory-diaries-2-停止构建机器人团队.md 黑暗工厂日记 #2：停止构建机器人团队 我像组建人类团队一样为我的AI流水线配备了角色：产品经理、工程师、质检员、评审员。结果它重现了官僚主义。解决办法是彻底抛弃人类类比。 Tue, 21 Apr 2026 06:18:46 GMT https://reader-feed.pages.dev/posts/2e9086b640-dark-factory-diaries-2-%E5%81%9C%E6%AD%A2%E6%9E%84%E5%BB%BA%E6%9C%BA%E5%99%A8%E4%BA%BA%E5%9B%A2%E9%98%9F.md obsidian:2b4bd2eb57:sources/vadim-comanescu/dark-factory-diaries-1-自主软件工厂的架构.md 黑暗工厂日记 #1：组织理论、错误数学与自主软件工厂的架构 当你尝试构建一个无人操作的软件工厂时会发生什么。组织理论、误差数学，以及为什么有趣的问题从来都不是代码本身。 Tue, 21 Apr 2026 06:17:35 GMT https://reader-feed.pages.dev/posts/2b4bd2eb57-dark-factory-diaries-1-%E8%87%AA%E4%B8%BB%E8%BD%AF%E4%BB%B6%E5%B7%A5%E5%8E%82%E7%9A%84%E6%9E%B6%E6%9E%84.md obsidian:1649afe9ce:sources/vadim-comanescu/the-lights-are-on-everywhere-灯火通明.md 灯火通明 基于我的个人经验，我相信正在发生一些深刻的事情，而很多人还没有意识到。 Tue, 21 Apr 2026 06:09:39 GMT https://reader-feed.pages.dev/posts/1649afe9ce-the-lights-are-on-everywhere-%E7%81%AF%E7%81%AB%E9%80%9A%E6%98%8E.md obsidian:f95f682c1e:sources/vadim-comanescu/dark-factory-diaries-6-为什么选择Pi作为编码代理.md 黑暗工厂日记 #6：为什么选择Pi作为编码代理 Arianna 需要一个编码代理后端。不是聊天模型，不是代理框架。而是一个接收提示、使用工具、然后退出的子进程。Pi 以 Unix 级别的简洁性做到了这一点，而其背后的设计选择比功能列表更重要。 Tue, 21 Apr 2026 06:08:35 GMT https://reader-feed.pages.dev/posts/f95f682c1e-dark-factory-diaries-6-%E4%B8%BA%E4%BB%80%E4%B9%88%E9%80%89%E6%8B%A9Pi%E4%BD%9C%E4%B8%BA%E7%BC%96%E7%A0%81%E4%BB%A3%E7%90%86.md obsidian:8e40358edc:sources/vadim-comanescu/dark-factory-diaries-4-管理单次代理运行中的上下文.md 黑暗工厂日记 #4：管理单次代理运行中的上下文 编码代理的上下文管理分为两个问题。本文涵盖第一个：在单次运行中，什么填满了窗口，为什么其中大部分被浪费在代码读取上，以及基于相关性的剪枝如何改变了经济性。 Tue, 21 Apr 2026 06:07:57 GMT https://reader-feed.pages.dev/posts/8e40358edc-dark-factory-diaries-4-%E7%AE%A1%E7%90%86%E5%8D%95%E6%AC%A1%E4%BB%A3%E7%90%86%E8%BF%90%E8%A1%8C%E4%B8%AD%E7%9A%84%E4%B8%8A%E4%B8%8B%E6%96%87.md obsidian:208676a6cc:sources/vadim-comanescu/dark-factory-diaries-5-每个上下文窗口一个任务.md 黑暗工厂日记 #5：每个上下文窗口一个任务 即使每次读取的内容都是相关的，长时间的编码代理运行仍然会出现性能退化。解决之道不是更聪明的上下文压缩，而是每个新鲜的上下文窗口只执行一个有边界的任务，并在迭代之间将运行轨迹持久化到磁盘。 从检查点B恢复 ## 复合工程让重置变得无代价 显而易见的反驳是：新鲜的上下文不会丢失前一次迭代学到的所有东西吗？不会。这正是复合工程的用途。每次迭代将其学到的知识写入磁盘上的共享文件：AGENTS.md 用架构决策更新，计划文件标注什么有效、什么无效，轨迹捕获具体的错误及其导致的方法。下一次迭代在加载其新鲜上下文时读取这些文件。没有任何东西丢失。知识存在于代码库中，而非模型的记忆中。 当早期版本的轨迹格式只记录"完成任务X"而没有记录导致第一次尝试失败的具体错误时，我深刻体会到了这一点的重要性。下一次迭代尝试了相同的方法，遇到了相同的错误，浪费了整个周期。解决方案不是更好的上下文管理，而是更好的轨迹：结构化的、具体的、包含失败信息的。一旦持久化层运作正常，新鲜上下文模式就严格优于旧模式。你获得了干净的推理，没有累积的混乱，同时拥有复合知识，没有过时的状态。 这也是模型分层自然契合的地方。像 Opus 这样的昂贵推理模型可以在单个新鲜窗口内处理困难任务。像 Sonnet 这样的便宜模型处理大部分有边界的任务，在这些任务中上下文保持小而专注。每个都从零开始，读取共享产物，做一件事，然后退出。 ## 同一个问题的两个半面 编码代理中的上下文管理分为两个问题： - **单次运行内：**窗口的大部分被代码读取填满。剪枝它们。（日记 #4。） - **跨运行：**累积状态腐蚀工作集。不要让它累积。每个新鲜窗口一个任务，轨迹存储在磁盘上。（本文。） 两者都基于同一原则：上下文窗口是工作记忆，不是存储。 --- *获取新文章，请通过邮件订阅* ]]> Tue, 21 Apr 2026 06:07:19 GMT https://reader-feed.pages.dev/posts/208676a6cc-dark-factory-diaries-5-%E6%AF%8F%E4%B8%AA%E4%B8%8A%E4%B8%8B%E6%96%87%E7%AA%97%E5%8F%A3%E4%B8%80%E4%B8%AA%E4%BB%BB%E5%8A%A1.md obsidian:764a34057d:sources/vadim-comanescu/dark-factory-diaries-3-让工厂防错.md 黑暗工厂日记 #3：让工厂防错 1961年，新乡重夫用一个碟子和两根弹簧消除了工厂的缺陷。同样的理念，是我发现的最有效的工具——用来对付那些无法遵守指令的 AI 代理。 Tue, 21 Apr 2026 06:06:56 GMT https://reader-feed.pages.dev/posts/764a34057d-dark-factory-diaries-3-%E8%AE%A9%E5%B7%A5%E5%8E%82%E9%98%B2%E9%94%99.md