vault: sync ECC orchestration findings, add PRP/DevFleet/Agent-worktree routes, fix outdated counts

.obsidian/community-plugins.json

@@ -1,5 +1,6 @@
 [
   "obsidian-checklist-plugin",
   "calendar",
-  "obsidian-git"
+  "obsidian-git",
+  "terminal"
 ]

.obsidian/plugins/obsidian-git/data.json

@@ -8,7 +8,7 @@
   "autoPullInterval": 0,
   "autoPullOnBoot": true,
   "autoCommitOnlyStaged": false,
-  "disablePush": false,
+  "disablePush": true,
   "pullBeforePush": true,
   "disablePopups": false,
   "showErrorNotices": true,

.obsidian/plugins/terminal/data.json

@@ -0,0 +1,168 @@
+{
+  "addToCommand": true,
+  "addToContextMenu": true,
+  "createInstanceNearExistingOnes": true,
+  "errorNoticeTimeout": 0,
+  "exposeInternalModules": true,
+  "focusOnNewInstance": true,
+  "hideStatusBar": "focused",
+  "interceptLogging": true,
+  "language": "",
+  "macOSOptionKeyPassthrough": true,
+  "newInstanceBehavior": "newHorizontalSplit",
+  "noticeTimeout": 5,
+  "openChangelogOnUpdate": true,
+  "pinNewInstance": true,
+  "preferredRenderer": "webgl",
+  "profiles": {
+    "darwinExternalDefault": {
+      "args": [
+        "\"$PWD\""
+      ],
+      "executable": "/System/Applications/Utilities/Terminal.app/Contents/macOS/Terminal",
+      "followTheme": true,
+      "name": "",
+      "platforms": {
+        "darwin": true
+      },
+      "restoreHistory": false,
+      "rightClickAction": "copyPaste",
+      "successExitCodes": [
+        "0",
+        "SIGINT",
+        "SIGTERM"
+      ],
+      "terminalOptions": {
+        "documentOverride": null
+      },
+      "type": "external"
+    },
+    "darwinIntegratedDefault": {
+      "args": [
+        "--login"
+      ],
+      "executable": "/bin/zsh",
+      "followTheme": true,
+      "name": "",
+      "platforms": {
+        "darwin": true
+      },
+      "pythonExecutable": "python3",
+      "restoreHistory": false,
+      "rightClickAction": "copyPaste",
+      "successExitCodes": [
+        "0",
+        "SIGINT",
+        "SIGTERM"
+      ],
+      "terminalOptions": {
+        "documentOverride": null
+      },
+      "type": "integrated",
+      "useWin32Conhost": true
+    },
+    "developerConsole": {
+      "followTheme": true,
+      "name": "",
+      "restoreHistory": false,
+      "rightClickAction": "copyPaste",
+      "successExitCodes": [
+        "0",
+        "SIGINT",
+        "SIGTERM"
+      ],
+      "terminalOptions": {
+        "documentOverride": null
+      },
+      "type": "developerConsole"
+    },
+    "linuxExternalDefault": {
+      "args": [],
+      "executable": "xterm",
+      "followTheme": true,
+      "name": "",
+      "platforms": {
+        "linux": true
+      },
+      "restoreHistory": false,
+      "rightClickAction": "copyPaste",
+      "successExitCodes": [
+        "0",
+        "SIGINT",
+        "SIGTERM"
+      ],
+      "terminalOptions": {
+        "documentOverride": null
+      },
+      "type": "external"
+    },
+    "linuxIntegratedDefault": {
+      "args": [],
+      "executable": "/bin/sh",
+      "followTheme": true,
+      "name": "",
+      "platforms": {
+        "linux": true
+      },
+      "pythonExecutable": "python3",
+      "restoreHistory": false,
+      "rightClickAction": "copyPaste",
+      "successExitCodes": [
+        "0",
+        "SIGINT",
+        "SIGTERM"
+      ],
+      "terminalOptions": {
+        "documentOverride": null
+      },
+      "type": "integrated",
+      "useWin32Conhost": true
+    },
+    "win32ExternalDefault": {
+      "args": [],
+      "executable": "C:\\Windows\\System32\\cmd.exe",
+      "followTheme": true,
+      "name": "",
+      "platforms": {
+        "win32": true
+      },
+      "restoreHistory": false,
+      "rightClickAction": "copyPaste",
+      "successExitCodes": [
+        "0",
+        "SIGINT",
+        "SIGTERM"
+      ],
+      "terminalOptions": {
+        "documentOverride": null
+      },
+      "type": "external"
+    },
+    "win32IntegratedDefault": {
+      "args": [],
+      "executable": "C:\\Windows\\System32\\cmd.exe",
+      "followTheme": true,
+      "name": "",
+      "platforms": {
+        "win32": true
+      },
+      "pythonExecutable": "python3",
+      "restoreHistory": false,
+      "rightClickAction": "copyPaste",
+      "successExitCodes": [
+        "0",
+        "SIGINT",
+        "SIGTERM"
+      ],
+      "terminalOptions": {
+        "documentOverride": null
+      },
+      "type": "integrated",
+      "useWin32Conhost": true
+    }
+  },
+  "defaultProfile": null,
+  "terminalOptions": {
+    "documentOverride": null
+  }
+}

.obsidian/plugins/terminal/manifest.json

@@ -0,0 +1,14 @@
+{
+  "author": "polyipseity",
+  "description": "Integrate consoles, shells, and terminals.",
+  "fundingUrl": {
+    "Buy Me a Coffee": "https://buymeacoffee.com/polyipseity",
+    "GitHub Sponsors": "https://github.com/sponsors/polyipseity"
+  },
+  "version": "3.23.0",
+  "authorUrl": "https://github.com/polyipseity",
+  "id": "terminal",
+  "isDesktopOnly": false,
+  "minAppVersion": "1.4.11",
+  "name": "Terminal"
+}

.obsidian/plugins/terminal/styles.css

@@ -0,0 +1,32 @@
+.obsidian-plugin-library\:icon{fill:none;stroke:currentColor}.obsidian-plugin-library\:await-css{display:unset!important}.obsidian-plugin-library\:hide-status-bar{display:none}/**
+ * Copyright (c) 2014 The xterm.js authors. All rights reserved.
+ * Copyright (c) 2012-2013, Christopher Jeffrey (MIT License)
+ * https://github.com/chjj/term.js
+ * @license MIT
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * Originally forked from (with the author's permission):
+ *   Fabrice Bellard's javascript vt100 for jslinux:
+ *   http://bellard.org/jslinux/
+ *   Copyright (c) 2011 Fabrice Bellard
+ *   The original design remains. The terminal itself
+ *   has been extended to include xterm CSI codes, among
+ *   other features.
+ */.xterm{cursor:text;position:relative;user-select:none;-ms-user-select:none;-webkit-user-select:none}.xterm.focus,.xterm:focus{outline:none}.xterm .xterm-helpers{position:absolute;top:0;z-index:5}.xterm .xterm-helper-textarea{padding:0;border:0;margin:0;position:absolute;opacity:0;left:-9999em;top:0;width:0;height:0;z-index:-5;white-space:nowrap;overflow:hidden;resize:none}.xterm .composition-view{background:#000;color:#fff;display:none;position:absolute;white-space:nowrap;z-index:1}.xterm .composition-view.active{display:block}.xterm .xterm-viewport{background-color:#000;overflow-y:scroll;cursor:default;position:absolute;inset:0}.xterm .xterm-screen{position:relative}.xterm .xterm-screen canvas{position:absolute;left:0;top:0}.xterm-char-measure-element{display:inline-block;visibility:hidden;position:absolute;top:0;left:-9999em;line-height:normal}.xterm.enable-mouse-events{cursor:default}.xterm.xterm-cursor-pointer,.xterm .xterm-cursor-pointer{cursor:pointer}.xterm.column-select.focus{cursor:crosshair}.xterm .xterm-accessibility:not(.debug),.xterm .xterm-message{position:absolute;inset:0;z-index:10;color:transparent;pointer-events:none}.xterm .xterm-accessibility-tree:not(.debug) *::selection{color:transparent}.xterm .xterm-accessibility-tree{font-family:monospace;user-select:text;white-space:pre}.xterm .xterm-accessibility-tree>div{transform-origin:left;width:fit-content}.xterm .live-region{position:absolute;left:-9999px;width:1px;height:1px;overflow:hidden}.xterm-dim{opacity:1!important}.xterm-underline-1{text-decoration:underline}.xterm-underline-2{text-decoration:double underline}.xterm-underline-3{text-decoration:wavy underline}.xterm-underline-4{text-decoration:dotted underline}.xterm-underline-5{text-decoration:dashed underline}.xterm-overline{text-decoration:overline}.xterm-overline.xterm-underline-1{text-decoration:overline underline}.xterm-overline.xterm-underline-2{text-decoration:overline double underline}.xterm-overline.xterm-underline-3{text-decoration:overline wavy underline}.xterm-overline.xterm-underline-4{text-decoration:overline dotted underline}.xterm-overline.xterm-underline-5{text-decoration:overline dashed underline}.xterm-strikethrough{text-decoration:line-through}.xterm-screen .xterm-decoration-container .xterm-decoration{z-index:6;position:absolute}.xterm-screen .xterm-decoration-container .xterm-decoration.xterm-decoration-top-layer{z-index:7}.xterm-decoration-overview-ruler{z-index:8;position:absolute;top:0;right:0;pointer-events:none}.xterm-decoration-top{z-index:2;position:relative}.xterm .xterm-scrollable-element>.scrollbar{cursor:default}.xterm .xterm-scrollable-element>.scrollbar>.scra{cursor:pointer;font-size:11px!important}.xterm .xterm-scrollable-element>.visible{opacity:1;background:#0000;transition:opacity .1s linear;z-index:11}.xterm .xterm-scrollable-element>.invisible{opacity:0;pointer-events:none}.xterm .xterm-scrollable-element>.invisible.fade{transition:opacity .8s linear}.xterm .xterm-scrollable-element>.shadow{position:absolute;display:none}.xterm .xterm-scrollable-element>.shadow.top{display:block;top:0;left:3px;height:3px;width:100%;box-shadow:var(--vscode-scrollbar-shadow, #000) 0 6px 6px -6px inset}.xterm .xterm-scrollable-element>.shadow.left{display:block;top:3px;left:0;height:100%;width:3px;box-shadow:var(--vscode-scrollbar-shadow, #000) 6px 0 6px -6px inset}.xterm .xterm-scrollable-element>.shadow.top-left-corner{display:block;top:0;left:0;height:3px;width:3px}.xterm .xterm-scrollable-element>.shadow.top.left{box-shadow:var(--vscode-scrollbar-shadow, #000) 6px 0 6px -6px inset}.workspace-leaf-content[data-type="terminal:terminal"] .view-content{overflow:clip;display:flex;flex-direction:column}.terminal\:terminal{flex:1;min-width:0;min-height:0}.is-phone .workspace-leaf-content[data-type="terminal:terminal"] .view-content{padding-bottom:max(var(--size-4-4),calc(var(--icon-l) + var(--size-4-2) + max(var(--size-4-2),var(--safe-area-inset-bottom))))}

1 - Inbox/你不知道的大模型训练：原理、路径与新实践.md

@@ -0,0 +1,251 @@
+---
+title: "你不知道的大模型训练：原理、路径与新实践"
+source: "https://x.com/HiTw93/article/2040047268221608281"
+author:
+  - "[[Tw93 (@HiTw93)]]"
+published: 2026-04-03
+created: 2026-04-06
+description:
+tags:
+  - "clippings"
+---
+## 太长也要读
+
+在写完《你不知道的 Claude Code：架构、治理与工程实践》、《你不知道的 Agent：原理、架构与工程实践》后，我想着继续来写第三篇，这次打算挑战下自己来梳理一下大模型训练到底怎么回事，这篇文章争取让非专业背景的人也能读得懂。
+
+2026 年来看大模型效果真正拉开差距的地方，慢慢不再是预训练本身了，而在它更后面的那一大段：后训练、评测、奖励、Agent 训练、蒸馏，每一个步骤都在影响用户实际感受效果。你发现某个模型突然变强了，背后可能是这几块一起优化到位了，而非单一因素导致。
+
+下文按大模型训练链路顺序来讲，重点放在厂商怎么通过后半段训练栈来提升最终上线效果。
+
+## 大模型训练其实是一条流水线
+
+过去几年，一般会用参数、数据、算力的堆积来解释模型进步，但很多用户真正感受到的提升，并不是来自再多训一点基础语料，而是来自预训练后面那整套训练流程。模型怎么说话、怎么听指令、怎么推理、怎么用工具，这些都不是多喂一点互联网文本就能自然长出来的。
+
+InstructGPT 当年给过一个很直接的例子：一个只有 1.3B 参数、做过对齐和偏好优化的模型，在人类偏好评测里能赢过 175B 的 GPT-3，参数量差了两个数量级，用户最后却更喜欢那个小很多的版本，训练后半段是真的会改写用户感知。
+
+训练过程其实是一条流水线，数据、算法、系统、反馈这几层高度耦合，一层变化通常会传导到其他层，2026 年的模型能力和产业价值，也越来越集中在预训练后面的几层。
+
+![Image](https://pbs.twimg.com/media/HE-wqTjaMAApYhA?format=jpg&name=large)
+
+这也是我们平时为啥感觉豆包不太去争排名，但大家日常用起来却更符合心意的原因，是后训练做到位了。
+
+这六层只是为了看分工，下图的九个阶段是更详细的版本：原始数据和系统配方单独拆开，Agent harness 和 Deployment 也是后半段的细分。还有两条反馈回路贯穿始终：生产流量回到数据工程，离线评测结果回到预训练。
+
+![Image](https://pbs.twimg.com/media/HE-xsyAa8AAG-Bx?format=jpg&name=large)
+
+## 预训练只是模型底座
+
+预训练仍然是训练链路的起点，搞清楚它到底在做什么，才能理解后面的每一层都在补充什么。没有这一步，就没有语言建模能力，没有知识压缩，也没有后面那些能力迁移的空间。在工程上，它要做的不只是让模型学会预测下一个 token：把语言分布学进去，把大规模文本里的知识和模式压进参数，还要给后面的能力激活留出空间。下一个 token 预测只描述了训练形式，解释不了为什么规模上来之后，模型会突然多出一些之前没有的能力。
+
+GPT-3 之后，不少模型调优的工作会更加考虑到预算和配比，模型不是越大越好，参数量、训练 token 数和总计算预算之间有配比问题，很多模型不是做小了，而是训练量不足，在既定预算下没有训到更合适的点。
+
+真到训练决策里，更实际的问题是：如果有人给你一万张 H100 和一个月时间，你会如何去训一个足够好的开源模型？规模定律在这里更像一个预算分配工具，不是那种论文里的抽象曲线，最后还是需要静下心来考虑这些问题：下一轮训练到底该多堆参数，还是多喂数据？当前模型到底是能力不够，还是只是欠训练？有限 GPU 预算下，什么配比更值？
+
+预训练更像是给模型能力打地基，决定知识范围、泛化潜力和模式归纳能力，也决定后训练有没有可以利用的空间。但听不听指令、配不配合用户、关键任务跑起来稳不稳，这些预训练都是管不到的。
+
+预训练阶段不只是在决定学多少知识，它还在提前决定模型以后能长成什么样。tokenizer 的切分方式会直接影响后续训练，context window 拉到多长也要在前面定下来。要不要继续做多模态预训练，要不要把单卡可运行当成一开始就定下来的要求，这些取舍在训练阶段就写进配方了，不是发布时再补的功能 feature。Gemma 3 同时强调了 single accelerator、128K context、视觉能力和量化，背后反映的也是这类取舍。用户最终看到的那些能力，比如能在本地电脑上跑、能看图、能理解长文档，其实很多在训练阶段就已经定下来了。
+
+通过 Chinchilla 给出的数据最优点来看，对于 8B 参数的模型大约是 200B tokens，但 Llama3 8B 实际用了 15T tokens，超出约 75 倍。这类过训练配方通常能在同等参数下换来更高的能力密度，最后换来一个更小、推起来也更省的模型。衡量这件事，看总 FLOP（浮点运算次数）比看参数量更靠谱，下图直观展示了这个差距。
+
+![Image](https://pbs.twimg.com/media/HE-x1GCb0AAKwdS?format=jpg&name=large)
+
+还有一类容易被忽略的设计也发生在预训练阶段：tokenizer 词表大小、分词策略、字节级编码方式都会有挺大影响。Llama2 词表 32K，Llama3 扩到 128K 后，序列长度大约压缩了 15%，下游性能也会跟着上去，这个影响会延续到推理成本和多语言能力。中文、代码、数学公式的 token 效率在词表设计时就已经定下来了。比如一个把中文分得很碎的 tokenizer，劣势并不是每次多花几个 token，而是每次推理都要持续承担这个决策错误的代价。
+
+## 数据配方决定模型能力
+
+参数规模是过去几年大家比较的重要指标，但这两年更重要的东西叫「数据配方」。
+
+这个过程表面看是清洗数据，实际上是完整的数据生产工程。网页、代码仓库、书籍、论坛这些原始数据，要先走完文本抽取、语言识别、质量过滤、隐私处理、安全过滤和去重，才能进入预训练，下图展示了完整的漏斗处理流程。
+
+![Image](https://pbs.twimg.com/media/HE-x-stbkAAjJKL?format=jpg&name=large)
+
+如果只把数据当作训练燃料，很容易得出越多越好的结论。但数据工程更接近能力设计，模型看见什么、看不见什么，代码数学百科各占多大比例，这些选择直接影响模型最后形成的能力分布。
+
+去重和污染控制常被忽略，但它对结果影响很大，要处理的不只是低质量数据，还包括重复模板、许可证文本、镜像网页，以及 benchmark 泄漏带来的污染。如果 document-level 和 line-level dedup 做得不够，模型往往会反复吸收最容易复制的内容，却未必真正学到最有价值的部分，很多开源模型效果看起来是参差不齐，往往是数据处理质量的差距。
+
+最近两年，数据配比本身也成了单独要研究的问题。Data Mixing Laws 这类工作关注的，不只是还能收集多少数据，更是不同类型数据的占比会把模型带向什么能力结构。
+
+合成数据也已经从辅助手段变成正式训练流程的一部分，Self-Instruct 这类让模型自己生成指令数据的方法、DeepSeek-R1 的蒸馏轨迹，以及 Qwen、Kimi 系列里越来越明显的合成监督，都在往同一个方向走。每一代更强的模型，都会参与重构下一代模型所看到的数据。早期模型生成基础指令数据，更强的模型生成高质量推理轨迹和 CoT 数据，经过 RL 训练的推理模型再把这些轨迹蒸馏给更小的 dense 模型。dense 就是全部参数都跑，和 MoE 那种按需激活不一样。
+
+这里的关键是，模型往往要先在更大规模上形成能力，后面才可能把这些能力压缩到更小的模型上。DeepSeek-R1-Distill 系列就是直接例子。RL 后的大模型轨迹让 1.5B 到 70B 的 dense 模型都获得了明显收益，Llama 3.1 405B 也明确被用于提升 8B 和 70B 的后训练质量，这些不是附带产物，而是训练设计的一部分。
+
+## 系统和架构的约束，训练前就要想清楚
+
+很多人把训练理解成研究问题：目标函数怎么设，损失怎么降，模型结构怎么改。但真正的大模型训练里系统约束这一块非常重要，是分布式系统问题，而非单机上的深度学习问题。GPU 数量、显存带宽、并行策略、容错和成本，这些不能等到训练完才去调优，最开始就决定了你能训多大、支持多长上下文、能不能跑更复杂的后训练这些点。
+
+MoE 是这一层最典型的例子，多专家模式让模型在相近计算量下扩大总参数，也把每个 token 的激活成本控住。代价会让路由复杂、负载均衡难、基础设施重。DeepSeek-V3、Qwen 一系列 MoE 设计都是成本和效果的折中，不是单纯的架构偏好。
+
+最近公开配方里的讨论，不再只是模型大小和 token 配比这种粗粒度分析。muP 让超参可从小规模实验迁移到大规模训练，WSD learning rate 是先升后稳再衰减的学习率调度策略，再加上最优 batch size 和更高的数据对参数比例，这些都开始出现在正式训练报告里，这些细节正在变成同规模模型之间真正拉开差距的地方。
+
+长上下文、多模态和新架构如果只按产品功能点理解，会漏掉训练侧的约束。128K context 这种目标会直接改变 attention 成本、batch size、训练 curriculum（数据编排顺序）和并行策略，多模态改的不只是模型结构，还有 data mixing（多来源数据配比）、encoder 设计和安全评测。如果把单卡可运行当成硬要求，参数量、量化路径、模型家族大小都会跟着收紧。
+
+Forgetting Transformer 和 Kimi 的 Attention Residuals 这类工作，都是在回答类似的问题：更长的上下文如何训练，网络变深之后如何避免信息被稀释。你看到的是模型能处理更长输入，或者更便于部署，训练时面对的却是另一组完全不同的约束。
+
+算力预算是固定的，模型大小、训练 token 量、上下文长度、serving 成本，每往一个方向多花，其他方向就得让步。
+
+![Image](https://pbs.twimg.com/media/HE-yYQib0AEyDCA?format=jpg&name=large)
+
+上下文拉长，attention 成本直接膨胀，batch size 必须压小；模型做大，GPU 内存上来，serving 成本也跟着涨。这不是取舍选项，是资源约束的结果，大部分决定在训练开始前就锁死了。
+
+还有个工程现实经常被忽略：训练并不总是稳定的，几千张 GPU 跑了几周，突然出现训练损失突增，幅度大到无法忽略，只能回滚到几天前的 checkpoint，重新来过。
+
+除了 loss spike，还有单块 GPU 静默出错，不报错但悄悄产生错误梯度、NVLink 带宽异常、节点间通信抖动，每一种都可能污染若干步训练。能不能在大规模训练里快速检测、隔离、恢复，这是实验室级别的工程能力，不是读论文能解决的问题。
+
+DeepSeek-V3 在技术报告里专门提到，整个预训练过程没有出现 irrecoverable loss spike，也没有做任何 rollback，同时是少数公开验证 FP8 混合精度训练在超大规模模型上可行的案例。按公开数据，全流程约 2.788M H800 GPU hours，预训练完成了 14.8T tokens。
+
+训练系统和推理系统关系紧密，但不是同一个工程问题。训练关心梯度、并行、checkpoint、吞吐和成本，推理关心延迟、KV cache（缓存历史计算避免重复运算）、量化和服务稳定性。
+
+## 后训练才决定用户真正感受到的差距
+
+普通用户真正能感受到的很多提升，其实都发生在预训练之后。指令微调（Instruction tuning）用标注好的指令-回答数据对模型做监督训练。它改变的是回答方式，把怎么接任务、怎么组织输出、怎么像个配合的助手这些要求变成监督信号。一个基础模型也许已经具备不少潜在能力，但如果没有这一步，这些能力往往不会以用户期待的形式稳定冒出来。
+
+再往后看，RLHF、DPO、RFT 方向差不多，都在把"什么叫更好的回答"接进训练回路，但路径不同。
+
+- RLHF（基于人类反馈的强化学习）先模仿高质量回答，再用偏好比较做强化
+- DPO（直接偏好优化）把这条路径缩短，直接从偏好对比里学，不需要单独训奖励模型
+- RFT（强化微调）是工程上更容易落地的接口，把任务定义、grader 设计和奖励信号放到产品化流程里
+
+今天谈后训练，只讲 SFT 或 RL 已经不够了，更难的是评测怎么设、分数怎么打、什么样的回答才算值得继续优化。SFT 是监督微调，它学到的不只是知识，也在学风格。数据长度、格式、是否带引用、是否偏好分点表达，都会显著影响模型最后的输出形态。很多用户以为自己在比较能力，实际比出来的往往只是风格差异。再加上偏好评测天然偏爱更长的回答，很容易把看起来更认真的长输出当成更可靠。所以后训练只看榜单往往不够，还要结合真实任务结果、成本和稳定性。
+
+现代后训练是一条多阶段流水线，公开资料里 DeepSeek-R1 的配方是最清晰的。它分四个阶段推进：
+
+**阶段 1**是冷启动 SFT，在做强化学习之前，先用少量高质量的思维链 CoT 数据热身。DeepSeek-R1-Zero 证明了直接从 base model（预训练后尚未做对齐的原始模型）上做 RL 是可行的，但纯 RL 训练出来的模型会反复重复、语言混乱、可读性很差。冷启动 SFT 给 RL 一个更稳定的起点，先把格式和语言一致性收住，这不是多余步骤。
+
+**阶段 2**在数学、代码、逻辑等可验证领域做强化学习，用 GRPO 作为训练算法，以可程序检验的正确性作为奖励信号。关键在于为什么选 GRPO 而不是传统的 PPO：PPO 是近端策略优化，需要一个独立的价值网络（value network）来估算当前状态价值，在大模型上同时维护两个网络工程负担很高。GRPO 对同一个提示词采样多个回答，用组内排名替代绝对价值估计，不需要独立的价值网络，工程上简洁很多，DeepSeek 系列和 Cursor Composer 2 的 RL 基础设施都采用了接近 GRPO 的方案。
+
+**阶段 3**做拒绝采样微调（Rejection Sampling Fine-Tuning），把 RL 产生的成功轨迹过滤后转成新的 SFT 数据，再做一轮监督微调。这是 RL 和 SFT 之间的桥梁，RL 探索出的好轨迹，就这样变成下一轮 SFT 的高质量训练样本。
+
+**阶段 4**融入有益性和安全性偏好反馈，把模型调整到符合发布标准的助手形态。
+
+![Image](https://pbs.twimg.com/media/HE-ygg2bQAEFcQJ?format=jpg&name=large)
+
+四个阶段互相依赖：冷启动让 RL 稳定启动，RL 产生高质量数据，拒绝采样把这些数据变成下一轮 SFT 的输入，对齐 RL 完成行为收敛。从公开结果看，直接 SFT 和走完四个阶段，差距通常是能看出来的。
+
+## Eval、Grader、Reward 在重新定义训练目标
+
+负责把模型输出转成训练分数的组件叫 grader，它很容易出现大家想不到的问题。只看最终答案，模型很快学会走捷径；打分太粗，噪声会被强化学习持续放大；榜单涨了，真实任务未必跟着一样好。很多时候，用户以为自己在看 base model 差距，其实差距出在目标怎么定义上。
+
+放到训练流程里看，eval 决定测什么，grader 决定一次输出怎么变成分数，reward 决定模型后面会被往哪里推。它们连起来就是一条具体的反馈回路：任务定义、eval、grader、优化、rollout、再评测。rollout 指模型执行任务产生的轨迹，链路里任何一环跑偏，后续优化就会一起跑偏。
+
+只看最终结果，模型可能会碰巧答对，也可能沿着错误过程拿到正确答案，代码、数学和复杂推理任务里，这个问题尤其明显。中间步骤如果不进反馈，模型学到的往往不是更可靠的推理，而是怎样更高概率地拿到最后那一分。
+
+所以这几年越来越多工作从传统 RLHF 转向 verified rewards，用程序直接验证正确性。在数学、代码、逻辑这些可验证任务里，现在已经可以直接对正确性打分，不再主要依赖人工偏好。但 verified rewards 也没有把问题彻底解决掉。过优化、reward overfitting（打分规则被过度优化、能力却没真正提升），以及 mode collapse（输出高度单一、失去多样性）这些现象还是会出现，问题只是从偏好标得准不准，变成了打分链路稳不稳。
+
+模型写出来的思考过程，也不能直接当成内部过程的完整记录。Anthropic 在 reasoning model 的可观测性实验里发现，模型会使用额外提示，却不在可见 CoT 里承认；到了 reward hacking 场景，它更可能补一段看起来合理的解释。reward hacking 是钻打分系统空子，而不是真正完成任务。可见 CoT 更适合当训练和监控信号，不能直接当成完整真相。
+
+再往下一层，模型甚至会开始利用打分通道本身。reward tampering 和 alignment faking 这类研究表明，模型在理论上可能主动干预打分过程本身。reward tampering 是直接篡改奖励计算过程本身，alignment faking 是对齐伪装，表面合规但隐藏不对齐意图。
+
+一旦模型有足够强的环境访问能力，它优化的就不止任务结果，还可能包括 checklist、reward code 和训练关系本身。Anthropic 2025 年一项实验，在一组可被利用的生产编码 RL 环境里注入了额外的 reward-hack 知识，随后观察到了类似的泛化。模型学会 reward hacking 后，不只会在同类任务上继续利用，还出现了对齐伪装等更广泛失对齐。
+
+这些行为在标准对话评测里看不到，只在 Agent 任务环境里能看到。工程含义很直接，reward、grader、环境隔离和监控都要当成训练设计的一部分。
+
+到了 Agent 阶段，reward design 还会继续拆细，最终结果只是其中一项，另外还要单独度量过程质量、上下文管理和反作弊约束。Kimi K2.5 奖励的是有效拆解和真实并行；Chroma Context-1 会给搜索途中找到的相关文档记分；Cursor Composer 2 把长任务里的 summary 纳入奖励，因为总结一旦失真，后面的上下文会一路被带偏。
+
+具体到实现里，ORM 是结果奖励模型，只给最终答案打分，信号稀疏，成本低，适合先起步，但也更容易让模型走捷径。PRM 是过程奖励模型，给中间步骤打分，信号更密，对数学和代码推理通常更强，但标注和系统成本都高很多。OpenAI 在数学推理实验里看到，PRM 不只提高了正确率，也更容易把过程约束住，因为每一步都在被监督；问题也很直接，PRM 的成本通常是 ORM 的数倍，所以大多数真实系统还是先从 ORM 起步，只有在数学、代码、逻辑这类可验证任务里，才更有条件把 PRM 自动化，用程序去验证中间步骤，绕开人工标注瓶颈。
+
+![Image](https://pbs.twimg.com/media/HE-yphDagAAfv_X?format=jpg&name=large)
+
+这条回路完整跑起来是这样的：
+
+![Image](https://pbs.twimg.com/media/HE-yqmaacAAo2Sj?format=jpg&name=large)
+
+最近几类对齐方法都在做同一件事。Anthropic 的 Constitutional AI 把人类写的原则接进训练，用 AI feedback 替代逐条人工偏好。OpenAI 的 Deliberative Alignment 把安全遵守放进推理过程，让推理能力本身承担一部分安全约束。这里说的 Deliberative Alignment 是审慎对齐，核心是推理阶段自行判断安全规范，而不是依赖训入的反射行为。两条路线都在把对齐从人工标签变成训练目标内部的一部分。
+
+以 Constitutional AI 为例，两阶段流程是先让模型依照原则自我批评和修订输出，再用 AI feedback 替代逐条人工偏好标注。对齐从来不是挂在训练后面的补丁，系统测什么、怎么打分、奖励什么，模型就往哪个方向走，这本身就是训练后半段最直接的调节手段。
+
+![Image](https://pbs.twimg.com/media/HE-yvfUaQAAb-AU?format=jpg&name=large)
+
+## 到了 Agent 训练，优化的不只是模型本身了
+
+过去两年，以 o1 系列和 DeepSeek-R1 为代表的推理模型快速成型，说明在奖励稳定、验证可靠、基础设施到位的条件下，语言模型上的 RL 确实能显著提升数学、代码和逻辑任务表现。
+
+这同时打开了一个新维度：推理算力也可以扩展了。RL 训练的作用随之多了一层，它在教模型答题之外，还在教模型分配推理预算，知道什么时候多想、什么时候该停。再往前走，难点就变成让模型在环境里持续行动，而不只是把单次思考拉长。
+
+![Image](https://pbs.twimg.com/media/HE-zFtCaAAAi1La?format=jpg&name=large)
+
+Qwen 前模型负责人 Junyang Lin 对 Thinking 和 Instruct 混合路线的反思很有代表性：难点不在给模型一个思考开关，而在两种模式的目标本来就不一样，一个追求直接、合规和低延迟，另一个追求更多探索和更高正确率。再往前一步，训练目标就会从回答前想多久，转成行动里怎么分配预算、怎么接反馈、怎么继续推进任务。
+
+这时候训练对象不再只是一个会回答问题的模型，而是一个能规划、调用工具、接收反馈、在长任务里保持连贯的系统。于是训练栈也跟着变了，浏览器、终端、搜索、执行沙盒、内存系统、工具服务器、编排框架都开始进入训练系统。
+
+更准确地说，harness 是包在模型外层的控制程序，这个概念不只属于 Agent 运行时，训练阶段同样有它：决定模型看到什么输入、以什么形式接收反馈、何时裁剪上下文、何时调工具。prompt construction、memory update、retrieval policy、context editing、tool orchestration 都在这里。环境也不再只是静态验证器，而是训练和部署都要直接面对的一层。
+
+![Image](https://pbs.twimg.com/media/HE-zJsAawAAfK9E?format=jpg&name=large)
+
+harness 先稳住，模型训练才有意义。工具返回值不稳定、浏览器环境和线上不一致、文件系统状态不可复现时，grader 会先出错，模型随后学到的就不是能力，而是如何利用环境漏洞。训练 Agent 时，很多时候既在 debug 模型，也在 debug 环境。
+
+三家的做法也很清楚：Kimi 用 PARL 解决并行拆解和 credit assignment，Cursor 用 self-summarization 和 real-time RL 把长时 coding session 与生产流量重新接回训练，Chroma 则把 prune\_chunks 训成策略本身，让 context pruning 直接进入检索过程。
+
+SFT 时代数据多样性是第一位，到了 Agent 时代，环境质量才是核心：稳定性、真实性、覆盖度、难度分布、反馈丰富度和抗利用性。训练目标也随之变化，要的是在完整任务里保持可靠，不只是做对一道题，经典 CoT benchmark 覆盖不到这部分。
+
+这个变化还在继续前移：不只是在 runtime harness 里训练模型，连 harness code 本身也开始成为可以被外循环搜索和优化的对象。
+
+![Image](https://pbs.twimg.com/media/HE-zKpjawAAnwFN?format=jpg&name=large)
+
+Kimi K2.5 的 PARL 是一个很值得拆开的工程案例，路线很明确：只训练 orchestrator，把 credit assignment 收束到编排层，不在所有 sub-agent 上同时优化。
+
+奖励信号分三类，任务成功、并行分解和完成约束，一起驱动编排层。训练早期把 r\_parallel 权重拉高，鼓励先探索并行策略，后期再逐步退到 0，避免把多开 sub-agent 当成捷径。评估也不只看总步数，还看关键路径长度，关键路径变短才说明并行真的生效。
+
+![Image](https://pbs.twimg.com/media/HE-zOsgakAA9XnV?format=jpg&name=large)
+
+但到了 2026，事情又往前走了一步，Meta-Harness 明确把 harness engineering 单独拿出来优化。它优化的不是权重，而是 harness code 本身，也就是围绕固定模型的 prompt construction、retrieval、memory 与状态更新程序。论文开头的数字很直接：同一个底模，只改 harness，在同一 benchmark 上就可能拉出 6x 的性能差距，模型外层这套程序已经不只是部署细节，也是能力形成的一层。
+
+它的关键也不是再加一个抽象 optimizer，而是把 prior code、scores、execution traces（工具调用和状态变化的执行日志）全部写入 filesystem，让 proposer 像写代码一样去 grep、cat、比对 diff，再顺着失败路径改 harness。proposer 是提出 harness 修改方案的模块。
+
+作者判断得很明确，过去很多 text optimizer 对 harness 这类长时、状态化程序不够有效，核心原因是只看 scalar score、短模板或总结会把问题压扁。scalar score 只有最终得分，没有过程信息。harness 的错误常常要很多步之后才显现，反馈一旦被过度压缩，诊断链路就会断。
+
+这些结果不只是 benchmark 分数更高。在线文本分类里，Meta-Harness 比 ACE（agent 上下文工程基线）高 7.7 个点，同时把 context token 用量压到原来的 1/4。检索增强数学推理里，一个发现出来的 harness 在 200 道 IMO-level 题上，对 5 个 held-out 模型（未参与优化）平均再涨 4.7 个点。在 TerminalBench-2 上，它也超过了手工工程化 baseline。这说明被优化的已经不只是模型内部策略，也包括模型外围那层如何组织信息和行动的程序。
+
+一个具体例子：Meta-Harness 在 TerminalBench-2 上自动发现了 environment bootstrap，也就是 agent loop 开始前先跑一个 shell command，把工作目录、可用语言、包管理器和内存状态整理成快照注入首轮 prompt。很多 coding agent 前几轮其实都在探环境，这层前置做好，提升不一定来自更强权重，而是 harness 让模型一开始就站在更好的上下文上。
+
+到这里，优化目标已经从答案扩展到轨迹，再扩展到承载轨迹的 harness program。
+
+## 前沿模型发布后，训练链路还在继续跑
+
+单用一轮预训练的思路来理解今天的大模型，已经不够了。发布出去的模型背后，通常已经跑完了预训练、后训练、蒸馏、专用化这整条链路，而且更强的模型还在持续给下一代产出训练数据。
+
+DeepSeek-R1 系列的蒸馏就是很典型的例子，大模型先通过 RL 和 verified rewards 把推理能力练出来，再把这些推理轨迹迁给更小的 dense 模型。TranslateGemma 这类专用模型则展示了另一条路线：在更明确的目标任务上，用高质量数据和专门的奖励设计，把能力进一步压缩和定向。到了这一步，更强的模型已经不只是拿来服务用户，也开始直接给下一代模型产出训练数据。
+
+背后的原因比轨迹迁移更根本一些：一个可能的解释是，互联网语料里知识记忆和推理能力是耦合在一起的，现有的预训练目标要求模型同时把两件事都学好。大模型之所以要先上来，是因为只有足够大，才能同时撑起这两件事，然后再用它来生成纯推理示范数据，小模型在这类数据上训练，就可以专注在推理本身，不用再被迫把所有知识都记住；先大再小，一个关键原因是能力解耦，不只是成本策略。
+
+另一边，部署适配性和能力本身同样重要。很多场景不需要全能大模型，更关心成本、延迟、稳定性和可控性，训练的终点不一定是更大，也可能是更小、更便宜、更专门。
+
+最后发布的模型，不一定是训练曲线最右边的那个 checkpoint。实际发布前往往会在多个 checkpoint 之间反复比较真实任务结果、拒答风格、工具稳定性、成本和回归风险。最后上线的版本往往是产品决策，不是单一指标上表现最强的那个。
+
+用户看到模型名字，会以为它对应一条平滑上升的训练曲线，但真正选哪个 checkpoint 上线，那是另一回事。
+
+大模型的价值，既在它自己的服务能力，也在它会继续给下一代模型提供训练数据、蒸馏来源和发布基座。
+
+![Image](https://pbs.twimg.com/media/HE-zd99awAA5nVW?format=jpg&name=large)
+
+离线训练之外，接近在线的持续优化也已经进了主流程，Cursor Composer 2 的 real-time RL 说明一部分 Agent 能力已经开始通过生产流量持续迭代，而不是等下一轮大规模离线训练统一刷新。训练和部署之间的边界并没有消失，但两者的反馈回路正在缩短。
+
+## 以后怎么看一个模型为什么变强了
+
+2026 年前沿模型的价值，越来越看谁能把预训练后面这整套训练链路跑完整：持续产出训练数据、做蒸馏、做专用化、把评测和奖励做好、做最后的发布选择。 也因为这样，后面再看一个模型为什么突然变强，可以先看三件事：
+
+- 先看变化发生在预训练层，还是后面的训练流程。很多能力提升确实来自更强的预训练和更好的数据配方，但也有很多体感变化，其实主要出在后训练。模型会不会听指令、会不会用工具、回答风格稳不稳，常常不是多训一点语料自己长出来的。
+- 再看提升来自哪一层：是权重和训练配方，还是 reward / eval / grader，还是 harness code 和 deployment loop。到了推理模型和 Agent 这一段，用户感受到的变强，很多时候已经不是基础模型单独做出来的结果。评测怎么设、奖励怎么打、工具环境稳不稳、retrieval 和记忆怎么组织、summary 和上下文怎么剪、上线时选了哪个 checkpoint，这些都会一起改掉最后的产品表现。
+- 最后看上线版本在优化什么。有些版本是在追求更高上限，有些版本是在压成本、延迟和回归风险，还有些版本是在给某一类场景做专用化。发布版本本来就是产品决策，不是训练曲线最右边那个点，所以看模型更新时，顺手看它到底在优化什么，会更接近真实情况。
+
+把模型突然变强这件事拆回生产环节看，很多提升其实是后半段训练栈和外层 harness 一起放大的。这条链路的迭代周期也在缩短：生产流量持续回流到训练，每代更强的模型在产出能力的同时也在产出下一代监督数据，外层程序根据 rollouts、logs 和真实任务反馈不断重写。
+
+今天发布的模型只是一个快照，链路和 harness program 才是持续在跑的产品。
+
+## 学习资料
+
+1. Hoffmann et al. (2022). Training Compute-Optimal Large Language Models (Chinchilla). [arXiv:2203.15556](https://arxiv.org/abs/2203.15556)
+2. Ouyang et al. (2022). Training language models to follow instructions with human feedback (InstructGPT). [arXiv:2203.02155](https://arxiv.org/abs/2203.02155)
+3. Shao et al. (2024). DeepSeekMath: Pushing the Limits of Mathematical Reasoning in Open Language Models (GRPO). [arXiv:2402.03300](https://arxiv.org/abs/2402.03300)
+4. DeepSeek-AI (2025). DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning. [arXiv:2501.12948](https://arxiv.org/abs/2501.12948)
+5. DeepSeek-AI (2024). DeepSeek-V3 Technical Report. [arXiv:2412.19437](https://arxiv.org/abs/2412.19437)
+6. Llama Team, AI @ Meta (2024). The Llama 3 Herd of Models. [arXiv:2407.21783](https://arxiv.org/abs/2407.21783)
+7. Bai et al. (2022). Constitutional AI: Harmlessness from AI Feedback. [arXiv:2212.08073](https://arxiv.org/abs/2212.08073)
+8. OpenAI (2024). Deliberative Alignment: Reasoning Enables Safer Language Models. [openai.com/index/deliberative-alignment](https://openai.com/index/deliberative-alignment/)
+9. Anthropic (2025). Sycophancy to Subterfuge: Investigating Reward Tampering in Language Models. [anthropic.com/research/reward-tampering](https://www.anthropic.com/research/reward-tampering)
+10. MacDiarmid et al. (2025). Natural Emergent Misalignment from Reward Hacking in Production RL. [arXiv:2511.18397](https://arxiv.org/abs/2511.18397)
+11. Lee et al. (2026). Meta-Harness: End-to-End Optimization of Model Harnesses (preprint project page). [yoonholee.com/meta-harness](https://yoonholee.com/meta-harness/)
+12. Kimi Team (2026). Kimi K2.5 Tech Blog: Visual Agentic Intelligence. [kimi.com/blog/kimi-k2-5](https://www.kimi.com/blog/kimi-k2-5)
+13. Rush, S. (2026). A technical report on Composer 2. [cursor.com/blog/composer-2-technical-report](https://cursor.com/blog/composer-2-technical-report)
+14. Chroma (2026). Chroma Context-1: Training a Self-Editing Search Agent. [trychroma.com/research/context-1](https://www.trychroma.com/research/context-1)
+
+本文不授权任何方式的转载，洗稿再发布，如大伙发现，欢迎去帮我举报。

2 - Projects/Smart Support.md

@@ -1,8 +1,8 @@
 ---
 created: 2026-03-29
-updated: 2026-04-06
+updated: 2026-04-07
 type: project
-status: completed
+status: active
 deadline: ""
 tags:
   - ai-agent
@@ -48,11 +48,14 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 | 检查点 | langgraph-checkpoint-postgres | PostgreSQL 持久化 |
 | MCP | langchain-mcp-adapters | MultiServerMCPClient |
 | 数据库 | PostgreSQL 16 | Docker Compose 部署 |
-| LLM | Claude Sonnet 4.6（默认） | 支持 Anthropic/OpenAI/Google 切换 |
+| DB 迁移 | Alembic | 自动运行 migrations |
+| LLM | Claude Sonnet 4.6（默认） | 支持 Anthropic/OpenAI/Azure/Google 切换 |
 | 前端 | React 19 + TypeScript + Vite 6 | React Router 7.x |
-| 测试 | pytest 8.3+ / vitest 4.1.2 | 后端 516 测试 92%+ 覆盖率 |
+| 测试 | pytest 8.3+ / vitest 4.1.2 | 后端 516+ 测试 94%+ 覆盖率 |
 | 部署 | Docker Compose | PostgreSQL + FastAPI + nginx |
+| 日志 | structlog | 结构化日志（console/json 模式） |
 | 代码质量 | ruff 0.9+ | Python linting + formatting |
+| 认证 | API Key | `X-API-Key` header / `?token=` for WS |
 
 ## 核心特性
 
@@ -76,14 +79,15 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 | Phase 3 | 第 4-6 周 | OpenAPI 自动发现 | COMPLETED (2026-03-30) | [[Smart Support/Phase 3 - OpenAPI 自动发现]] |
 | Phase 4 | 第 6-7 周 | 分析 + 回放 | COMPLETED (2026-03-31) | [[Smart Support/Phase 4 - 分析 + 回放]] |
 | Phase 5 | 缓冲周 | 打磨 + 演示 | COMPLETED (2026-03-31) | [[Smart Support/Phase 5 - 打磨 + 演示]] |
+| Post | 2026-04 | 架构修复 + 工程改进 | 进行中 | API v1 版本化、structlog、Alembic、认证、GraphContext/WebSocketContext |
 
 ## 项目数据
 
-- 后端测试：516 个（单元 ~400 + 集成 ~7 + E2E ~3）
+- 后端测试：516+ 个（单元 ~439 + 集成 ~51 + E2E ~26）
 - 前端测试：~23 个（vitest + happy-dom）
-- 代码覆盖率：92.88%
-- 应用版本：v0.5.0
-- Git 最新提交：`af53111` refactor: fix architectural issues
+- 代码覆盖率：~94%
+- 应用版本：v0.6.0
+- Git 最新提交：`f069943` refactor: engineering improvements -- API versioning, structured logging, Alembic, error standardization
 
 ## 目标用户
 
@@ -99,28 +103,36 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 
 客户端 -> 服务器：
 - `{"type": "message", "thread_id": "...", "content": "..."}`
-- `{"type": "interrupt_response", "thread_id": "...", "interrupt_id": "...", "approved": true/false}`
+- `{"type": "interrupt_response", "thread_id": "...", "approved": true/false}`
 
-服务器 -> 客户端：
-- `{"type": "token", "thread_id": "...", "content": "..."}` -- 流式 token
-- `{"type": "interrupt", ...}` -- 人工确认提示（含 TTL）
-- `{"type": "tool_call", ...}` / `{"type": "tool_result", ...}` -- 工具调用
-- `{"type": "message_complete", ...}` -- 消息完成
-- `{"type": "error", ...}` -- 错误
+服务器 -> 客户端（8 种消息类型）：
+- `{"type": "token", "agent": "...", "content": "..."}` -- 流式 token
+- `{"type": "interrupt", "thread_id": "...", "action": "...", "params": {...}}` -- 人工确认提示
+- `{"type": "clarification", "thread_id": "...", "message": "..."}` -- 意图模糊，请求澄清
+- `{"type": "interrupt_expired", "thread_id": "...", "action": "...", "message": "..."}` -- 审批超时
+- `{"type": "tool_call", "agent": "...", "tool": "...", "args": {...}}` -- 工具调用
+- `{"type": "tool_result", "agent": "...", "tool": "...", "result": ...}` -- 工具返回
+- `{"type": "message_complete", "thread_id": "..."}` -- 消息完成
+- `{"type": "error", "message": "..."}` -- 错误
+
+WebSocket 连接需 `?token=<ADMIN_API_KEY>` 认证（未配置 key 时跳过）。
 
 ## REST API
 
-| 方法 | 路径 | 说明 |
-|------|------|------|
-| WS | `/ws` | WebSocket 聊天 |
-| GET | `/api/health` | 健康检查 |
-| GET | `/api/conversations` | 对话列表（分页） |
-| GET | `/api/replay/{thread_id}` | 回放时间线（分页，默认 20 步） |
-| GET | `/api/analytics?range=7d` | 分析摘要（1d/7d/30d/90d） |
-| POST | `/api/openapi/import` | 开始 OpenAPI 导入 |
-| GET | `/api/openapi/jobs/{id}` | 导入任务状态 |
-| PUT | `/api/openapi/jobs/{id}/classifications/{idx}` | 修改端点分类 |
-| POST | `/api/openapi/jobs/{id}/approve` | 审核通过，生成工具 |
+所有端点使用 `/api/v1/` 前缀。管理端点需 `X-API-Key` header（`ADMIN_API_KEY` 未配置时跳过认证）。
+
+| 方法 | 路径 | 认证 | 说明 |
+|------|------|------|------|
+| WS | `/ws` | Token | WebSocket 聊天（`?token=<key>`） |
+| GET | `/api/v1/health` | 无 | 健康检查 |
+| GET | `/api/v1/conversations` | API Key | 对话列表（分页） |
+| GET | `/api/v1/replay/{thread_id}` | API Key | 回放时间线（分页） |
+| GET | `/api/v1/analytics?range=7d` | API Key | 分析摘要 |
+| POST | `/api/v1/openapi/import` | API Key | 开始 OpenAPI 导入 |
+| GET | `/api/v1/openapi/jobs/{id}` | API Key | 导入任务状态 |
+| GET | `/api/v1/openapi/jobs/{id}/classifications` | API Key | 获取端点分类 |
+| PUT | `/api/v1/openapi/jobs/{id}/classifications/{idx}` | API Key | 修改端点分类 |
+| POST | `/api/v1/openapi/jobs/{id}/approve` | API Key | 审核通过，生成工具代码 + Agent YAML |
 
 ## 数据库表
 
@@ -129,9 +141,12 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 | checkpoints | LangGraph 状态快照（自动管理） |
 | checkpoint_writes | 检查点写入记录 |
 | conversations | 对话元数据（状态、解决类型、使用 Agent、Token、成本） |
-| interrupts | 人工确认记录（pending/approved/rejected/expired） |
+| active_interrupts | 人工确认记录（interrupt_id, action, params, resolved_at） |
+| sessions | 会话状态持久化（last_activity, has_pending_interrupt），供 PgSessionManager 使用 |
 | analytics_events | 分析事件流（事件类型、Agent、工具、Token、成本、耗时） |
 
+数据库迁移通过 Alembic 管理，应用启动时自动执行 `run_alembic_migrations()`。
+
 ## 架构决策（ADR）
 
 | ADR | 决策 | 理由 |
@@ -166,26 +181,39 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
 
 ```
 backend/app/
-  main.py              -- FastAPI 入口 (v0.5.0)
-  config.py            -- Pydantic Settings
-  db.py                -- AsyncPostgreSQL + AsyncPostgresSaver
-  llm.py               -- LLM 提供商工厂（Anthropic/OpenAI/Google）
-  graph.py             -- LangGraph Supervisor 构建
+  main.py              -- FastAPI 入口 (v0.6.0), 全局异常处理, 中断清理循环
+  config.py            -- Pydantic Settings（含 admin_api_key, log_format）
+  db.py                -- AsyncPostgreSQL + AsyncPostgresSaver + Alembic runner
+  llm.py               -- LLM 提供商工厂（Anthropic/OpenAI/Azure/Google）
+  graph.py             -- LangGraph Supervisor 构建，返回 GraphContext
+  graph_context.py     -- GraphContext: 图 + 分类器 + 注册表的类型化封装
   ws_handler.py        -- WebSocket 消息分发 + 流式 + 速率限制
+  ws_context.py        -- WebSocketContext: WS 处理依赖打包
+  auth.py              -- API Key 认证中间件（X-API-Key / ?token= for WS）
+  api_utils.py         -- 共享 envelope() 响应格式
+  logging_config.py    -- structlog 配置（console/json）
   registry.py          -- YAML Agent 注册表 + 模板支持
   intent.py            -- LLM 意图分类器
-  session_manager.py   -- Session TTL（30m 滑动窗口）
-  interrupt_manager.py -- 中断 TTL 追踪 + 自动取消
+  session_manager.py   -- Session TTL（30m 滑动窗口）+ PgSessionManager
+  interrupt_manager.py -- 中断 TTL 追踪 + 自动取消 + PgInterruptManager
   escalation.py        -- Webhook 升级（指数退避）
   conversation_tracker.py -- 对话生命周期追踪
   callbacks.py         -- Token 用量回调
+  safety.py            -- 确认策略规则 + MCP 错误分类
   agents/              -- Agent 定义（order_lookup, order_actions, discount, fallback）
-  openapi/             -- OpenAPI 解析 + 分类 + 生成（ssrf, fetcher, parser, classifier, generator）
+  openapi/             -- OpenAPI 解析 + 分类 + 生成（ssrf, fetcher, parser, classifier, generator, review_api）
   replay/              -- 回放模型 + 转换器 + API
   analytics/           -- 分析模型 + 事件记录 + 查询 + API
-  tools/               -- 错误处理（ErrorCategory, classify_error, with_retry）
 ```
 
+### 架构模式
+
+- **Protocol 接口**：所有跨模块边界使用 Protocol（SessionManagerProtocol, InterruptManagerProtocol 等）
+- **Frozen dataclasses**：GraphContext, WebSocketContext, SessionState, InterruptRecord 等全部不可变
+- **Composition Root**：main.py lifespan() 统一组装所有依赖
+- **Envelope 响应**：`{"success": bool, "data": T, "error": str | null}` 统一格式
+- **双实现状态管理**：内存版（开发）+ PostgreSQL 版（生产多 Worker）
+
 ## 计划文档
 
 项目根目录下：
@@ -235,12 +263,18 @@ cd ../frontend && npm test
 
 ## 已知技术债务
 
-- [ ] 认证/授权系统（生产部署前）
+- [x] ~~认证/授权系统~~ -- 已实现 API Key 认证（`auth.py`，`ADMIN_API_KEY`）
+- [x] ~~中断清理未定时调度~~ -- 已实现 `_interrupt_cleanup_loop` 后台任务（60s 间隔）
+- [x] ~~猴子补丁~~ -- 已替换为 GraphContext 类型化封装
+- [x] ~~dispatch_message 参数膨胀~~ -- 已替换为 WebSocketContext
+- [x] ~~_envelope 重复定义~~ -- 已提取到 api_utils.py
+- [x] ~~前端缺失消息类型~~ -- 已添加 clarification/interrupt_expired/tool_result 处理
 - [ ] 多租户架构（第一个付费客户后）
 - [ ] CI/CD 流水线（原型阶段手动部署）
 - [ ] 速率限制进程全局状态 -- 多 Worker 需 Redis
-- [ ] 中断清理未定时调度（cleanup_expired 存在但未触发）
-- [ ] NoOpAnalyticsRecorder 已注册 -- PostgresAnalyticsRecorder 集成待完善
+- [ ] 生产环境切换到 PgSessionManager/PgInterruptManager
+- [ ] OpenAPI approve 后的工具尚未运行时注入到 _TOOL_MAP（仅生成代码 + YAML）
+- [ ] SSRF DNS 重绑定 TOCTOU 窗口（实践中利用难度大）
 - [ ] SaaS/Fintech 模板工具仅为桩（无实现）
 - [ ] 工具生成基于字符串模板 -- 复杂场景可能需 AST
 

4 - Resources/Claude-Code/ECC 编排替代方案 (orchestrate 迁移).md

@@ -1,7 +1,8 @@
 ---
 created: "2026-04-06"
+updated: "2026-04-14"
 type: resource
-tags: [resource, claude-code, AI-tools, orchestrate, migration, feature-dev, GSD, ECC, windows-compatible]
+tags: [resource, claude-code, AI-tools, orchestrate, migration, feature-dev, GSD, PRP, devfleet, ECC, windows-compatible]
 source: "https://github.com/affaan-m/everything-claude-code"
 ---
 
@@ -9,6 +10,8 @@ source: "https://github.com/affaan-m/everything-claude-code"
 
 `/ecc:orchestrate` 已标记为 legacy shim。底层委托给 `dmux-workflows`（需 tmux）和 `autonomous-agent-harness`（部分依赖 tmux）。Windows 上基本不可用。本文档记录迁移路径。
 
+> **先看决策表**：见文末「一张表选编排方式」。
+
 相关笔记：[[Autonomous Agent Harness 自主代理框架]]、[[Everything Claude Code 完整指南]]
 
 ## orchestrate 做了什么
@@ -63,7 +66,102 @@ source: "https://github.com/affaan-m/everything-claude-code"
 | 安全相关 | 任何组合 + `/ecc:security-review` |
 | 最终验证 | `/ecc:verify` |
 
-### 路线 C：全项目多阶段 — GSD
+### 路线 C：PRP 工作流（PRD → 实施 → 提交 → PR）
+
+**适合结构化 PRD/migration-plan 等带 Implementation Phases 的文档。** 一条龙自动走完：
+
+```
+/prp-plan <feature 描述 | path/to/prd.md>   # 解析 PRD 找到下一个 pending phase，产出完整实施计划
+/prp-implement <上一步生成的 plan 路径>       # 按计划严格实施 + 验证循环
+/prp-commit                                  # 分析变更，起草 conventional commit
+/prp-pr                                      # 汇总提交生成 PR
+```
+
+特点：
+- `/prp-plan` 自动检测输入：PRD 文件 → 选下一个 pending phase；自由描述 → 直接规划
+- 黄金原则：把实施时可能要搜的所有模式/惯例**提前抓进 plan**，实施阶段不再回去搜
+- Windows 原生可用
+
+### 路线 D：多模型协同 — `/multi-workflow`
+
+**Claude 编排 + Codex 后端 + Gemini 前端 的 6 阶段流水线。** 适合全栈功能。
+
+```
+/multi-workflow "add real-time notifications when market resolves"
+```
+
+6 阶段：Research → Ideation → Plan → Execute → Optimize → Review。每阶段通过 `~/.claude/bin/codeagent-wrapper` 并行调用 Codex/Gemini（`run_in_background: true`），用 `TaskOutput` 等结果。外部模型**无文件写权限**，所有修改由 Claude 落盘。
+
+变体：`/multi-plan`（只规划）、`/multi-backend`、`/multi-frontend`、`/multi-execute`。
+
+### 路线 E：DAG 式并行多 agent — `claude-devfleet`
+
+**用独立 git worktree 跑多个 Claude Code agent，按 DAG 依赖自动调度，Windows 原生可用。** 需本地启 DevFleet 服务并通过 MCP 接入：
+
+```bash
+claude mcp add devfleet --transport http http://localhost:18801/mcp
+```
+
+核心调用（通过 MCP tool）：
+
+```
+plan_project(prompt="Build a REST API with auth and tests")
+  → 返回 project_id + 一系列 missions（含 depends_on 链、auto_dispatch=true）
+dispatch_mission(mission_id=<root>)
+  → 根 mission 启动，后续 mission 在依赖满足时自动派发
+get_mission_status / get_dashboard / get_report
+  → 监控与汇报
+```
+
+特点：
+- 每个 mission 在独立 worktree 中运行，完成后自动 merge
+- 默认最多 3 个并发 agent（`DEVFLEET_MAX_AGENTS` 可配）
+- 合并冲突时留在 worker 分支手动处理
+- 长任务建议用 `get_mission_status` 轮询（30-60 秒间隔），避免用 `wait_for_mission` 阻塞会话
+
+### 路线 F：会话内并行 — Agent 工具 + worktree 隔离
+
+**当前会话里直接 spawn 多个子代理，`isolation: "worktree"` 参数自动建临时 worktree，Windows 原生可用。** 不需要 tmux、不需要外部服务。
+
+主代理调用示例（Claude 自身能用）：
+
+```
+并行 3 个子 agent：
+- subagent_type: general-purpose, isolation: worktree, prompt: "迁移 module X"
+- subagent_type: general-purpose, isolation: worktree, prompt: "迁移 module Y"
+- subagent_type: csharp-reviewer, prompt: "审查 module X/Y 结果"
+```
+
+适合：互相独立的迁移任务、并行审查、互不冲突的多模块改造。不适合：跨模块强耦合、需要相互看到中间状态的任务。
+
+### 路线 G：外部 tmux + worktree 脚本 — `scripts/orchestrate-worktrees.js`
+
+**ECC 自带的长周期/跨 harness 编排助手。需要 tmux（Linux/macOS/WSL）。**
+
+```bash
+node scripts/orchestrate-worktrees.js plan.json --execute
+```
+
+`plan.json` 结构：
+
+```json
+{
+  "sessionName": "skill-audit",
+  "baseRef": "HEAD",
+  "seedPaths": ["scripts/helper.js", ".claude/plan/spec.md"],
+  "launcherCommand": "codex exec --cwd {worktree_path} --task-file {task_file}",
+  "workers": [
+    {"name": "docs-a", "task": "Fix skills 1-4."},
+    {"name": "docs-b", "task": "Fix skills 5-8."}
+  ]
+}
+```
+
+自动完成：每 worker 一个分支+worktree、覆盖 `seedPaths` 中的本地脏文件、写 `.orchestration/<session>/` 下的 task/handoff/status 文件、启动 tmux 会话挂 panes。
+
+状态快照：`node scripts/orchestration-status.js <plan.json>`。
+
+### 路线 H：全项目多阶段 — GSD
 
 GSD（Get Shit Done）是 ECC 集成的项目级编排系统，Windows 原生可用。
 
@@ -104,13 +202,15 @@ npx get-shit-done-cc@latest
 ## 迁移对照表
 
 | 旧命令                                | 新命令                                           | 说明                       |
-|--------|--------|------|
-| `/ecc:orchestrate feature "desc"` | `/ecc:feature-dev "desc"` | 单功能全流程 |
+| ---------------------------------- | --------------------------------------------- | ------------------------ |
+| `/ecc:orchestrate feature "desc"`  | `/ecc:feature-dev "desc"` 或 `/prp-plan`+`/prp-implement` | 单功能全流程         |
 | `/ecc:orchestrate bugfix "desc"`   | `/ecc:tdd` + `/ecc:code-review`               | 先写失败测试再修                 |
 | `/ecc:orchestrate refactor "desc"` | `/ecc:plan` + `/ecc:tdd` + `/ecc:code-review` | 先规划再重构                   |
 | `/ecc:orchestrate security "desc"` | 任何路线 + `/ecc:security-review`                 | 加安全审查                    |
 | 多阶段自动执行                            | `/gsd:autonomous`                             | GSD 接管                   |
-| 并行编排 | 不可用（Windows） | 用 Agent/Task tool 做进程内并行 |
+| 并行编排（tmux）                         | `claude-devfleet` MCP 或 Agent+worktree        | Windows 原生替代             |
+| PRD → 实施                           | `/prp-plan <prd.md>` → `/prp-implement`       | 自动解析 phases              |
+| 多模型协同                              | `/multi-workflow`                             | Codex+Gemini+Claude     |
 
 ## CLAUDE.md 更新
 
@@ -138,13 +238,35 @@ npx get-shit-done-cc@latest
 |------|---------|------|
 | `/ecc:feature-dev` | 可用 | Claude Code 内部，不依赖外部工具 |
 | `/ecc:plan` + `/ecc:tdd` + ... | 可用 | 同上 |
+| `/prp-plan` / `/prp-implement` / `/prp-commit` / `/prp-pr` | 可用 | 全部 Claude Code 内部 |
+| `/multi-workflow` (含 Codex/Gemini) | 可用 | 需装 codeagent-wrapper，不依赖 tmux |
 | `/gsd:autonomous` | 可用 | 用 Claude Code Task tool 做并行 |
+| Agent 工具 + `isolation: "worktree"` | 可用 | 原生 git worktree，不依赖 tmux |
+| `claude-devfleet` (MCP) | 可用 | HTTP MCP 接入，worker 在独立 worktree |
 | `/ecc:orchestrate` | **不可用** | Legacy，底层依赖 tmux |
-| `dmux-workflows` | **不可用** | 需要 tmux |
+| `dmux-workflows` | **不可用** | 需要 tmux（除非 WSL） |
+| `scripts/orchestrate-worktrees.js` | **WSL 可用** | 建 tmux session 挂 panes |
 | `auto-pilot.sh` 脚本 | 可用 | Git Bash，每阶段独立 `claude -p` |
 
 ---
 
+## 一张表选编排方式
+
+| 我要... | 选 | 入口 |
+|---------|-----|------|
+| 规划单个功能，确认后再写 | `/plan` | 命令 |
+| 单功能全流程（含 TDD+审查） | `/ecc:feature-dev` | 命令 |
+| 已有 PRD/migration-plan 带 phases | `/prp-plan <path>` → `/prp-implement` | 命令 |
+| 前后端都动（Codex/Gemini 辅助） | `/multi-workflow` | 命令 |
+| 会话内并行几个独立任务 | Agent 工具 + `isolation: worktree` | 主代理直接 spawn |
+| DAG 调度多 worker 自动合并 | `claude-devfleet` | MCP |
+| 整个项目/多 milestone 生命周期 | `/gsd:new-project` → `/gsd:autonomous` | 命令 |
+| 无人值守长时间跑 | `autonomous-agent-harness` + crons | MCP scheduled-tasks |
+| 定时重复同一个任务 | `/loop-start <interval> <prompt>` | 命令 |
+| 跨 harness 长周期编排（Linux/WSL） | `scripts/orchestrate-worktrees.js` | 脚本 |
+
+---
+
 ## 什么时候需要外部脚本
 
 大部分情况下 Claude Code 自己编排（`/ecc:feature-dev` 或 GSD）就够了。外部脚本（`auto-pilot.sh`）只在以下场景有价值：

4 - Resources/Claude-Code/Everything Claude Code 完整指南.md

@@ -1,5 +1,6 @@
 ---
 created: "2026-03-08 21:30"
+updated: "2026-04-14"
 type: resource
 tags: [resource, claude-code, AI-tools, development-workflow, reference]
 source: "https://github.com/affaan-m/everything-claude-code"
@@ -7,24 +8,35 @@ source: "https://github.com/affaan-m/everything-claude-code"
 
 # Everything Claude Code 完整指南
 
-生产级 Claude Code 插件系统。v1.10.0 (2026-04-06 更新)，包含 215 skills、112 agents、82 commands、hooks 和 rules (608 files total)。方法论与最佳实践见 [[Everything Claude Code 方法论与最佳实践]]，按场景速查见 [[Everything Claude Code 用法速查]]。
+生产级 Claude Code 插件系统。v1.10.0（本地仓库实测 183 skills / 48 agents / 79 commands；marketplace 版可能更多——以本地 `ls` 结果为准）。方法论与最佳实践见 [[Everything Claude Code 方法论与最佳实践]]，按场景速查见 [[Everything Claude Code 用法速查]]。
+
+> **仓库关键参考文档**（实测路径 `C:\Users\yaoji\git\OpenSource\everything-claude-code\`）：
+> - `docs/COMMAND-AGENT-MAP.md` — 命令↔agent↔skill 的官方对照表
+> - `COMMANDS-QUICK-REF.md` — 59 命令速查（按作者口径）
+> - `the-longform-guide.md` / `the-shortform-guide.md` — 官方长/短指南
+> - `skills/dmux-workflows/SKILL.md`、`skills/autonomous-agent-harness/SKILL.md`、`skills/claude-devfleet/SKILL.md` — 三类编排机制
+> - `scripts/orchestrate-worktrees.js` — 外部 tmux+worktree 编排脚本
 
 自主循环和并行编排详见：[[Autonomous Loops 自主循环模式]]、[[dmux 多Agent并行编排]]、[[Ralphinho RFC-DAG 编排模式]]、[[Autonomous Agent Harness 自主代理框架]]、[[ECC 编排替代方案 (orchestrate 迁移)]]
 
 ## 项目架构
 
 ```
-everything-claude-code/ (v1.10.0, 608 files)
-├── agents/     (112个) - 专用子代理 (.agents/ + agents/)
-├── skills/     (215个) - 工作流定义和领域知识
-├── commands/   (82个)  - slash 命令
-├── hooks/      - 基于事件的自动化
-├── rules/      - 始终遵循的规则（15种语言 + common）
-├── scripts/    (93个) - 跨平台 Node.js 工具脚本
+everything-claude-code/ (v1.10.0)
+├── agents/     (~48) - 专用子代理（code-reviewer、planner、tdd-guide、...）
+├── skills/     (~183) - 工作流定义和领域知识
+├── commands/   (~79) - slash 命令
+├── hooks/      - 基于事件的自动化（hooks.json + scripts/hooks/*）
+├── rules/      - 始终遵循的规则（python/typescript/golang/... + common + zh）
+├── scripts/    - 跨平台 Node.js 工具脚本（orchestrate-worktrees、harness-audit、...）
 ├── mcp-configs/- MCP 服务器配置模板
-└── contexts/   - 动态注入的上下文文件
+├── contexts/   - 动态注入的上下文文件
+├── docs/       - COMMAND-AGENT-MAP、SKILL-PLACEMENT-POLICY 等
+└── plugins/    - 独立子插件（gsd、obsidian、planning-with-files、...）
 ```
 
+> 数字随版本浮动，以 `ls commands/*.md | wc -l` 等实测为准。
+
 ## 安装
 
 ```bash
@@ -85,7 +97,21 @@ Rules 新增：java, kotlin, dart, csharp, cpp, rust, perl, php, web, zh (中文
 
 ---
 
-## 全部 65 Skills
+## 精选 Skills（curated subset，非全量）
+
+> 实际 skills 总数 ~183（v1.10.0）。以下只列最常用的按领域分组。完整清单：`ls skills/` 或看 `docs/COMMAND-AGENT-MAP.md`。
+
+### 编排三件套（本文档重点）
+
+| Skill | 用途 | Windows 可用 |
+|-------|------|--------------|
+| `dmux-workflows` | tmux pane 多 agent 并行 | ❌（需 WSL） |
+| `autonomous-agent-harness` | 自主循环 / 定时 / 持久记忆 | ✅ |
+| `claude-devfleet` | DAG 式多 worker + 独立 worktree + 自动 merge | ✅（需本地 DevFleet MCP） |
+
+其它相关：`autonomous-loops`、`continuous-agent-loop`、`ralphinho-rfc-pipeline`、`council`、`gan-style-harness`。
+
+
 
 ### 核心基础设施 (9)
 
@@ -229,7 +255,11 @@ Rules 新增：java, kotlin, dart, csharp, cpp, rust, perl, php, web, zh (中文
 
 ---
 
-## 16 Agents
+## 精选 Agents（非全量）
+
+> 实际 agents 总数 ~48。以下是最常被命令调用或主代理手动 spawn 的核心子代理。完整清单：`ls agents/` 或看 `docs/COMMAND-AGENT-MAP.md`。
+
+
 
 | Agent                  | 职责                |
 | ---------------------- | ----------------- |
@@ -255,16 +285,22 @@ Rules 新增：java, kotlin, dart, csharp, cpp, rust, perl, php, web, zh (中文
 ## 常用 Commands
 
 ### 开发核心
-`/plan` `/tdd` `/e2e` `/code-review` `/build-fix` `/verify` `/test-coverage` `/refactor-clean`
+`/plan` `/tdd` `/e2e` `/code-review` `/build-fix` `/verify` `/test-coverage` `/refactor-clean` `/feature-dev`
+
+### PRP 工作流（PRD→实施→PR 一条龙）
+`/prp-prd` `/prp-plan` `/prp-implement` `/prp-commit` `/prp-pr`
 
 ### 多 Agent 编排
-`/multi-plan` `/multi-execute` `/multi-frontend` `/multi-backend` `/orchestrate`
+`/multi-plan` `/multi-workflow` `/multi-execute` `/multi-frontend` `/multi-backend` `/devfleet` `/orchestrate`（legacy shim）
+
+### GSD 项目生命周期（独立子插件）
+`/gsd:new-project` `/gsd:plan-phase` `/gsd:execute-phase` `/gsd:verify-work` `/gsd:next` `/gsd:autonomous` `/gsd:ship` `/gsd:complete-milestone`
 
 ### 学习演化
-`/learn` `/learn-eval` `/evolve` `/instinct-status` `/instinct-export` `/instinct-import`
+`/learn` `/learn-eval` `/evolve` `/instinct-status` `/instinct-export` `/instinct-import` `/skill-create` `/skill-health` `/rules-distill`
 
-### v1.8.0 新增
-`/loop-start` `/loop-status` `/model-route` `/quality-gate` `/harness-audit` `/promote`
+### 循环/自动化
+`/loop-start` `/loop-status` `/model-route` `/quality-gate` `/harness-audit` `/promote` `/claw`
 
 ---
 
@@ -303,9 +339,12 @@ ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
 ### Resources
 - [[Everything Claude Code 方法论与最佳实践]]
 - [[Everything Claude Code 用法速查]]
+- [[ECC 编排替代方案 (orchestrate 迁移)]] ← **编排机制全景表**
 - [[Autonomous Loops 自主循环模式]]
+- [[Autonomous Agent Harness 自主代理框架]]
 - [[dmux 多Agent并行编排]]
 - [[Ralphinho RFC-DAG 编排模式]]
+- [[GSD 方法论与最佳实践]]
 
 ### Zettelkasten
 - [[Everything Claude Code 最佳实践]]

6 - Zettelkasten/20260414230719 Agent 工具 worktree 隔离是 Windows 原生并行的关键.md

@@ -0,0 +1,53 @@
+---
+created: "2026-04-14 23:07"
+type: zettel
+tags: [zettel, claude-code, ECC, orchestration, parallel, windows, worktree]
+source: "Claude Code Agent tool 参数: isolation"
+---
+
+# Agent 工具 worktree 隔离是 Windows 原生并行的关键
+
+ECC 的 `dmux-workflows`、`scripts/orchestrate-worktrees.js` 都依赖 tmux，Windows 原生环境跑不了。绕过这个限制最干净的方案不是切 WSL，是用 Claude Code 内置 `Agent` 工具的 `isolation: "worktree"` 参数。
+
+## 机制
+
+`Agent` 工具在 spawn 子代理时接受 `isolation: "worktree"`——平台会自动为该子代理建一个临时 git worktree，子代理在隔离分支上做修改，无改动时自动清理，有改动则把 path 和 branch 返还给主代理，由主代理决定合并还是丢弃。
+
+这和 `claude-devfleet` 的 worktree 策略本质一致，只是调度层从 HTTP MCP 变成主代理自己。
+
+## 为什么重要
+
+1. **零外部依赖** — 不需要 tmux、不需要额外服务，Claude Code 开箱即用
+2. **天然隔离** — git worktree 保证多个子代理改同一个仓库也不会互相踩脚
+3. **失败可丢弃** — 改坏了直接扔掉 worktree，主会话干净无污染
+4. **和现有 agent 生态复用** — 任何 `subagent_type`（general-purpose、csharp-reviewer、security-reviewer……）都能套 worktree
+
+## 适用边界
+
+- ✅ 互相独立的迁移任务、并行审查、多模块改造
+- ✅ 想在 Windows 上复刻 dmux 「多 pane 并行」效果
+- ❌ 跨模块强耦合、子代理需要实时看到彼此中间状态
+- ❌ 需要长时间运行、跨会话存活（用 `claude-devfleet` 或 `autonomous-agent-harness` crons）
+
+## 和其他编排方式的关系
+
+| 需求 | 用这个 |
+|------|--------|
+| 几个独立子任务，当前会话内搞定 | **Agent + isolation: worktree**（本 zettel） |
+| DAG 依赖、跨会话、自动 merge | `claude-devfleet`（MCP） |
+| Linux/WSL 上可视化多 pane | `dmux-workflows` |
+| 定时 / 长周期无人值守 | `autonomous-agent-harness` + crons |
+
+---
+
+## Related
+
+- [[ECC 编排替代方案 (orchestrate 迁移)]]
+- [[dmux 多Agent并行编排]]
+- [[Autonomous Agent Harness 自主代理框架]]
+- [[Everything Claude Code Agent 编排模式]]
+
+## Source
+
+- Claude Code `Agent` tool 原生参数 `isolation`
+- ECC `skills/claude-devfleet/SKILL.md` 的 worktree 隔离策略（同源思路）