Compare commits
7 Commits
e4cee2f21d
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
|
8e74b9efd0 | ||
|
|
e3d669818c | ||
|
|
0b2068d0e8 | ||
|
|
949863408c | ||
|
|
998df02055 | ||
|
|
ab3263c474 | ||
|
|
7ab3575374 |
3
.obsidian/community-plugins.json
vendored
3
.obsidian/community-plugins.json
vendored
@@ -1,5 +1,6 @@
|
|||||||
[
|
[
|
||||||
"obsidian-checklist-plugin",
|
"obsidian-checklist-plugin",
|
||||||
"calendar",
|
"calendar",
|
||||||
"obsidian-git"
|
"obsidian-git",
|
||||||
|
"terminal"
|
||||||
]
|
]
|
||||||
2
.obsidian/plugins/obsidian-git/data.json
vendored
2
.obsidian/plugins/obsidian-git/data.json
vendored
@@ -8,7 +8,7 @@
|
|||||||
"autoPullInterval": 0,
|
"autoPullInterval": 0,
|
||||||
"autoPullOnBoot": true,
|
"autoPullOnBoot": true,
|
||||||
"autoCommitOnlyStaged": false,
|
"autoCommitOnlyStaged": false,
|
||||||
"disablePush": false,
|
"disablePush": true,
|
||||||
"pullBeforePush": true,
|
"pullBeforePush": true,
|
||||||
"disablePopups": false,
|
"disablePopups": false,
|
||||||
"showErrorNotices": true,
|
"showErrorNotices": true,
|
||||||
|
|||||||
168
.obsidian/plugins/terminal/data.json
vendored
Normal file
168
.obsidian/plugins/terminal/data.json
vendored
Normal file
@@ -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
|
||||||
|
}
|
||||||
|
}
|
||||||
306
.obsidian/plugins/terminal/main.js
vendored
Normal file
306
.obsidian/plugins/terminal/main.js
vendored
Normal file
File diff suppressed because one or more lines are too long
14
.obsidian/plugins/terminal/manifest.json
vendored
Normal file
14
.obsidian/plugins/terminal/manifest.json
vendored
Normal file
@@ -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"
|
||||||
|
}
|
||||||
32
.obsidian/plugins/terminal/styles.css
vendored
Normal file
32
.obsidian/plugins/terminal/styles.css
vendored
Normal file
@@ -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))))}
|
||||||
251
1 - Inbox/你不知道的大模型训练：原理、路径与新实践.md
Normal file
251
1 - Inbox/你不知道的大模型训练：原理、路径与新实践.md
Normal file
@@ -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 年的模型能力和产业价值，也越来越集中在预训练后面的几层。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
这也是我们平时为啥感觉豆包不太去争排名，但大家日常用起来却更符合心意的原因，是后训练做到位了。
|
||||||
|
|
||||||
|
这六层只是为了看分工，下图的九个阶段是更详细的版本：原始数据和系统配方单独拆开，Agent harness 和 Deployment 也是后半段的细分。还有两条反馈回路贯穿始终：生产流量回到数据工程，离线评测结果回到预训练。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 预训练只是模型底座
|
||||||
|
|
||||||
|
预训练仍然是训练链路的起点，搞清楚它到底在做什么，才能理解后面的每一层都在补充什么。没有这一步，就没有语言建模能力，没有知识压缩，也没有后面那些能力迁移的空间。在工程上，它要做的不只是让模型学会预测下一个 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（浮点运算次数）比看参数量更靠谱，下图直观展示了这个差距。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
还有一类容易被忽略的设计也发生在预训练阶段：tokenizer 词表大小、分词策略、字节级编码方式都会有挺大影响。Llama2 词表 32K，Llama3 扩到 128K 后，序列长度大约压缩了 15%，下游性能也会跟着上去，这个影响会延续到推理成本和多语言能力。中文、代码、数学公式的 token 效率在词表设计时就已经定下来了。比如一个把中文分得很碎的 tokenizer，劣势并不是每次多花几个 token，而是每次推理都要持续承担这个决策错误的代价。
|
||||||
|
|
||||||
|
## 数据配方决定模型能力
|
||||||
|
|
||||||
|
参数规模是过去几年大家比较的重要指标，但这两年更重要的东西叫「数据配方」。
|
||||||
|
|
||||||
|
这个过程表面看是清洗数据，实际上是完整的数据生产工程。网页、代码仓库、书籍、论坛这些原始数据，要先走完文本抽取、语言识别、质量过滤、隐私处理、安全过滤和去重，才能进入预训练，下图展示了完整的漏斗处理流程。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
如果只把数据当作训练燃料，很容易得出越多越好的结论。但数据工程更接近能力设计，模型看见什么、看不见什么，代码数学百科各占多大比例，这些选择直接影响模型最后形成的能力分布。
|
||||||
|
|
||||||
|
去重和污染控制常被忽略，但它对结果影响很大，要处理的不只是低质量数据，还包括重复模板、许可证文本、镜像网页，以及 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 成本，每往一个方向多花，其他方向就得让步。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
上下文拉长，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**融入有益性和安全性偏好反馈，把模型调整到符合发布标准的助手形态。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
四个阶段互相依赖：冷启动让 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 自动化，用程序去验证中间步骤，绕开人工标注瓶颈。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
这条回路完整跑起来是这样的：
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
最近几类对齐方法都在做同一件事。Anthropic 的 Constitutional AI 把人类写的原则接进训练，用 AI feedback 替代逐条人工偏好。OpenAI 的 Deliberative Alignment 把安全遵守放进推理过程，让推理能力本身承担一部分安全约束。这里说的 Deliberative Alignment 是审慎对齐，核心是推理阶段自行判断安全规范，而不是依赖训入的反射行为。两条路线都在把对齐从人工标签变成训练目标内部的一部分。
|
||||||
|
|
||||||
|
以 Constitutional AI 为例，两阶段流程是先让模型依照原则自我批评和修订输出，再用 AI feedback 替代逐条人工偏好标注。对齐从来不是挂在训练后面的补丁，系统测什么、怎么打分、奖励什么，模型就往哪个方向走，这本身就是训练后半段最直接的调节手段。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## 到了 Agent 训练，优化的不只是模型本身了
|
||||||
|
|
||||||
|
过去两年，以 o1 系列和 DeepSeek-R1 为代表的推理模型快速成型，说明在奖励稳定、验证可靠、基础设施到位的条件下，语言模型上的 RL 确实能显著提升数学、代码和逻辑任务表现。
|
||||||
|
|
||||||
|
这同时打开了一个新维度：推理算力也可以扩展了。RL 训练的作用随之多了一层，它在教模型答题之外，还在教模型分配推理预算，知道什么时候多想、什么时候该停。再往前走，难点就变成让模型在环境里持续行动，而不只是把单次思考拉长。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Qwen 前模型负责人 Junyang Lin 对 Thinking 和 Instruct 混合路线的反思很有代表性：难点不在给模型一个思考开关，而在两种模式的目标本来就不一样，一个追求直接、合规和低延迟，另一个追求更多探索和更高正确率。再往前一步，训练目标就会从回答前想多久，转成行动里怎么分配预算、怎么接反馈、怎么继续推进任务。
|
||||||
|
|
||||||
|
这时候训练对象不再只是一个会回答问题的模型，而是一个能规划、调用工具、接收反馈、在长任务里保持连贯的系统。于是训练栈也跟着变了，浏览器、终端、搜索、执行沙盒、内存系统、工具服务器、编排框架都开始进入训练系统。
|
||||||
|
|
||||||
|
更准确地说，harness 是包在模型外层的控制程序，这个概念不只属于 Agent 运行时，训练阶段同样有它：决定模型看到什么输入、以什么形式接收反馈、何时裁剪上下文、何时调工具。prompt construction、memory update、retrieval policy、context editing、tool orchestration 都在这里。环境也不再只是静态验证器，而是训练和部署都要直接面对的一层。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
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 本身也开始成为可以被外循环搜索和优化的对象。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
Kimi K2.5 的 PARL 是一个很值得拆开的工程案例，路线很明确：只训练 orchestrator，把 credit assignment 收束到编排层，不在所有 sub-agent 上同时优化。
|
||||||
|
|
||||||
|
奖励信号分三类，任务成功、并行分解和完成约束，一起驱动编排层。训练早期把 r\_parallel 权重拉高，鼓励先探索并行策略，后期再逐步退到 0，避免把多开 sub-agent 当成捷径。评估也不只看总步数，还看关键路径长度，关键路径变短才说明并行真的生效。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
但到了 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 上线，那是另一回事。
|
||||||
|
|
||||||
|
大模型的价值，既在它自己的服务能力，也在它会继续给下一代模型提供训练数据、蒸馏来源和发布基座。
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
离线训练之外，接近在线的持续优化也已经进了主流程，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)
|
||||||
|
|
||||||
|
本文不授权任何方式的转载，洗稿再发布，如大伙发现，欢迎去帮我举报。
|
||||||
@@ -1,5 +1,6 @@
|
|||||||
---
|
---
|
||||||
created: 2026-03-29
|
created: 2026-03-29
|
||||||
|
updated: 2026-04-07
|
||||||
type: project
|
type: project
|
||||||
status: active
|
status: active
|
||||||
deadline: ""
|
deadline: ""
|
||||||
@@ -14,6 +15,8 @@ tags:
|
|||||||
- customer-support
|
- customer-support
|
||||||
- websocket
|
- websocket
|
||||||
- postgresql
|
- postgresql
|
||||||
|
- react
|
||||||
|
- docker
|
||||||
---
|
---
|
||||||
|
|
||||||
# Smart Support
|
# Smart Support
|
||||||
@@ -31,35 +34,60 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
|
|||||||
```
|
```
|
||||||
|
|
||||||
核心组件：
|
核心组件：
|
||||||
- **langgraph-supervisor** v1.1 - 多 Agent 编排
|
- **langgraph-supervisor** v0.0.31 -- 多 Agent 编排
|
||||||
- **langchain-mcp-adapters** - MCP 工具集成
|
- **langchain-mcp-adapters** -- MCP 工具集成
|
||||||
- **PostgresSaver** - 会话状态持久化
|
- **langgraph-checkpoint-postgres** v3.0.5 -- 会话状态持久化
|
||||||
- **interrupt()** - 写操作人工确认
|
- **interrupt()** -- 写操作人工确认（30 分钟 TTL 自动取消）
|
||||||
|
|
||||||
## 技术栈
|
## 技术栈
|
||||||
|
|
||||||
- Python 3.11+, FastAPI, LangGraph v1.1
|
| 组件 | 技术 | 版本/说明 |
|
||||||
- React（前端）, PostgreSQL（Docker Compose）
|
|------|------|-----------|
|
||||||
- Claude Sonnet 4.6（可切换 LLM）
|
| 后端 | Python 3.11+ / FastAPI | Web 框架 + WebSocket |
|
||||||
|
| Agent 编排 | LangGraph 1.x | Supervisor 模式多 Agent 路由 |
|
||||||
|
| 检查点 | langgraph-checkpoint-postgres | PostgreSQL 持久化 |
|
||||||
|
| MCP | langchain-mcp-adapters | MultiServerMCPClient |
|
||||||
|
| 数据库 | PostgreSQL 16 | Docker Compose 部署 |
|
||||||
|
| 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+ 测试 94%+ 覆盖率 |
|
||||||
|
| 部署 | Docker Compose | PostgreSQL + FastAPI + nginx |
|
||||||
|
| 日志 | structlog | 结构化日志（console/json 模式） |
|
||||||
|
| 代码质量 | ruff 0.9+ | Python linting + formatting |
|
||||||
|
| 认证 | API Key | `X-API-Key` header / `?token=` for WS |
|
||||||
|
|
||||||
## 核心特性
|
## 核心特性
|
||||||
|
|
||||||
- 多 Agent 协作，YAML 驱动配置
|
- 多 Agent 协作，YAML 驱动配置
|
||||||
- OpenAPI 规范自动生成 MCP 服务器 + Agent 配置（LLM 辅助分类 + 人工审核）
|
- 意图分类（单意图/多意图/模糊检测），LLM 结构化输出
|
||||||
- 写操作人工确认（30 分钟超时自动取消）
|
- OpenAPI 规范自动生成 @tool 函数 + Agent YAML（LLM 辅助分类 + 人工审核）
|
||||||
- 对话回放 + 数据分析仪表盘
|
- 写操作人工确认（interrupt()，30 分钟 TTL 超时自动取消）
|
||||||
- Webhook 升级通知
|
- 对话回放 + 数据分析仪表盘（解决率、Agent 使用率、升级率、成本）
|
||||||
|
- Webhook 升级通知（指数退避重试）
|
||||||
- 垂直行业模板（电商、SaaS、金融科技）
|
- 垂直行业模板（电商、SaaS、金融科技）
|
||||||
|
- SSRF 防护（私有 IP 拦截、DNS 重绑定防御、重定向链验证）
|
||||||
|
- WebSocket 流式输出 + 速率限制（10 msg/10s per thread）
|
||||||
|
- 错误分类 + 自动重试（ErrorCategory 枚举，可重试错误指数退避）
|
||||||
|
|
||||||
## 开发阶段
|
## 开发阶段
|
||||||
|
|
||||||
| 阶段 | 周期 | 内容 | 状态 | 详情 |
|
| 阶段 | 周期 | 内容 | 状态 | 详情 |
|
||||||
|------|------|------|------|------|
|
|------|------|------|------|------|
|
||||||
| Phase 1 | 第 1-3 周 | 核心框架 | COMPLETED (2026-03-30) | [[Smart Support/Phase 1 - 核心框架]] |
|
| Phase 1 | 第 1-3 周 | 核心框架 | COMPLETED (2026-03-30) | [[Smart Support/Phase 1 - 核心框架]] |
|
||||||
| Phase 2 | 第 3-4 周 | 多 Agent + 安全 | 未开始 | [[Smart Support/Phase 2 - 多 Agent + 安全]] |
|
| Phase 2 | 第 3-4 周 | 多 Agent + 安全 | COMPLETED (2026-03-30) | [[Smart Support/Phase 2 - 多 Agent + 安全]] |
|
||||||
| Phase 3 | 第 4-6 周 | OpenAPI 自动发现 | 未开始 | [[Smart Support/Phase 3 - OpenAPI 自动发现]] |
|
| Phase 3 | 第 4-6 周 | OpenAPI 自动发现 | COMPLETED (2026-03-30) | [[Smart Support/Phase 3 - OpenAPI 自动发现]] |
|
||||||
| Phase 4 | 第 6-7 周 | 分析 + 回放 | 未开始 | [[Smart Support/Phase 4 - 分析 + 回放]] |
|
| Phase 4 | 第 6-7 周 | 分析 + 回放 | COMPLETED (2026-03-31) | [[Smart Support/Phase 4 - 分析 + 回放]] |
|
||||||
| Phase 5 | 缓冲周 | 打磨 + 演示 | 未开始 | [[Smart Support/Phase 5 - 打磨 + 演示]] |
|
| Phase 5 | 缓冲周 | 打磨 + 演示 | COMPLETED (2026-03-31) | [[Smart Support/Phase 5 - 打磨 + 演示]] |
|
||||||
|
| Post | 2026-04 | 架构修复 + 工程改进 | 进行中 | API v1 版本化、structlog、Alembic、认证、GraphContext/WebSocketContext |
|
||||||
|
|
||||||
|
## 项目数据
|
||||||
|
|
||||||
|
- 后端测试：516+ 个（单元 ~439 + 集成 ~51 + E2E ~26）
|
||||||
|
- 前端测试：~23 个（vitest + happy-dom）
|
||||||
|
- 代码覆盖率：~94%
|
||||||
|
- 应用版本：v0.6.0
|
||||||
|
- Git 最新提交：`f069943` refactor: engineering improvements -- API versioning, structured logging, Alembic, error standardization
|
||||||
|
|
||||||
## 目标用户
|
## 目标用户
|
||||||
|
|
||||||
@@ -67,43 +95,189 @@ AI 客服行动层框架。粘贴你的 API，获得一个能执行真实操作
|
|||||||
|
|
||||||
## 仓库
|
## 仓库
|
||||||
|
|
||||||
- 代码：`ssh://git@git.colacoder.com:2200/kai/smart-support.git`
|
- 代码：`git@git.colacoder.com:kai/smart-support.git`
|
||||||
- 分支：`main`
|
- 分支：`main`
|
||||||
- 本地路径：`/Users/yiukai/Documents/git/smart-support`
|
- 本地路径（Windows）：`C:\Users\yaoji\git\ColaCoder\smart-support`
|
||||||
|
|
||||||
|
## WebSocket 协议
|
||||||
|
|
||||||
|
客户端 -> 服务器：
|
||||||
|
- `{"type": "message", "thread_id": "...", "content": "..."}`
|
||||||
|
- `{"type": "interrupt_response", "thread_id": "...", "approved": true/false}`
|
||||||
|
|
||||||
|
服务器 -> 客户端（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
|
||||||
|
|
||||||
|
所有端点使用 `/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 |
|
||||||
|
|
||||||
|
## 数据库表
|
||||||
|
|
||||||
|
| 表 | 用途 |
|
||||||
|
|----|----|
|
||||||
|
| checkpoints | LangGraph 状态快照（自动管理） |
|
||||||
|
| checkpoint_writes | 检查点写入记录 |
|
||||||
|
| conversations | 对话元数据（状态、解决类型、使用 Agent、Token、成本） |
|
||||||
|
| 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 | 决策 | 理由 |
|
||||||
|
|-----|------|------|
|
||||||
|
| ADR-001 | LangGraph Supervisor 多 Agent | 内置编排，无需自定义 |
|
||||||
|
| ADR-002 | PostgresSaver 从第一天起 | Phase 4 分析需要可查询的检查点数据 |
|
||||||
|
| ADR-003 | WebSocket + astream_events() | 双向低延迟流式 |
|
||||||
|
| ADR-004 | YAML 声明式 Agent 注册 | 非开发者可配置 Agent |
|
||||||
|
| ADR-005 | LangGraph interrupt() HITL | 框架内置，深度集成检查点 |
|
||||||
|
| ADR-006 | OpenAPI: 解析 -> LLM 分类 -> 人工审核 | 平衡自动化与安全 |
|
||||||
|
| ADR-007 | SSRF 独立模块 | 可复用，可独立测试 |
|
||||||
|
|
||||||
|
## 安全架构
|
||||||
|
|
||||||
|
- **L1 输入验证**：消息格式、长度限制（10k 字符）、Agent YAML 启动验证
|
||||||
|
- **L2 SSRF 防护**：私有 IP 拦截、DNS 重绑定防御、重定向链验证
|
||||||
|
- **L3 HITL**：写操作 interrupt()、30 分钟 TTL 自动取消
|
||||||
|
- **L4 权限隔离**：Agent 级工具集、读 Agent 无法调写工具
|
||||||
|
- **L5 审计追踪**：全操作记录、PostgreSQL 存储、回放 API
|
||||||
|
|
||||||
## 完整文档（已同步）
|
## 完整文档（已同步）
|
||||||
|
|
||||||
- [[Smart Support/Architecture]] - 系统架构文档（12 章，含 ADR、数据库设计、API 协议）
|
- [[Smart Support/Architecture]] -- 系统架构文档（12 章，含 ADR、数据库设计、API 协议）
|
||||||
- [[Smart Support/Development Plan]] - 详细开发计划（6 Phase，任务清单 + 检查点 + 风险）
|
- [[Smart Support/Development Plan]] -- 详细开发计划（5 Phase，任务清单 + 检查点 + 风险）
|
||||||
- [[Smart Support/Phase 1 Dev Log]] - Phase 1 开发日志（88% 覆盖率，82 个单元测试）
|
- [[Smart Support/Phase 1 Dev Log]] -- Phase 1 开发日志（88% 覆盖率，82 个单元测试）
|
||||||
|
- [[Smart Support/Phase 2 Dev Log]] -- Phase 2 开发日志（90% 覆盖率，153 个测试）
|
||||||
|
- [[Smart Support/Phase 3 Dev Log]] -- Phase 3 开发日志（93% 覆盖率，322 个测试）
|
||||||
|
- [[Smart Support/Phase 4 Dev Log]] -- Phase 4 开发日志（93% 覆盖率，399 个测试）
|
||||||
|
- [[Smart Support/Phase 5 Dev Log]] -- Phase 5 开发日志（93% 覆盖率，449 个测试）
|
||||||
|
|
||||||
|
## 项目模块结构
|
||||||
|
|
||||||
|
```
|
||||||
|
backend/app/
|
||||||
|
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 滑动窗口）+ 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, review_api）
|
||||||
|
replay/ -- 回放模型 + 转换器 + API
|
||||||
|
analytics/ -- 分析模型 + 事件记录 + 查询 + API
|
||||||
|
```
|
||||||
|
|
||||||
|
### 架构模式
|
||||||
|
|
||||||
|
- **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）
|
||||||
|
|
||||||
## 计划文档
|
## 计划文档
|
||||||
|
|
||||||
项目根目录下：
|
项目根目录下：
|
||||||
- `design-doc.md` - 设计文档（问题定义、约束、方案选择）
|
- `design-doc.md` -- 设计文档（问题定义、约束、方案选择）
|
||||||
- `ceo-plan.md` - CEO 计划（产品愿景、范围决策）
|
- `ceo-plan.md` -- CEO 计划（产品愿景、范围决策）
|
||||||
- `eng-review-plan.md` - 工程评审（架构决策、测试策略、失败模式）
|
- `eng-review-plan.md` -- 工程评审（架构决策、测试策略、失败模式）
|
||||||
- `eng-review-test-plan.md` - 测试计划（测试路径、边界情况、E2E 流程）
|
- `TODOS.md` -- 待办事项
|
||||||
- `TODOS.md` - 待办事项
|
|
||||||
|
|
||||||
## 关键决策
|
## 快速启动
|
||||||
|
|
||||||
- 用 LangGraph 内置能力（supervisor、checkpointer、interrupt），不自己造轮子
|
```bash
|
||||||
- PostgresSaver 从第一天起使用，为后期分析和回放打基础
|
# 1. 克隆 + 配置
|
||||||
- OpenAPI 导入生成完整 MCP 服务器（非简单 @tool 函数），LLM 辅助端点分类
|
git clone <repo-url> && cd smart-support
|
||||||
- 路由错误时有 fallback agent 兜底
|
cp .env.example .env && cp backend/.env.example backend/.env
|
||||||
- 解决率定义：成功工具调用 + 未升级
|
# 编辑 .env 设置 ANTHROPIC_API_KEY
|
||||||
- Token 用量从第一天起记录
|
|
||||||
|
|
||||||
## 待解决
|
# 2. 启动
|
||||||
|
docker compose up -d
|
||||||
|
# PostgreSQL: localhost:5433 | Backend: localhost:8000 | Frontend: localhost:80
|
||||||
|
|
||||||
- [ ] 认证/授权系统（生产部署前）
|
# 3. 测试
|
||||||
|
cd backend && pytest --cov=app --cov-report=term-missing
|
||||||
|
cd ../frontend && npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
## 自动编排脚本
|
||||||
|
|
||||||
|
项目 `scripts/` 目录下有基于 autonomous-agent-harness 模式的自动化脚本：
|
||||||
|
|
||||||
|
| 脚本 | 用途 | 模式 |
|
||||||
|
|------|------|------|
|
||||||
|
| `auto-pilot.sh` | 多阶段自动执行（每阶段独立 `claude -p` session） | Sequential Pipeline |
|
||||||
|
| `dev-sequential.sh` | 单功能开发（plan → TDD → de-sloppify → verify → commit） | Sequential Pipeline |
|
||||||
|
| `de-sloppify.sh` | 独立清理 pass（新上下文 = 无作者偏见） | De-Sloppify |
|
||||||
|
| `full-verify.sh` | 全套质量门（测试、安全、模块独立性、代码质量） | Verification Pipeline |
|
||||||
|
| `pr-review-loop.sh` | 自动审查 open PRs | Continuous PR Loop |
|
||||||
|
| `health-monitor.sh` | 服务健康检查（可配 Windows Task Scheduler） | Scheduled Monitor |
|
||||||
|
| `phases.json` | 声明式阶段定义（任务、验收标准、模式、依赖） | 配置文件 |
|
||||||
|
|
||||||
|
**大部分时候不需要外部脚本** — 在 Claude Code 内直接用：
|
||||||
|
- `/ecc:feature-dev "描述"` — 单功能全流程
|
||||||
|
- `/gsd:autonomous` — 全项目多阶段自动
|
||||||
|
|
||||||
|
脚本只在以下场景使用：上下文窗口不够、无人值守运行、需要 Santa Method 消除作者偏见。
|
||||||
|
|
||||||
|
**CLAUDE.md 已更新**：Step 2 从 `/ecc:orchestrate`（legacy）迁移到 `/ecc:feature-dev` + GSD。
|
||||||
|
|
||||||
|
## 已知技术债务
|
||||||
|
|
||||||
|
- [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 流水线（原型阶段手动部署）
|
- [ ] CI/CD 流水线（原型阶段手动部署）
|
||||||
- [ ] 路由准确率评估数据集
|
- [ ] 速率限制进程全局状态 -- 多 Worker 需 Redis
|
||||||
- [ ] 过期中断处理（Phase 2 实现）
|
- [ ] 生产环境切换到 PgSessionManager/PgInterruptManager
|
||||||
- [ ] SSRF 防护模块（Phase 3 前构建）
|
- [ ] OpenAPI approve 后的工具尚未运行时注入到 _TOOL_MAP（仅生成代码 + YAML）
|
||||||
|
- [ ] SSRF DNS 重绑定 TOCTOU 窗口（实践中利用难度大）
|
||||||
|
- [ ] SaaS/Fintech 模板工具仅为桩（无实现）
|
||||||
|
- [ ] 工具生成基于字符串模板 -- 复杂场景可能需 AST
|
||||||
|
|
||||||
## Related
|
## Related
|
||||||
|
|
||||||
- [[Billo Release Agent]] - 另一个 AI Agent 项目
|
- [[Billo Release Agent]] -- 另一个 AI Agent 项目
|
||||||
|
|||||||
@@ -1,5 +1,6 @@
|
|||||||
---
|
---
|
||||||
created: 2026-03-29
|
created: 2026-03-29
|
||||||
|
updated: 2026-04-06
|
||||||
type: project
|
type: project
|
||||||
status: COMPLETED (2026-03-30)
|
status: COMPLETED (2026-03-30)
|
||||||
parent: "[[Smart Support]]"
|
parent: "[[Smart Support]]"
|
||||||
|
|||||||
@@ -1,7 +1,8 @@
|
|||||||
---
|
---
|
||||||
created: 2026-03-29
|
created: 2026-03-29
|
||||||
|
updated: 2026-04-06
|
||||||
type: project
|
type: project
|
||||||
status: 未开始
|
status: COMPLETED (2026-03-30)
|
||||||
parent: "[[Smart Support]]"
|
parent: "[[Smart Support]]"
|
||||||
phase: 2
|
phase: 2
|
||||||
timeline: 第 3-4 周
|
timeline: 第 3-4 周
|
||||||
@@ -20,161 +21,51 @@ tags:
|
|||||||
|
|
||||||
# Phase 2：多 Agent + 安全
|
# Phase 2：多 Agent + 安全
|
||||||
|
|
||||||
|
> Status: COMPLETED (2026-03-30)
|
||||||
|
|
||||||
## 目标
|
## 目标
|
||||||
|
|
||||||
让 Supervisor 具备真正的多 Agent 路由能力，能根据用户意图选择正确的 Agent。同时完善安全机制：中断超时处理、Webhook 升级通知。这个阶段结束时，系统能处理多种类型的客服请求，并在无法解决时通过 Webhook 通知人工。
|
让 Supervisor 具备真正的多 Agent 路由能力，能根据用户意图选择正确的 Agent。同时完善安全机制：中断超时处理、Webhook 升级通知。
|
||||||
|
|
||||||
## 前置条件
|
|
||||||
|
|
||||||
- [[Smart Support/Phase 1 - 核心框架]] 完成
|
|
||||||
- 核心聊天闭环端到端可用
|
|
||||||
- PostgresSaver + interrupt() 基础流程工作正常
|
|
||||||
|
|
||||||
## 阶段产出
|
## 阶段产出
|
||||||
|
|
||||||
- Supervisor 能准确路由不同类型的请求到对应 Agent
|
- Intent 分类器：LLM 结构化输出，支持单意图/多意图/模糊检测
|
||||||
- 多意图请求（「取消订单并给我折扣」）能被拆分并按序处理
|
- Discount Agent：apply_discount（write + interrupt）+ generate_coupon（read）
|
||||||
- 无法解决的问题通过 Webhook 通知人工客服
|
- 中断管理器：30 分钟 TTL 自动过期，register/check/resolve/cleanup
|
||||||
- 过期中断自动取消并提供重试选项
|
- Webhook 升级：HTTP POST + 指数退避重试（最多 3 次）
|
||||||
- 2-3 个垂直行业模板开箱可用
|
- 增强 Supervisor 路由：动态 Agent 描述、多意图提示注入
|
||||||
|
- 垂直行业模板：电商、SaaS、金融科技
|
||||||
|
- 模板加载：load_template() / list_templates()
|
||||||
|
|
||||||
## 集成检查点
|
## 新增文件
|
||||||
|
|
||||||
第 4 周末验证：
|
| 文件 | 用途 |
|
||||||
1. 发送订单查询 → 路由到 order_lookup agent
|
|------|------|
|
||||||
2. 发送「取消订单并退款」→ 按序处理两个操作
|
| `app/intent.py` | 意图分类模型 + LLM 分类器 |
|
||||||
3. 发送无法处理的请求 → Webhook POST 发出
|
| `app/agents/discount.py` | 折扣 Agent 工具 |
|
||||||
4. 触发确认 → 30 分钟不操作 → 自动取消 → 重新发消息收到重试提示
|
| `app/interrupt_manager.py` | 中断 TTL 管理 |
|
||||||
5. 加载电商模板 YAML → 相关 agents 自动注册
|
| `app/escalation.py` | Webhook 升级 + 重试 |
|
||||||
|
| `templates/e-commerce.yaml` | 电商模板 |
|
||||||
|
| `templates/saas.yaml` | SaaS 模板 |
|
||||||
|
| `templates/fintech.yaml` | 金融科技模板 |
|
||||||
|
|
||||||
---
|
## 测试覆盖
|
||||||
|
|
||||||
## 任务清单
|
- 总测试：153（Phase 1: 87 + Phase 2: 66）
|
||||||
|
- 覆盖率：90.18%
|
||||||
|
- 新模块覆盖：intent 100%, discount 96%, interrupt_manager 100%, escalation 100%
|
||||||
|
|
||||||
### 1. 完善 Supervisor 路由
|
## 与计划的偏差
|
||||||
|
|
||||||
- [ ] 优化 supervisor 的 agent 描述，使路由更准确
|
- 多意图处理用 Supervisor 提示注入而非自定义预路由节点（更简单）
|
||||||
- [ ] 多意图处理：supervisor 识别复合请求，拆分为多个子任务，按序执行
|
- Webhook 升级已接入 app.state 但未连接到具体 Agent 工具（模块就绪，集成推迟）
|
||||||
- 例如「取消订单 1042 并给我一个 10% 折扣码」→ 先路由到 order_actions（取消），再路由到 discount（发码）
|
- `escalate_to_human` 工具未创建（升级模块可独立触发）
|
||||||
- [ ] 模糊/冲突意图处理：supervisor 无法判断时，返回澄清问题（「您是想查询订单还是取消订单？」）
|
|
||||||
- [ ] 路由失败日志：每次路由记录 `{intent, selected_agent, confidence}`，为后续评估提供数据
|
|
||||||
|
|
||||||
### 2. 过期中断处理
|
## 技术债务
|
||||||
|
|
||||||
- [ ] 中断触发时记录 `interrupt_timestamp` 到 graph state
|
- SaaS/Fintech 模板工具名称无实现（配置蓝图）
|
||||||
- [ ] 用户恢复对话时检查：`current_time - interrupt_timestamp > 30 min`
|
- 中断清理未定时调度
|
||||||
- [ ] 超时行为：
|
- main.py 覆盖率 44%（需真实 DB）
|
||||||
1. 将该操作标记为已取消（不执行）
|
|
||||||
2. 返回消息：「您之前请求的[操作描述]已因超时取消。订单状态可能已变化，需要我重新查看吗？」
|
|
||||||
3. Agent 重新评估当前状态（重新调用查询工具），而不是直接重试旧操作
|
|
||||||
- [ ] 未超时：正常恢复 interrupt 流程（approve/reject）
|
|
||||||
|
|
||||||
### 3. Webhook 升级通知
|
|
||||||
|
|
||||||
- [ ] 配置项：`webhook_url`（在 agents.yaml 或环境变量中配置）
|
|
||||||
- [ ] 触发条件：
|
|
||||||
- Agent 明确表示无法处理（返回 escalation 标记）
|
|
||||||
- Supervisor 连续 3 次路由失败（用户重复同一问题）
|
|
||||||
- 用户主动请求人工客服
|
|
||||||
- [ ] Webhook payload 格式：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"event": "escalation",
|
|
||||||
"thread_id": "uuid",
|
|
||||||
"timestamp": "2026-04-10T14:30:00Z",
|
|
||||||
"reason": "agent_unable_to_resolve",
|
|
||||||
"conversation_summary": "客户询问关于批量退货的问题，order_lookup agent 无法找到相关功能",
|
|
||||||
"messages": [
|
|
||||||
{"role": "user", "content": "..."},
|
|
||||||
{"role": "assistant", "content": "..."}
|
|
||||||
],
|
|
||||||
"customer_context": {
|
|
||||||
"resolved_entities": {"order_id": "1042"}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] HTTP POST 发送，设置 10 秒 timeout
|
|
||||||
- [ ] 失败重试：最多 3 次，指数退避（1s, 2s, 4s）
|
|
||||||
- [ ] 重试全部失败 → 记录日志（ERROR 级别），不阻塞聊天流程
|
|
||||||
- [ ] 在聊天 UI 中通知用户：「已通知人工客服，他们会尽快联系您」
|
|
||||||
|
|
||||||
### 4. 垂直行业模板
|
|
||||||
|
|
||||||
- [ ] 创建模板目录 `backend/templates/`
|
|
||||||
- [ ] 电商模板 `ecommerce.yaml`：
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
name: ecommerce
|
|
||||||
description: 电商客服模板 - 订单管理、物流查询、退换货
|
|
||||||
agents:
|
|
||||||
- name: order_lookup
|
|
||||||
description: 查询订单状态、物流跟踪、收货确认
|
|
||||||
permission: read
|
|
||||||
personality:
|
|
||||||
tone: professional
|
|
||||||
greeting: "您好！我可以帮您查询订单相关信息。"
|
|
||||||
tools: [get_order, get_tracking, list_orders]
|
|
||||||
|
|
||||||
- name: order_actions
|
|
||||||
description: 取消订单、修改地址、申请退换货
|
|
||||||
permission: write
|
|
||||||
personality:
|
|
||||||
tone: careful
|
|
||||||
greeting: "我可以帮您处理订单变更，所有操作都会先确认。"
|
|
||||||
tools: [cancel_order, modify_address, request_return]
|
|
||||||
|
|
||||||
- name: promotions
|
|
||||||
description: 查询优惠活动、发放折扣码
|
|
||||||
permission: write
|
|
||||||
personality:
|
|
||||||
tone: enthusiastic
|
|
||||||
tools: [apply_discount, check_promotions]
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] SaaS 模板 `saas.yaml`：账号管理、订阅变更、功能咨询
|
|
||||||
- [ ] 金融科技模板 `fintech.yaml`：账户查询、交易记录、转账操作
|
|
||||||
- [ ] 模板加载机制：启动时指定 `--template ecommerce` 或在配置中设置 `template: ecommerce`
|
|
||||||
- [ ] 模板与自定义 agents.yaml 合并：模板提供默认值，自定义配置覆盖
|
|
||||||
|
|
||||||
### 5. 新增演示 Agent
|
|
||||||
|
|
||||||
在 Phase 1 的基础上增加写操作 Agent：
|
|
||||||
|
|
||||||
- [ ] `order_actions` agent：取消订单（`cancel_order`）、修改地址（`modify_address`）
|
|
||||||
- [ ] `discount` agent：发放优惠券（`apply_discount`）、生成折扣码（`generate_coupon`）
|
|
||||||
- [ ] 所有写操作工具标记 `permission: write` → 自动触发 interrupt
|
|
||||||
|
|
||||||
### 6. 测试
|
|
||||||
|
|
||||||
- [ ] **路由测试：** 「查询订单」→ order_lookup，「取消订单」→ order_actions，「给我折扣」→ discount
|
|
||||||
- [ ] **路由测试：** 模糊请求 → 返回澄清问题
|
|
||||||
- [ ] **多意图测试：** 「取消订单并退款」→ 按序执行两个操作
|
|
||||||
- [ ] **超时测试：** interrupt 后 mock 时间超过 30 分钟 → 自动取消 + 重试提示
|
|
||||||
- [ ] **超时测试：** interrupt 后 mock 时间未超过 30 分钟 → 正常 approve/reject
|
|
||||||
- [ ] **Webhook 测试：** 升级触发 → HTTP POST 发出，payload 格式正确
|
|
||||||
- [ ] **Webhook 测试：** 目标 URL 不可达 → 重试 3 次 → 记录日志 → 聊天不中断
|
|
||||||
- [ ] **模板测试：** 加载电商模板 → agents 正确注册
|
|
||||||
- [ ] **模板测试：** 自定义配置覆盖模板默认值
|
|
||||||
- [ ] **E2E 测试：** 完整升级流程（无法处理 → webhook 发出 → 用户收到通知）
|
|
||||||
|
|
||||||
## 技术要点
|
|
||||||
|
|
||||||
| 功能 | 实现方式 |
|
|
||||||
|------|---------|
|
|
||||||
| 多意图拆分 | Supervisor LLM 识别并按序调度 |
|
|
||||||
| 超时检测 | graph state 记录 timestamp，resume 时比较 |
|
|
||||||
| Webhook | httpx.AsyncClient POST，asyncio 重试 |
|
|
||||||
| 模板加载 | PyYAML 加载 + 与自定义 YAML 深度合并 |
|
|
||||||
|
|
||||||
## 风险与缓解
|
|
||||||
|
|
||||||
| 风险 | 影响 | 缓解措施 |
|
|
||||||
|------|------|---------|
|
|
||||||
| 多意图拆分不准确 | 操作顺序错误或遗漏 | 先处理常见组合，复杂情况要求用户分步操作 |
|
|
||||||
| Webhook 目标服务不稳定 | 升级通知丢失 | 重试 + 日志 + 聊天内告知用户 |
|
|
||||||
| 超时时间 30 分钟不合适 | 过早或过晚取消 | 配置化，允许每个 agent 自定义 TTL |
|
|
||||||
|
|
||||||
## Related
|
## Related
|
||||||
|
|
||||||
|
|||||||
43
2 - Projects/Smart Support/Phase 2 Dev Log.md
Normal file
43
2 - Projects/Smart Support/Phase 2 Dev Log.md
Normal file
@@ -0,0 +1,43 @@
|
|||||||
|
---
|
||||||
|
created: 2026-04-06
|
||||||
|
type: log
|
||||||
|
project: "[[Smart Support]]"
|
||||||
|
source: docs/phases/phase-2-dev-log.md
|
||||||
|
tags:
|
||||||
|
- dev-log
|
||||||
|
- phase-2
|
||||||
|
- intent-classification
|
||||||
|
- discount-agent
|
||||||
|
- interrupt-ttl
|
||||||
|
- webhook-escalation
|
||||||
|
- templates
|
||||||
|
---
|
||||||
|
|
||||||
|
# Phase 2: Multi-Agent Routing + Safety -- Development Log
|
||||||
|
|
||||||
|
> Status: COMPLETED
|
||||||
|
> Phase branch: `phase-2/multi-agent-safety`
|
||||||
|
> Date started: 2026-03-30
|
||||||
|
> Date completed: 2026-03-30
|
||||||
|
|
||||||
|
## What Was Built
|
||||||
|
|
||||||
|
- **Intent Classification** (`app/intent.py`): LLM 结构化输出意图分类器，Pydantic 模型（IntentTarget, ClassificationResult）。支持单意图、多意图、模糊检测，可配置置信度阈值。
|
||||||
|
- **Discount Agent** (`app/agents/discount.py`): Mock Agent，apply_discount（write + interrupt）和 generate_coupon（read）。验证折扣范围 1-100%。
|
||||||
|
- **Interrupt Manager** (`app/interrupt_manager.py`): TTL 中断追踪，30 分钟自动过期。提供 register, check_status, resolve, cleanup_expired, generate_retry_prompt。
|
||||||
|
- **Webhook Escalation** (`app/escalation.py`): HTTP POST 升级，指数退避重试（最多 3 次）。WebhookEscalator + NoOpEscalator，EscalationService Protocol。
|
||||||
|
- **Enhanced Supervisor** (`app/graph.py`): 动态 Agent 描述 Supervisor 提示。意图分类器附加到 graph。多意图提示注入。
|
||||||
|
- **Vertical Templates**: 三个行业 YAML 模板（电商、SaaS、金融科技）。
|
||||||
|
- **Template Loading** (`app/registry.py`): load_template() 和 list_templates()。
|
||||||
|
- **WebSocket Integration**: 模糊意图发送澄清消息。中断 TTL 检查 -- 过期中断返回重试提示。
|
||||||
|
|
||||||
|
## Test Coverage
|
||||||
|
|
||||||
|
- Total: 153 tests (Phase 1: 87 + Phase 2: 66)
|
||||||
|
- Coverage: 90.18%
|
||||||
|
- intent.py: 100% | discount.py: 96% | interrupt_manager.py: 100% | escalation.py: 100%
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [[Smart Support]]
|
||||||
|
- [[Smart Support/Phase 2 - 多 Agent + 安全]]
|
||||||
@@ -1,7 +1,8 @@
|
|||||||
---
|
---
|
||||||
created: 2026-03-29
|
created: 2026-03-29
|
||||||
|
updated: 2026-04-06
|
||||||
type: project
|
type: project
|
||||||
status: 未开始
|
status: COMPLETED (2026-03-30)
|
||||||
parent: "[[Smart Support]]"
|
parent: "[[Smart Support]]"
|
||||||
phase: 3
|
phase: 3
|
||||||
timeline: 第 4-6 周
|
timeline: 第 4-6 周
|
||||||
@@ -19,177 +20,59 @@ tags:
|
|||||||
|
|
||||||
# Phase 3：OpenAPI 自动发现
|
# Phase 3：OpenAPI 自动发现
|
||||||
|
|
||||||
|
> Status: COMPLETED (2026-03-30)
|
||||||
|
|
||||||
## 目标
|
## 目标
|
||||||
|
|
||||||
实现 Smart Support 的「10x 差异化功能」：用户粘贴 OpenAPI 规范 URL，系统自动生成 MCP 服务器和 Agent 配置。这个阶段结束时，用户无需写代码，只需提供 API 文档就能让 AI Agent 操作他们的系统。
|
实现 Smart Support 的「10x 差异化功能」：用户粘贴 OpenAPI 规范 URL，系统自动生成 @tool 函数和 Agent 配置。
|
||||||
|
|
||||||
## 前置条件
|
|
||||||
|
|
||||||
- [[Smart Support/Phase 2 - 多 Agent + 安全]] 完成
|
|
||||||
- 多 Agent 路由 + interrupt 流程工作正常
|
|
||||||
- YAML agent 注册表可以动态加载新 agent
|
|
||||||
|
|
||||||
## 阶段产出
|
## 阶段产出
|
||||||
|
|
||||||
- 粘贴 OpenAPI spec URL → 自动解析 + 生成 MCP 服务器 + 注册 Agent
|
- SSRF 防护模块：私有 IP 拦截、DNS 重绑定防御、重定向链验证
|
||||||
- LLM 自动分类端点（读/写、客户参数、Agent 分组）
|
- OpenAPI 获取器：SSRF 安全、JSON/YAML 自动检测、10MB 大小限制
|
||||||
- 运维审核界面确认/修正 LLM 分类结果
|
- 结构化 OpenAPI 验证器：3.0.x 和 3.1.x
|
||||||
- SSRF 防护保障 URL 获取安全
|
- 端点解析器：$ref 解析、参数提取、自动生成 operationId
|
||||||
- 导入过程异步执行，WebSocket 实时推送进度
|
- 启发式 + LLM 端点分类器：GET=read, POST/PUT/PATCH/DELETE=write，LLM 失败回退启发式
|
||||||
|
- 审核 API（/api/openapi）：导入任务、分类审核、批准生成
|
||||||
|
- @tool 代码生成器：async 函数 + httpx
|
||||||
|
- Agent YAML 生成器：按分类分组端点
|
||||||
|
- 导入编排器：fetch -> validate -> parse -> classify 全流程
|
||||||
|
- 内存任务存储：导入状态追踪
|
||||||
|
|
||||||
## 集成检查点
|
## 新增文件
|
||||||
|
|
||||||
第 6 周末验证：
|
| 文件 | 用途 | 行数 |
|
||||||
1. 粘贴一个真实的 OpenAPI 3.0 spec URL → 解析成功
|
|------|------|------|
|
||||||
2. 生成的 MCP 服务器正确包装每个端点
|
| `app/openapi/models.py` | 冻结数据类：EndpointInfo, ClassificationResult, ImportJob | 68 |
|
||||||
3. LLM 分类结果合理（GET = read，DELETE = write）
|
| `app/openapi/ssrf.py` | SSRF 防护（validate_url, safe_fetch, DNS 解析） | 162 |
|
||||||
4. 运维审核后，agent 自动注册到 supervisor
|
| `app/openapi/fetcher.py` | SSRF 安全规范获取 | 94 |
|
||||||
5. 在聊天中使用新生成的工具完成操作
|
| `app/openapi/validator.py` | 结构化规范验证 | 52 |
|
||||||
6. SSRF 攻击被拦截（私有 IP、localhost）
|
| `app/openapi/parser.py` | 端点提取 + $ref 解析 | 153 |
|
||||||
|
| `app/openapi/classifier.py` | 启发式 + LLM 分类器 | 164 |
|
||||||
|
| `app/openapi/review_api.py` | 导入/审核 API 路由 | 180 |
|
||||||
|
| `app/openapi/generator.py` | @tool 代码 + YAML 生成 | 157 |
|
||||||
|
| `app/openapi/importer.py` | 异步导入流水线 | 117 |
|
||||||
|
|
||||||
---
|
## 测试覆盖
|
||||||
|
|
||||||
## 任务清单
|
- 新增测试：125 个（118 单元 + 7 集成）
|
||||||
|
- 总测试：322
|
||||||
|
- 覆盖率：93.23%
|
||||||
|
- SSRF 测试最多：42 个
|
||||||
|
|
||||||
### 1. SSRF 防护模块
|
## 与计划的偏差
|
||||||
|
|
||||||
> 独立模块 `backend/app/openapi/ssrf.py`，可与 Phase 1-2 并行开发
|
- 未构建自定义工具基类（架构文档明确禁止）
|
||||||
|
- 使用轻量级结构化验证器而非包装外部库
|
||||||
|
- 内存任务存储而非数据库（可后续迁移 PostgreSQL）
|
||||||
|
- 前端审核 UI 推迟到 Phase 5
|
||||||
|
|
||||||
- [ ] URL 解析：提取 host，解析 DNS 获取 IP
|
## 技术债务
|
||||||
- [ ] 屏蔽私有 IP 范围：
|
|
||||||
- `10.0.0.0/8`
|
|
||||||
- `172.16.0.0/12`
|
|
||||||
- `192.168.0.0/16`
|
|
||||||
- `127.0.0.0/8`（localhost）
|
|
||||||
- `169.254.0.0/16`（link-local，云元数据端点）
|
|
||||||
- `0.0.0.0/8`
|
|
||||||
- `::1`（IPv6 localhost）
|
|
||||||
- [ ] DNS 重绑定防护：解析 DNS → 检查 IP → 使用解析后的 IP 发起请求（不让 DNS 在检查和请求之间变化）
|
|
||||||
- [ ] URL 协议限制：仅允许 `http://` 和 `https://`，拒绝 `file://`, `ftp://`, `gopher://` 等
|
|
||||||
- [ ] 可选 URL 白名单：通过配置限制只允许特定域名
|
|
||||||
- [ ] 单元测试覆盖所有拦截场景
|
|
||||||
|
|
||||||
### 2. OpenAPI 规范解析器
|
- 前端 ReviewPage 推迟（API 就绪）
|
||||||
|
- 代码生成基于字符串模板
|
||||||
- [ ] 支持 OpenAPI 3.0+ 规范（JSON 和 YAML 格式）
|
- LLM 分类提示可用真实案例调优
|
||||||
- [ ] 使用 `openapi-spec-validator` 验证规范合法性
|
- 审核 API 无速率限制
|
||||||
- [ ] 通过 SSRF 安全模块获取远程 URL 内容
|
|
||||||
- [ ] 解析每个端点提取：
|
|
||||||
- HTTP 方法 + 路径
|
|
||||||
- 描述 / summary
|
|
||||||
- 请求参数（path params, query params, request body schema）
|
|
||||||
- 响应 schema
|
|
||||||
- 认证要求（API key, Bearer token, OAuth）
|
|
||||||
- [ ] 错误处理：
|
|
||||||
- 无效 URL → 「无法访问该地址，请检查 URL 是否正确」
|
|
||||||
- 无效规范格式 → 「该文件不是有效的 OpenAPI 3.0 规范：[具体原因]」
|
|
||||||
- 认证要求无法自动满足 → 提示用户提供 API key
|
|
||||||
- [ ] OpenAPI 2.0 (Swagger) → 返回明确提示：「检测到 Swagger 2.0 格式，请升级到 OpenAPI 3.0」
|
|
||||||
- [ ] 大型规范（100+ 端点）→ 正常处理，不超时
|
|
||||||
|
|
||||||
### 3. MCP 服务器生成器
|
|
||||||
|
|
||||||
- [ ] 为每个解析到的端点生成 MCP tool 定义
|
|
||||||
- [ ] Tool 名称：从路径 + 方法自动生成（如 `GET /orders/{id}` → `get_order_by_id`）
|
|
||||||
- [ ] Tool 描述：使用端点的 summary/description
|
|
||||||
- [ ] Tool 参数：从 path params + query params + request body 提取，保留类型信息
|
|
||||||
- [ ] 生成可运行的 MCP 服务器代码（Python，使用 `mcp` SDK）
|
|
||||||
- [ ] 处理复杂 request body（嵌套对象、数组）→ 扁平化或保留 JSON 结构
|
|
||||||
- [ ] 认证注入：生成的服务器支持在配置中设置 API key / Bearer token，自动添加到请求 header
|
|
||||||
|
|
||||||
### 4. LLM 辅助端点分类
|
|
||||||
|
|
||||||
- [ ] 将解析后的端点信息（方法、路径、描述）发送给 LLM
|
|
||||||
- [ ] LLM 分类任务：
|
|
||||||
1. **读/写分类**：每个端点标记为 `read`（不触发 interrupt）或 `write`（触发 interrupt）
|
|
||||||
2. **客户参数识别**：哪些参数代表客户标识（customer_id, email, phone）
|
|
||||||
3. **Agent 分组建议**：将端点按功能分组为不同 Agent（如「订单管理」「用户管理」「支付操作」）
|
|
||||||
- [ ] 分类提示模板：
|
|
||||||
|
|
||||||
```
|
|
||||||
你是一个 API 安全分析师。分析以下 API 端点列表，为每个端点提供：
|
|
||||||
1. 操作类型：read（查询/获取数据）或 write（创建/修改/删除数据）
|
|
||||||
2. 客户参数：哪些参数代表客户身份标识
|
|
||||||
3. 建议的 Agent 分组名称
|
|
||||||
|
|
||||||
规则：
|
|
||||||
- GET 请求通常是 read，但要看描述（如 GET /export 可能是 write）
|
|
||||||
- POST/PUT/PATCH/DELETE 通常是 write
|
|
||||||
- 涉及金钱、订单状态变更、账号操作的必须标记为 write
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] 分类结果缓存：同一规范不重复分类
|
|
||||||
- [ ] 成本控制：使用 prompt caching 减少重复输入成本
|
|
||||||
|
|
||||||
### 5. 运维审核/修正 UI
|
|
||||||
|
|
||||||
- [ ] API 端点：`GET /api/openapi/review/{import_id}` → 返回 LLM 分类结果
|
|
||||||
- [ ] API 端点：`POST /api/openapi/review/{import_id}` → 提交修正后的分类
|
|
||||||
- [ ] 前端审核界面：
|
|
||||||
- 端点列表，每行显示：方法、路径、描述、LLM 分类（read/write）、Agent 分组
|
|
||||||
- 每个分类可以点击修改（下拉选择）
|
|
||||||
- 「全部确认」按钮 → 生成最终 MCP 服务器 + Agent YAML
|
|
||||||
- [ ] 修正后重新生成不需要再次调用 LLM
|
|
||||||
|
|
||||||
### 6. Agent YAML 自动生成
|
|
||||||
|
|
||||||
- [ ] 根据 LLM 分类 + 运维修正结果，生成 Agent YAML 配置
|
|
||||||
- [ ] 每个 Agent 分组 → 一个 agent 条目
|
|
||||||
- [ ] permission 根据分组内端点的最高权限决定（有一个 write 端点就标记为 write）
|
|
||||||
- [ ] 自动生成 agent description（基于分组内端点的描述汇总）
|
|
||||||
- [ ] 生成的 YAML 合并到 agent 注册表，热加载到 supervisor（不需要重启）
|
|
||||||
|
|
||||||
### 7. 异步导入 + 进度更新
|
|
||||||
|
|
||||||
- [ ] 导入流程作为后台任务执行（`asyncio.create_task`）
|
|
||||||
- [ ] 通过 WebSocket 推送进度更新：
|
|
||||||
|
|
||||||
```json
|
|
||||||
{"type": "import_progress", "step": "parsing", "message": "正在解析 OpenAPI 规范..."}
|
|
||||||
{"type": "import_progress", "step": "classifying", "message": "正在分析端点 12/50..."}
|
|
||||||
{"type": "import_progress", "step": "generating", "message": "正在生成 MCP 服务器..."}
|
|
||||||
{"type": "import_progress", "step": "review", "message": "分析完成，请审核分类结果", "review_url": "/review/abc123"}
|
|
||||||
{"type": "import_progress", "step": "done", "message": "导入完成！新增 3 个 Agent，15 个工具"}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] 导入期间聊天功能不受影响
|
|
||||||
- [ ] 导入失败 → 推送错误消息 + 错误详情
|
|
||||||
|
|
||||||
### 8. 测试
|
|
||||||
|
|
||||||
- [ ] **SSRF 测试：** 私有 IP (10.x, 172.16.x, 192.168.x) → 拦截
|
|
||||||
- [ ] **SSRF 测试：** localhost / 127.0.0.1 → 拦截
|
|
||||||
- [ ] **SSRF 测试：** 169.254.169.254（云元数据）→ 拦截
|
|
||||||
- [ ] **SSRF 测试：** 合法公网 URL → 放行
|
|
||||||
- [ ] **SSRF 测试：** file:// 协议 → 拦截
|
|
||||||
- [ ] **解析测试：** 有效 OpenAPI 3.0 JSON → 正确解析端点
|
|
||||||
- [ ] **解析测试：** 有效 OpenAPI 3.0 YAML → 正确解析端点
|
|
||||||
- [ ] **解析测试：** 无效规范 → 明确错误信息
|
|
||||||
- [ ] **解析测试：** 大型规范（100+ 端点）→ 不超时
|
|
||||||
- [ ] **生成测试：** 端点 → MCP tool 定义（名称、参数、描述匹配）
|
|
||||||
- [ ] **分类测试：** mock LLM 响应 → 正确解析分类结果
|
|
||||||
- [ ] **分类测试：** GET 端点 → 默认 read，DELETE 端点 → 默认 write
|
|
||||||
- [ ] **集成测试：** 完整流程：URL → 解析 → 分类 → 生成 → 注册
|
|
||||||
- [ ] **E2E 测试：** 粘贴 spec URL → 进度更新 → 审核 → 新工具在聊天中可用
|
|
||||||
|
|
||||||
## 技术要点
|
|
||||||
|
|
||||||
| 功能 | 技术选型 | 说明 |
|
|
||||||
|------|---------|------|
|
|
||||||
| 规范验证 | openapi-spec-validator | PyPI 包，支持 3.0+ |
|
|
||||||
| URL 获取 | httpx + SSRF 模块 | 异步 HTTP，IP 检查 |
|
|
||||||
| MCP 生成 | mcp SDK (Python) | 生成 stdio MCP 服务器 |
|
|
||||||
| LLM 分类 | ChatAnthropic structured output | JSON mode 确保输出格式 |
|
|
||||||
| 异步任务 | asyncio.create_task | FastAPI 内后台任务 |
|
|
||||||
|
|
||||||
## 风险与缓解
|
|
||||||
|
|
||||||
| 风险 | 影响 | 缓解措施 |
|
|
||||||
|------|------|---------|
|
|
||||||
| LLM 分类不准确 | 读操作被标记为写（多余确认）或反之（危险） | 运维审核 UI 作为安全网，默认偏向标记为 write |
|
|
||||||
| 复杂 request body 无法处理 | 部分端点工具不可用 | 跳过无法处理的端点，在审核 UI 中标注 |
|
|
||||||
| DNS 重绑定绕过 SSRF | 安全漏洞 | 解析后绑定 IP 发请求，不二次解析 |
|
|
||||||
| 大规范生成慢 | 用户等待久 | 异步 + 进度条，分批生成 |
|
|
||||||
|
|
||||||
## Related
|
## Related
|
||||||
|
|
||||||
|
|||||||
42
2 - Projects/Smart Support/Phase 3 Dev Log.md
Normal file
42
2 - Projects/Smart Support/Phase 3 Dev Log.md
Normal file
@@ -0,0 +1,42 @@
|
|||||||
|
---
|
||||||
|
created: 2026-04-06
|
||||||
|
type: log
|
||||||
|
project: "[[Smart Support]]"
|
||||||
|
source: docs/phases/phase-3-dev-log.md
|
||||||
|
tags:
|
||||||
|
- dev-log
|
||||||
|
- phase-3
|
||||||
|
- openapi
|
||||||
|
- ssrf
|
||||||
|
- code-generation
|
||||||
|
- llm-classification
|
||||||
|
---
|
||||||
|
|
||||||
|
# Phase 3: OpenAPI Auto-Discovery -- Development Log
|
||||||
|
|
||||||
|
> Status: COMPLETED
|
||||||
|
> Phase branch: `phase-3/openapi-discovery`
|
||||||
|
> Date started: 2026-03-30
|
||||||
|
> Date completed: 2026-03-30
|
||||||
|
|
||||||
|
## What Was Built
|
||||||
|
|
||||||
|
- **SSRF 防护** (`openapi/ssrf.py`): 私有 IP 拦截、DNS 重绑定防御、重定向链验证。162 行，42 个测试。
|
||||||
|
- **规范获取** (`openapi/fetcher.py`): SSRF 安全获取，JSON/YAML 自动检测，10MB 限制。
|
||||||
|
- **规范验证** (`openapi/validator.py`): 结构化 OpenAPI 3.0.x/3.1.x 验证。
|
||||||
|
- **端点解析** (`openapi/parser.py`): $ref 解析、参数提取、自动 operationId。
|
||||||
|
- **端点分类** (`openapi/classifier.py`): 启发式（GET=read）+ LLM 分类器 + Protocol 接口。失败回退启发式。
|
||||||
|
- **审核 API** (`openapi/review_api.py`): 导入任务管理、分类审核、批准生成。180 行。
|
||||||
|
- **代码生成** (`openapi/generator.py`): @tool 装饰 async 函数 + httpx。157 行。
|
||||||
|
- **导入编排** (`openapi/importer.py`): fetch -> validate -> parse -> classify 全流程。
|
||||||
|
|
||||||
|
## Test Coverage
|
||||||
|
|
||||||
|
- New: 125 tests (118 unit + 7 integration)
|
||||||
|
- Total: 322 tests
|
||||||
|
- Coverage: 93.23%
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [[Smart Support]]
|
||||||
|
- [[Smart Support/Phase 3 - OpenAPI 自动发现]]
|
||||||
@@ -1,7 +1,8 @@
|
|||||||
---
|
---
|
||||||
created: 2026-03-29
|
created: 2026-03-29
|
||||||
|
updated: 2026-04-06
|
||||||
type: project
|
type: project
|
||||||
status: 未开始
|
status: COMPLETED (2026-03-31)
|
||||||
parent: "[[Smart Support]]"
|
parent: "[[Smart Support]]"
|
||||||
phase: 4
|
phase: 4
|
||||||
timeline: 第 6-7 周
|
timeline: 第 6-7 周
|
||||||
@@ -19,243 +20,57 @@ tags:
|
|||||||
|
|
||||||
# Phase 4：分析 + 回放
|
# Phase 4：分析 + 回放
|
||||||
|
|
||||||
|
> Status: COMPLETED (2026-03-31)
|
||||||
|
|
||||||
## 目标
|
## 目标
|
||||||
|
|
||||||
让客户看到 AI 客服的 ROI。对话回放让客户信任系统（看到 AI 为什么做了某个决定），分析仪表盘用数据证明价值（自动解决了多少问题、省了多少成本）。这个阶段结束时，Smart Support 是一个完整可演示的产品。
|
让客户看到 AI 客服的 ROI。对话回放让客户信任系统，分析仪表盘用数据证明价值。
|
||||||
|
|
||||||
## 前置条件
|
|
||||||
|
|
||||||
- [[Smart Support/Phase 1 - 核心框架]] 完成（PostgresSaver 已持久化所有 checkpoint 数据）
|
|
||||||
- [[Smart Support/Phase 3 - OpenAPI 自动发现]] 完成（有真实工具调用数据可分析）
|
|
||||||
- Token 用量统计回调已运行（Phase 1 实现）
|
|
||||||
|
|
||||||
## 阶段产出
|
## 阶段产出
|
||||||
|
|
||||||
- 对话回放页面：逐步展示 Agent 的决策过程
|
- 回放数据模型：StepType 枚举、ReplayStep、ReplayPage（冻结数据类）
|
||||||
- 分析仪表盘：解决率、Agent 使用率、升级率、每对话成本
|
- 检查点转换器：PostgresSaver JSONB -> 结构化 ReplayStep 时间线
|
||||||
- 数据驱动的 ROI 证明能力
|
- 回放 API：GET /api/conversations（分页列表）、GET /api/replay/{thread_id}（分页时间线）
|
||||||
|
- 分析数据模型：AgentUsage、InterruptStats、AnalyticsResult
|
||||||
|
- 分析事件记录器：Protocol 接口 + PostgresAnalyticsRecorder + NoOpAnalyticsRecorder
|
||||||
|
- 分析查询：resolution_rate、agent_usage、escalation_rate、cost_per_conversation、interrupt_stats
|
||||||
|
- 分析 API：GET /api/analytics?range=Xd
|
||||||
|
- DB 迁移：analytics_events 表 + conversations 列扩展
|
||||||
|
|
||||||
## 集成检查点
|
## 新增文件
|
||||||
|
|
||||||
第 7 周末验证：
|
| 文件 | 用途 |
|
||||||
1. 完成几轮对话后，打开回放页面 → 看到完整决策时间线
|
|------|------|
|
||||||
2. 分析仪表盘显示正确的解决率和成本数据
|
| `app/replay/models.py` | StepType, ReplayStep, ReplayPage |
|
||||||
3. 零数据状态（新部署）→ 仪表盘显示空状态引导
|
| `app/replay/transformer.py` | Checkpoint JSONB -> ReplayStep[] |
|
||||||
4. 200+ 轮对话的回放 → 分页正常，不卡顿
|
| `app/replay/api.py` | 回放 + 对话列表 API |
|
||||||
|
| `app/analytics/models.py` | AgentUsage, InterruptStats, AnalyticsResult |
|
||||||
|
| `app/analytics/event_recorder.py` | 记录器 Protocol + 实现 |
|
||||||
|
| `app/analytics/queries.py` | SQL 查询 + get_analytics 聚合 |
|
||||||
|
| `app/analytics/api.py` | 分析 API 路由 |
|
||||||
|
|
||||||
---
|
## 分析指标
|
||||||
|
|
||||||
## 任务清单
|
| 指标 | 计算方式 |
|
||||||
|
|------|---------|
|
||||||
|
| 解决率 | 成功工具调用 + 未升级 / 总对话数 |
|
||||||
|
| Agent 使用率 | 每 Agent 路由次数占比 |
|
||||||
|
| 升级率 | 触发 Webhook 对话占比 |
|
||||||
|
| 每对话成本 | Token 用量 x 价格 |
|
||||||
|
| 中断统计 | approved/rejected/expired 分布 |
|
||||||
|
|
||||||
### 1. 对话回放 API
|
## 测试覆盖
|
||||||
|
|
||||||
- [ ] 端点 `GET /api/conversations` → 对话列表（分页）
|
- 新增测试：74 个
|
||||||
- 返回：`thread_id`, 开始时间, 消息数, 最终状态（resolved/escalated/abandoned）
|
- 总测试：399
|
||||||
- 支持筛选：按状态、按日期范围、按 agent
|
- 覆盖率：92.87%
|
||||||
- 分页参数：`page`, `page_size`（默认 20）
|
- 所有新模块覆盖率 81-100%
|
||||||
|
|
||||||
- [ ] 端点 `GET /api/replay/{thread_id}` → 单个对话的回放数据（分页）
|
## 与计划的偏差
|
||||||
- 查询 PostgresSaver checkpoint 表，按 checkpoint_id 排序
|
|
||||||
- 每个 checkpoint 解析为结构化时间线事件：
|
|
||||||
|
|
||||||
```json
|
- 前端页面推迟到 Phase 5
|
||||||
{
|
- ws_handler 事件记录推迟（注册 NoOpAnalyticsRecorder）
|
||||||
"thread_id": "uuid",
|
- conversations.agents_used 列未填充
|
||||||
"total_steps": 15,
|
|
||||||
"page": 1,
|
|
||||||
"page_size": 50,
|
|
||||||
"events": [
|
|
||||||
{
|
|
||||||
"step": 1,
|
|
||||||
"timestamp": "2026-04-10T14:30:00Z",
|
|
||||||
"type": "user_message",
|
|
||||||
"content": "查询订单 1042 的状态"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"step": 2,
|
|
||||||
"timestamp": "2026-04-10T14:30:01Z",
|
|
||||||
"type": "routing",
|
|
||||||
"agent": "order_lookup",
|
|
||||||
"reasoning": "用户请求查询订单状态"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"step": 3,
|
|
||||||
"timestamp": "2026-04-10T14:30:02Z",
|
|
||||||
"type": "tool_call",
|
|
||||||
"agent": "order_lookup",
|
|
||||||
"tool": "get_order_status",
|
|
||||||
"input": {"order_id": "1042"},
|
|
||||||
"output": {"status": "shipped", "tracking": "SF1234567"},
|
|
||||||
"duration_ms": 230
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"step": 4,
|
|
||||||
"timestamp": "2026-04-10T14:30:03Z",
|
|
||||||
"type": "agent_response",
|
|
||||||
"agent": "order_lookup",
|
|
||||||
"content": "您的订单 1042 已发货，运单号 SF1234567",
|
|
||||||
"tokens": {"input": 450, "output": 35}
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- 分页：`page` + `page_size` 控制每页 events 数量
|
|
||||||
- thread 不存在 → 404
|
|
||||||
|
|
||||||
- [ ] 端点 `GET /api/replay/{thread_id}/summary` → 对话摘要
|
|
||||||
- 总步骤数、涉及的 agents、工具调用次数、总 token 用量、总耗时、最终状态
|
|
||||||
|
|
||||||
### 2. 对话回放 UI
|
|
||||||
|
|
||||||
- [ ] 对话列表页：
|
|
||||||
- 表格显示所有对话（时间、消息数、状态、涉及 agent）
|
|
||||||
- 状态标签：🟢 已解决 / 🟡 已升级 / ⚫ 已放弃
|
|
||||||
- 点击进入回放详情
|
|
||||||
|
|
||||||
- [ ] 回放详情页：
|
|
||||||
- 左侧：原始聊天记录（用户消息 + AI 回复）
|
|
||||||
- 右侧：决策时间线（路由决策、工具调用、参数、返回值、耗时）
|
|
||||||
- 时间线高亮：
|
|
||||||
- 工具调用 → 蓝色
|
|
||||||
- interrupt 确认 → 黄色
|
|
||||||
- 错误/升级 → 红色
|
|
||||||
- 每个步骤可展开查看详细信息（工具输入输出、token 用量）
|
|
||||||
- 支持键盘导航（上/下箭头逐步浏览）
|
|
||||||
|
|
||||||
- [ ] 长对话分页加载（滚动加载或分页按钮）
|
|
||||||
|
|
||||||
### 3. 分析数据查询
|
|
||||||
|
|
||||||
- [ ] 数据来源：PostgresSaver checkpoint 表 + token 用量表
|
|
||||||
- [ ] 核心指标计算：
|
|
||||||
|
|
||||||
**解决率**
|
|
||||||
```sql
|
|
||||||
-- resolved = 至少一次成功工具调用 且 未触发升级
|
|
||||||
resolved_count / total_conversations * 100
|
|
||||||
```
|
|
||||||
|
|
||||||
**Agent 使用率**
|
|
||||||
```sql
|
|
||||||
-- 每个 agent 被路由到的次数占总路由次数的百分比
|
|
||||||
SELECT agent_name, COUNT(*) * 100.0 / total_routes AS usage_pct
|
|
||||||
```
|
|
||||||
|
|
||||||
**升级率**
|
|
||||||
```sql
|
|
||||||
-- 触发 webhook 升级的对话占总对话的百分比
|
|
||||||
escalated_count / total_conversations * 100
|
|
||||||
```
|
|
||||||
|
|
||||||
**每对话成本**
|
|
||||||
```sql
|
|
||||||
-- 基于 token 用量计算
|
|
||||||
SELECT thread_id,
|
|
||||||
SUM(input_tokens) * input_price + SUM(output_tokens) * output_price AS cost
|
|
||||||
```
|
|
||||||
|
|
||||||
**对话量趋势**
|
|
||||||
```sql
|
|
||||||
-- 按天/周/月聚合对话数量
|
|
||||||
SELECT DATE(created_at) AS date, COUNT(DISTINCT thread_id) AS conversations
|
|
||||||
GROUP BY date ORDER BY date
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] 时间范围筛选：今天 / 7 天 / 30 天 / 自定义
|
|
||||||
- [ ] 所有查询加索引优化（checkpoint 表的 thread_id + timestamp）
|
|
||||||
|
|
||||||
### 4. 分析仪表盘 API
|
|
||||||
|
|
||||||
- [ ] 端点 `GET /api/analytics/overview` → 概览数据
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"period": "last_7_days",
|
|
||||||
"total_conversations": 142,
|
|
||||||
"resolution_rate": 73.2,
|
|
||||||
"escalation_rate": 12.7,
|
|
||||||
"avg_cost_per_conversation": 0.045,
|
|
||||||
"total_cost": 6.39,
|
|
||||||
"avg_messages_per_conversation": 4.2,
|
|
||||||
"avg_resolution_time_seconds": 45
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] 端点 `GET /api/analytics/agents` → Agent 使用分布
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"agents": [
|
|
||||||
{"name": "order_lookup", "usage_pct": 45.3, "resolution_rate": 89.1},
|
|
||||||
{"name": "order_actions", "usage_pct": 30.2, "resolution_rate": 72.5},
|
|
||||||
{"name": "discount", "usage_pct": 15.8, "resolution_rate": 65.0},
|
|
||||||
{"name": "fallback", "usage_pct": 8.7, "resolution_rate": 20.0}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
- [ ] 端点 `GET /api/analytics/trend` → 对话量趋势（按日）
|
|
||||||
- [ ] 端点 `GET /api/analytics/costs` → 成本趋势 + 按 agent 成本分布
|
|
||||||
- [ ] 所有端点支持 `period` 参数（`today`, `7d`, `30d`, `custom`）
|
|
||||||
|
|
||||||
### 5. 分析仪表盘 UI
|
|
||||||
|
|
||||||
- [ ] 概览卡片（顶部）：
|
|
||||||
- 解决率（百分比 + 趋势箭头）
|
|
||||||
- 总对话数
|
|
||||||
- 升级率
|
|
||||||
- 平均成本/对话
|
|
||||||
- [ ] Agent 使用分布（饼图或条形图）
|
|
||||||
- [ ] 对话量趋势（折线图，按日）
|
|
||||||
- [ ] 成本趋势（折线图，按日）
|
|
||||||
- [ ] 零数据状态：
|
|
||||||
- 没有对话数据时，显示引导页面：「开始你的第一次对话，数据将在这里展示」
|
|
||||||
- 卡片显示 "—" 而非 0 或 NaN
|
|
||||||
|
|
||||||
### 6. 对话状态判定
|
|
||||||
|
|
||||||
- [ ] 实现对话最终状态判定逻辑：
|
|
||||||
- **resolved**：至少一次成功工具调用 + 未触发升级 webhook
|
|
||||||
- **escalated**：触发了升级 webhook
|
|
||||||
- **abandoned**：最后一条消息是用户发送的，且超过 30 分钟无后续（session TTL 过期）
|
|
||||||
- [ ] 状态写入 checkpoint metadata 或独立表
|
|
||||||
- [ ] 状态判定在对话结束时（WebSocket 断开 或 TTL 过期）异步执行
|
|
||||||
|
|
||||||
### 7. 测试
|
|
||||||
|
|
||||||
- [ ] **回放 API 测试：** 有效 thread_id → 返回结构化时间线
|
|
||||||
- [ ] **回放 API 测试：** 不存在的 thread_id → 404
|
|
||||||
- [ ] **回放 API 测试：** 大对话（200+ 步骤）→ 分页正常
|
|
||||||
- [ ] **回放 API 测试：** 时间线事件类型覆盖（user_message, routing, tool_call, agent_response, interrupt, error）
|
|
||||||
- [ ] **分析 API 测试：** overview 返回正确的解决率计算
|
|
||||||
- [ ] **分析 API 测试：** agent 使用分布百分比之和 = 100%
|
|
||||||
- [ ] **分析 API 测试：** 成本计算准确（基于 token 用量 × 价格）
|
|
||||||
- [ ] **分析 API 测试：** 时间范围筛选正确
|
|
||||||
- [ ] **零数据测试：** 无对话 → 所有指标返回合理默认值（非 NaN/null）
|
|
||||||
- [ ] **状态判定测试：** 成功工具调用 + 无升级 → resolved
|
|
||||||
- [ ] **状态判定测试：** 触发 webhook → escalated
|
|
||||||
- [ ] **状态判定测试：** 用户最后发言 + 超时 → abandoned
|
|
||||||
- [ ] **E2E 测试：** 完成对话 → 回放页面正确展示 → 仪表盘数据更新
|
|
||||||
|
|
||||||
## 技术要点
|
|
||||||
|
|
||||||
| 功能 | 实现方式 | 说明 |
|
|
||||||
|------|---------|------|
|
|
||||||
| 回放数据 | PostgresSaver checkpoint 表查询 | 按 thread_id + checkpoint_id 排序 |
|
|
||||||
| 分页 | OFFSET/LIMIT 或 cursor-based | 大数据量用 cursor |
|
|
||||||
| 图表 | Recharts 或 Chart.js | React 图表库 |
|
|
||||||
| 索引 | checkpoint 表加 thread_id + created_at 索引 | 保证查询性能 |
|
|
||||||
| 状态判定 | 异步任务 | WebSocket 断开或 TTL 到期时触发 |
|
|
||||||
|
|
||||||
## 风险与缓解
|
|
||||||
|
|
||||||
| 风险 | 影响 | 缓解措施 |
|
|
||||||
|------|------|---------|
|
|
||||||
| Checkpoint 数据格式变化 | 回放解析失败 | 版本化 checkpoint 格式，解析失败降级显示原始数据 |
|
|
||||||
| 大量对话数据查询慢 | 仪表盘加载慢 | 加索引 + 预聚合热门查询（物化视图） |
|
|
||||||
| 解决率定义不准确 | 指标误导 | 可配置定义，后续加入客户满意度信号 |
|
|
||||||
| Token 价格变化 | 成本计算不准 | 价格配置化，支持不同模型不同价格 |
|
|
||||||
|
|
||||||
## Related
|
## Related
|
||||||
|
|
||||||
|
|||||||
41
2 - Projects/Smart Support/Phase 4 Dev Log.md
Normal file
41
2 - Projects/Smart Support/Phase 4 Dev Log.md
Normal file
@@ -0,0 +1,41 @@
|
|||||||
|
---
|
||||||
|
created: 2026-04-06
|
||||||
|
type: log
|
||||||
|
project: "[[Smart Support]]"
|
||||||
|
source: docs/phases/phase-4-dev-log.md
|
||||||
|
tags:
|
||||||
|
- dev-log
|
||||||
|
- phase-4
|
||||||
|
- analytics
|
||||||
|
- replay
|
||||||
|
- postgresql
|
||||||
|
---
|
||||||
|
|
||||||
|
# Phase 4: Conversation Replay + Analytics -- Development Log
|
||||||
|
|
||||||
|
> Status: COMPLETED
|
||||||
|
> Phase branch: `phase-4/analytics-replay`
|
||||||
|
> Date started: 2026-03-31
|
||||||
|
> Date completed: 2026-03-31
|
||||||
|
|
||||||
|
## What Was Built
|
||||||
|
|
||||||
|
- **回放模型**: StepType 枚举、ReplayStep、ReplayPage 冻结数据类。
|
||||||
|
- **检查点转换器** (`replay/transformer.py`): PostgresSaver JSONB -> 结构化 ReplayStep 时间线。
|
||||||
|
- **回放 API** (`replay/api.py`): GET /api/conversations（分页列表）、GET /api/replay/{thread_id}（分页时间线，默认 20 步）。
|
||||||
|
- **分析模型**: AgentUsage、InterruptStats、AnalyticsResult。
|
||||||
|
- **事件记录器** (`analytics/event_recorder.py`): AnalyticsRecorder Protocol + PostgresAnalyticsRecorder + NoOpAnalyticsRecorder。
|
||||||
|
- **分析查询** (`analytics/queries.py`): resolution_rate, agent_usage, escalation_rate, cost_per_conversation, interrupt_stats。
|
||||||
|
- **分析 API** (`analytics/api.py`): GET /api/analytics?range=Xd。
|
||||||
|
- **DB 迁移**: analytics_events 表 + conversations 列扩展（resolution_type, agents_used, turn_count, ended_at）。
|
||||||
|
|
||||||
|
## Test Coverage
|
||||||
|
|
||||||
|
- New: 74 tests
|
||||||
|
- Total: 399 tests
|
||||||
|
- Coverage: 92.87%
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [[Smart Support]]
|
||||||
|
- [[Smart Support/Phase 4 - 分析 + 回放]]
|
||||||
@@ -1,7 +1,8 @@
|
|||||||
---
|
---
|
||||||
created: 2026-03-29
|
created: 2026-03-29
|
||||||
|
updated: 2026-04-06
|
||||||
type: project
|
type: project
|
||||||
status: 未开始
|
status: COMPLETED (2026-03-31)
|
||||||
parent: "[[Smart Support]]"
|
parent: "[[Smart Support]]"
|
||||||
phase: 5
|
phase: 5
|
||||||
timeline: 缓冲周
|
timeline: 缓冲周
|
||||||
@@ -14,97 +15,78 @@ tags:
|
|||||||
- documentation
|
- documentation
|
||||||
- edge-cases
|
- edge-cases
|
||||||
- e2e-testing
|
- e2e-testing
|
||||||
|
- frontend
|
||||||
|
- rate-limiting
|
||||||
---
|
---
|
||||||
|
|
||||||
# Phase 5：打磨 + 演示准备
|
# Phase 5：打磨 + 演示准备
|
||||||
|
|
||||||
|
> Status: COMPLETED (2026-03-31)
|
||||||
|
|
||||||
## 目标
|
## 目标
|
||||||
|
|
||||||
将 Smart Support 从「能跑」变成「能演示给客户看」。修复所有边界情况，准备演示数据和脚本，确保一键部署流程顺畅。这个阶段结束时，能录一个 90 秒的产品演示视频。
|
将 Smart Support 从「能跑」变成「能演示给客户看」。修复所有边界情况，准备演示数据和脚本，确保一键部署流程顺畅。
|
||||||
|
|
||||||
## 前置条件
|
|
||||||
|
|
||||||
- [[Smart Support/Phase 4 - 分析 + 回放]] 完成
|
|
||||||
- 所有核心功能端到端可用
|
|
||||||
|
|
||||||
## 阶段产出
|
## 阶段产出
|
||||||
|
|
||||||
- 错误处理覆盖所有已知边界情况
|
### 后端
|
||||||
- 演示脚本 + 真实感的示例数据
|
|
||||||
- Docker Compose 全栈一键部署
|
|
||||||
- 90 秒产品演示视频
|
|
||||||
|
|
||||||
---
|
- **对话追踪器** (`conversation_tracker.py`)：Protocol + PostgresConversationTracker + NoOpConversationTracker，生命周期管理（ensure, record_turn, resolve）
|
||||||
|
- **错误处理** (`tools/error_handler.py`)：ErrorCategory 枚举、classify_error()、with_retry() 指数退避（仅重试可重试错误）
|
||||||
|
- **WebSocket 加固** (`ws_handler.py`)：
|
||||||
|
- analytics_recorder + conversation_tracker + pool 参数
|
||||||
|
- _fire_and_forget_tracking 异步追踪
|
||||||
|
- 速率限制（10 msg/10s per thread）
|
||||||
|
- 空白消息检查、JSON 数组拒绝、10000 字符限制
|
||||||
|
- **健康检查**：GET /api/health
|
||||||
|
- **演示数据**：demo_data.py 种子脚本 + sample_openapi.yaml
|
||||||
|
|
||||||
## 任务清单
|
### 前端（全部页面实现）
|
||||||
|
|
||||||
### 1. 错误处理加固
|
- **API 客户端** (`api.ts`)：fetchConversations, fetchReplay, fetchAnalytics 类型化封装
|
||||||
|
- **导航** (`NavBar.tsx` + `Layout.tsx`)：水平导航 + App Shell
|
||||||
|
- **错误提示** (`ErrorBanner.tsx`)：断线状态 + 重连按钮
|
||||||
|
- **分析组件** (`MetricCard.tsx`)：可复用指标卡片
|
||||||
|
- **回放组件** (`ReplayTimeline.tsx`)：垂直时间线 + 可展开步骤详情
|
||||||
|
- **页面**：
|
||||||
|
- `ChatPage.tsx` -- 聊天（集成 ErrorBanner）
|
||||||
|
- `ReplayListPage.tsx` -- 对话列表（分页）
|
||||||
|
- `ReplayPage.tsx` -- 回放时间线
|
||||||
|
- `DashboardPage.tsx` -- 分析仪表盘（范围选择、零状态处理）
|
||||||
|
- `ReviewPage.tsx` -- OpenAPI 导入表单 + 任务轮询 + 可编辑分类表
|
||||||
|
|
||||||
- [ ] 审查所有 API 端点，确保每个都有明确的错误响应
|
### 基础设施
|
||||||
- [ ] LLM API 超时 → 用户收到「AI 正在思考中，请稍候...」→ 15 秒后仍无响应 → 「抱歉，处理超时，请重试」
|
|
||||||
- [ ] WebSocket 异常断开 → 前端自动重连（最多 3 次，间隔 1s/2s/4s）→ 重连失败 → 提示刷新页面
|
|
||||||
- [ ] MCP 工具调用失败 → 「该操作暂时不可用，已通知技术团队」
|
|
||||||
- [ ] 非预期错误 → 统一错误格式，不暴露堆栈信息
|
|
||||||
- [ ] 所有错误记录详细日志（structlog / JSON 格式）
|
|
||||||
|
|
||||||
### 2. 演示数据
|
- `frontend/Dockerfile` -- 多阶段构建（node:20-alpine -> nginx:alpine）
|
||||||
|
- `frontend/nginx.conf` -- SPA 路由 + WebSocket/API 代理
|
||||||
|
- `docker-compose.yml` -- 新增 frontend 服务、健康检查、app_network
|
||||||
|
- `.env.example` -- Docker Compose 环境模板
|
||||||
|
|
||||||
- [ ] 创建模拟电商数据集：
|
### 文档
|
||||||
- 20 个订单（不同状态：待付款、已付款、已发货、已完成、已取消）
|
|
||||||
- 5 个客户（含姓名、邮箱、订单历史）
|
|
||||||
- 3 个优惠活动（满减、折扣码、新人券）
|
|
||||||
- 物流追踪信息（不同快递公司、不同状态）
|
|
||||||
- [ ] Mock 工具返回对应数据（根据 order_id 查表返回）
|
|
||||||
- [ ] 数据感觉真实（合理的金额、日期、商品名称）
|
|
||||||
|
|
||||||
### 3. 演示脚本
|
- `docs/demo-script.md` -- 10 分钟演示脚本（5 个场景）
|
||||||
|
- `docs/agent-config-guide.md` -- agents.yaml 参考
|
||||||
|
- `docs/openapi-import-guide.md` -- 导入工作流 + SSRF 防护
|
||||||
|
- `docs/deployment.md` -- Docker Compose 部署 + 生产考虑
|
||||||
|
- `README.md` -- 完整项目概述 + 快速启动
|
||||||
|
|
||||||
- [ ] 编写演示对话脚本（覆盖核心功能）：
|
## 测试覆盖
|
||||||
|
|
||||||
**场景 1：订单查询（30 秒）**
|
- 新增测试：42 个（conversation_tracker 13 + error_handler 19 + edge_cases 10）
|
||||||
> 用户：「我的订单 1042 到哪了？」
|
- 总测试：449（后续工程审查后增至 516）
|
||||||
> Agent：查询 → 返回物流信息 + 预计到达时间
|
- 覆盖率：92.88%
|
||||||
|
|
||||||
**场景 2：取消订单 + 人工确认（30 秒）**
|
## 与计划的偏差
|
||||||
> 用户：「帮我取消订单 1043」
|
|
||||||
> Agent：确认提示 → 用户批准 → 取消成功
|
|
||||||
|
|
||||||
**场景 3：OpenAPI 导入（30 秒）**
|
- MAX_CONTENT_LENGTH 从 8000 改为 10000（匹配计划规格）
|
||||||
> 粘贴 OpenAPI URL → 进度条 → 审核分类 → 新工具可用 → 用新工具完成操作
|
- _thread_timestamps 模块级别，添加 autouse fixture 清理测试间状态
|
||||||
|
- 异步追踪用 await 而非后台任务（WebSocket 循环已是 async）
|
||||||
|
|
||||||
- [ ] 准备一个公开可用的 OpenAPI spec URL 用于演示（或自建 mock API + spec）
|
## 技术债务
|
||||||
- [ ] 录制脚本的文字版，标注每个步骤的预期画面
|
|
||||||
|
|
||||||
### 4. Docker Compose 全栈部署
|
- main.py 覆盖率 48%（启动路径需真实 DB）
|
||||||
|
- 速率限制进程全局（多 Worker 需 Redis）
|
||||||
- [ ] 更新 `docker-compose.yml`：
|
- conversations 表 schema 假设已存在
|
||||||
- PostgreSQL 16（带数据持久化 volume）
|
|
||||||
- FastAPI 后端（含 uvicorn）
|
|
||||||
- React 前端（nginx 托管构建产物）
|
|
||||||
- 环境变量通过 `.env` 文件注入
|
|
||||||
- [ ] 创建 `Dockerfile`（后端）和 `Dockerfile`（前端）
|
|
||||||
- [ ] 健康检查：PostgreSQL ready → 后端启动 → 前端可访问
|
|
||||||
- [ ] `docker compose up` 一键启动，无需手动操作
|
|
||||||
- [ ] 编写部署文档（README 中的快速开始部分）
|
|
||||||
|
|
||||||
### 5. 90 秒演示视频
|
|
||||||
|
|
||||||
- [ ] 按演示脚本录制屏幕
|
|
||||||
- [ ] 要点：
|
|
||||||
- 开头 5 秒：一句话说明产品（「粘贴你的 API，获得一个能执行操作的 AI 客服」）
|
|
||||||
- 展示速度：聊天流式输出的流畅感
|
|
||||||
- 展示信任：人工确认流程
|
|
||||||
- 展示魔法：OpenAPI 导入（粘贴 URL → 自动可用）
|
|
||||||
- 展示价值：分析仪表盘（解决率、成本）
|
|
||||||
- [ ] 视频放到可分享的位置（YouTube unlisted 或直接托管）
|
|
||||||
|
|
||||||
### 6. 最终测试
|
|
||||||
|
|
||||||
- [ ] 全量 E2E 测试通过
|
|
||||||
- [ ] `pytest --cov` → 80%+ 覆盖率
|
|
||||||
- [ ] 全新环境 `docker compose up` → 所有功能正常
|
|
||||||
- [ ] 在不同网络环境测试（本地、云服务器）
|
|
||||||
- [ ] 演示脚本完整跑通 3 次无报错
|
|
||||||
|
|
||||||
## Related
|
## Related
|
||||||
|
|
||||||
|
|||||||
56
2 - Projects/Smart Support/Phase 5 Dev Log.md
Normal file
56
2 - Projects/Smart Support/Phase 5 Dev Log.md
Normal file
@@ -0,0 +1,56 @@
|
|||||||
|
---
|
||||||
|
created: 2026-04-06
|
||||||
|
type: log
|
||||||
|
project: "[[Smart Support]]"
|
||||||
|
source: docs/phases/phase-5-dev-log.md
|
||||||
|
tags:
|
||||||
|
- dev-log
|
||||||
|
- phase-5
|
||||||
|
- error-handling
|
||||||
|
- frontend
|
||||||
|
- docker
|
||||||
|
- demo
|
||||||
|
- rate-limiting
|
||||||
|
---
|
||||||
|
|
||||||
|
# Phase 5: Polish + Demo Prep -- Development Log
|
||||||
|
|
||||||
|
> Status: COMPLETED
|
||||||
|
> Phase branch: `phase-5/polish-demo`
|
||||||
|
> Date started: 2026-03-30
|
||||||
|
> Date completed: 2026-03-30
|
||||||
|
|
||||||
|
## What Was Built
|
||||||
|
|
||||||
|
### 后端
|
||||||
|
- **对话追踪器** (`conversation_tracker.py`): Protocol + PostgresConversationTracker + NoOpConversationTracker。ensure, record_turn, resolve 生命周期管理。
|
||||||
|
- **错误处理** (`tools/error_handler.py`): ErrorCategory 枚举（RETRYABLE/PERMANENT/EXTERNAL/UNKNOWN）、classify_error()、with_retry() 指数退避。
|
||||||
|
- **WebSocket 加固**: 速率限制 10 msg/10s、空白消息检查、JSON 数组拒绝、10000 字符限制、fire-and-forget 追踪。
|
||||||
|
- **健康检查**: GET /api/health。
|
||||||
|
- **演示数据**: demo_data.py + sample_openapi.yaml。
|
||||||
|
|
||||||
|
### 前端（完整实现）
|
||||||
|
- API 客户端、导航栏、App Shell
|
||||||
|
- 5 个页面：Chat、ReplayList、Replay、Dashboard、Review
|
||||||
|
- ErrorBanner 断线提示 + 重连
|
||||||
|
- MetricCard + ReplayTimeline 组件
|
||||||
|
- WebSocket reconnect() + onDisconnect/onReconnect 回调
|
||||||
|
|
||||||
|
### 基础设施
|
||||||
|
- Frontend Dockerfile（多阶段构建）
|
||||||
|
- nginx.conf（SPA + WS/API 代理）
|
||||||
|
- Docker Compose 全栈（PostgreSQL + Backend + Frontend）
|
||||||
|
|
||||||
|
### 文档
|
||||||
|
- 演示脚本、Agent 配置指南、OpenAPI 导入指南、部署文档、README
|
||||||
|
|
||||||
|
## Test Coverage
|
||||||
|
|
||||||
|
- New: 42 tests
|
||||||
|
- Total: 449 (后续工程审查增至 516)
|
||||||
|
- Coverage: 92.88%
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [[Smart Support]]
|
||||||
|
- [[Smart Support/Phase 5 - 打磨 + 演示]]
|
||||||
239
4 - Resources/Claude-Code/Autonomous Agent Harness 自主代理框架.md
Normal file
239
4 - Resources/Claude-Code/Autonomous Agent Harness 自主代理框架.md
Normal file
@@ -0,0 +1,239 @@
|
|||||||
|
---
|
||||||
|
created: "2026-04-06"
|
||||||
|
type: resource
|
||||||
|
tags: [resource, claude-code, AI-tools, autonomous-agent, agent-harness, ECC, windows-compatible]
|
||||||
|
source: "~/.claude/skills/autonomous-agent-harness/SKILL.md"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Autonomous Agent Harness 自主代理框架
|
||||||
|
|
||||||
|
把 Claude Code 变成持久化、自驱动的 Agent 系统，替代 AutoGPT/Hermes。核心理念：不需要额外框架，用 Claude Code 原生能力（crons + dispatch + MCP + memory）就能构建自主 Agent。
|
||||||
|
|
||||||
|
相关笔记：[[Autonomous Loops 自主循环模式]]、[[dmux 多Agent并行编排]]、[[ECC 编排替代方案 (orchestrate 迁移)]]
|
||||||
|
|
||||||
|
## 架构
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────┐
|
||||||
|
│ Claude Code Runtime │
|
||||||
|
│ │
|
||||||
|
│ Crons (定时) Dispatch (远程) Memory Computer Use │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ ▼ ▼ ▼ ▼ │
|
||||||
|
│ ┌───────────────────────────────────────────────┐ │
|
||||||
|
│ │ ECC Skill + Agent Layer │ │
|
||||||
|
│ │ autonomous-loops / eval-harness / santa... │ │
|
||||||
|
│ │ loop-operator / harness-optimizer agents │ │
|
||||||
|
│ └───────────────────────────────────────────────┘ │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ ▼ ▼ ▼ ▼ │
|
||||||
|
│ ┌───────────────────────────────────────────────┐ │
|
||||||
|
│ │ MCP Server Layer │ │
|
||||||
|
│ │ memory github exa browser-use ... │ │
|
||||||
|
│ └───────────────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5 大核心组件
|
||||||
|
|
||||||
|
### 1. 三层记忆系统
|
||||||
|
|
||||||
|
| 层级 | 机制 | 生命周期 | 用途 |
|
||||||
|
|------|------|----------|------|
|
||||||
|
| 短期 | `TodoWrite` | 单次会话内 | 任务追踪 |
|
||||||
|
| 中期 | `~/.claude/projects/*/memory/*.md` | 跨会话 | 项目上下文 |
|
||||||
|
| 长期 | MCP Memory Server (知识图谱) | 永久 | 实体、关系、观察 |
|
||||||
|
|
||||||
|
### 2. 定时操作 (Crons)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Claude Code 内置 cron 能力
|
||||||
|
# 例：每 30 分钟检查新 PR 并审查
|
||||||
|
Cron: every 30 min during work hours
|
||||||
|
1. Check for new PRs on watched repos
|
||||||
|
2. For each new PR: pull branch, run tests, review
|
||||||
|
3. Post review comments via GitHub MCP
|
||||||
|
4. Update memory with review status
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 远程 Agent (Dispatch)
|
||||||
|
|
||||||
|
通过 `claude dispatch` 或 remote trigger 启动远程 Agent 实例。
|
||||||
|
|
||||||
|
### 4. Computer Use (MCP)
|
||||||
|
|
||||||
|
通过 MCP browser/desktop 服务器实现屏幕交互、浏览器操作。
|
||||||
|
|
||||||
|
### 5. 任务队列
|
||||||
|
|
||||||
|
基于 memory 的持久化任务队列，跨会话保持任务状态。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 关键 Agent
|
||||||
|
|
||||||
|
### loop-operator
|
||||||
|
|
||||||
|
运行自主循环的安全操作员：
|
||||||
|
|
||||||
|
- 跟踪进度 checkpoint
|
||||||
|
- 检测停滞和重试风暴
|
||||||
|
- 失败重复时暂停并缩小范围
|
||||||
|
- 验证通过后才恢复
|
||||||
|
|
||||||
|
**升级条件**（任何一个为 true 则升级到人类）：
|
||||||
|
- 连续 2 个 checkpoint 无进展
|
||||||
|
- 重复相同 stack trace 的失败
|
||||||
|
- 成本漂移超出预算窗口
|
||||||
|
- merge 冲突阻塞队列
|
||||||
|
|
||||||
|
### harness-optimizer
|
||||||
|
|
||||||
|
优化 Agent 框架配置的专家：
|
||||||
|
|
||||||
|
1. 运行 `/harness-audit` 收集基线分数
|
||||||
|
2. 识别 top 3 杠杆点（hooks, evals, routing, context, safety）
|
||||||
|
3. 提出最小可逆配置变更
|
||||||
|
4. 应用并验证
|
||||||
|
5. 报告前后对比
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 核心设计原则
|
||||||
|
|
||||||
|
### 1. Eval-First（评估先行）
|
||||||
|
|
||||||
|
执行前定义完成标准。Eval 是 "AI 开发的单元测试"。
|
||||||
|
|
||||||
|
```
|
||||||
|
目标 pass@3 > 90%
|
||||||
|
- 定义 capability eval (新功能能做什么)
|
||||||
|
- 定义 regression eval (不破坏已有功能)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. De-Sloppify（去粗糙化）
|
||||||
|
|
||||||
|
**永远不要给生成器加负面约束**（"不要做 X"）。让它自由生成，然后加独立清理 agent。
|
||||||
|
|
||||||
|
> 核心洞察：两个聚焦的 Agent 优于一个被约束的 Agent。
|
||||||
|
|
||||||
|
### 3. Santa Method（收敛循环）
|
||||||
|
|
||||||
|
```
|
||||||
|
Generator 生成
|
||||||
|
→ Reviewer A（安全+正确性）独立评估
|
||||||
|
→ Reviewer B（架构+测试）独立评估
|
||||||
|
→ 两者都 PASS 才算收敛
|
||||||
|
→ FAIL 则修复后用全新 Agent 重跑两个 Reviewer
|
||||||
|
→ 最多 3 轮，超过则上报人类
|
||||||
|
```
|
||||||
|
|
||||||
|
关键：Reviewer 从未看过 Generator 的推理过程，消除作者偏见。
|
||||||
|
|
||||||
|
### 4. 15 分钟单元规则
|
||||||
|
|
||||||
|
每个任务单元必须：
|
||||||
|
- 独立可验证
|
||||||
|
- 单一主要风险
|
||||||
|
- 明确的完成条件
|
||||||
|
- 约 15 分钟可完成
|
||||||
|
|
||||||
|
### 5. 分离上下文窗口
|
||||||
|
|
||||||
|
每个管道阶段在独立 Agent 进程中运行。不同阶段用不同模型：
|
||||||
|
|
||||||
|
| 阶段 | 模型 |
|
||||||
|
|------|------|
|
||||||
|
| Research | Sonnet |
|
||||||
|
| Plan | Opus |
|
||||||
|
| Implement | Sonnet / Codex |
|
||||||
|
| Review | Opus |
|
||||||
|
|
||||||
|
### 6. 循环安全
|
||||||
|
|
||||||
|
- **必须有退出条件**：max-runs / max-cost / max-duration / completion signal
|
||||||
|
- **检测停滞和重试风暴**
|
||||||
|
- **质量门必须活跃**：eval baseline 必须存在
|
||||||
|
- **回滚路径必须存在**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Hermes 组件替代表
|
||||||
|
|
||||||
|
| Hermes 组件 | ECC 替代 |
|
||||||
|
|-------------|---------|
|
||||||
|
| Task Queue | MCP Memory + TodoWrite |
|
||||||
|
| Long-term Memory | MCP Memory Server (知识图谱) |
|
||||||
|
| Tool Execution | MCP Server Layer |
|
||||||
|
| Planning | /ecc:plan + /ecc:feature-dev |
|
||||||
|
| Scheduling | Claude Code Crons |
|
||||||
|
| Computer Use | MCP Playwright / Desktop |
|
||||||
|
| Web Browsing | MCP Browser + Exa Search |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Windows 可用性
|
||||||
|
|
||||||
|
| 组件 | Windows | 说明 |
|
||||||
|
|------|---------|------|
|
||||||
|
| 三层记忆 | 可用 | 文件系统 + MCP |
|
||||||
|
| Crons | 可用 | Claude Code 原生 |
|
||||||
|
| Dispatch | 可用 | Claude Code 原生 |
|
||||||
|
| loop-operator agent | 可用 | Claude Code 内部 |
|
||||||
|
| 外部脚本（auto-pilot.sh） | 可用 | Git Bash |
|
||||||
|
| dmux 并行编排 | **不可用** | 需要 tmux（Linux/Mac） |
|
||||||
|
|
||||||
|
Windows 上的并行替代：Claude Code 内置 Agent/Task tool 实现进程内并行子 agent。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 实际例子
|
||||||
|
|
||||||
|
### Sequential Pipeline（最常用）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
set -e
|
||||||
|
claude -p "读取 spec，实现功能，先写测试"
|
||||||
|
claude -p "审查改动，清理 slop，运行测试"
|
||||||
|
claude -p "运行构建 + lint + 测试，修复失败"
|
||||||
|
claude -p "创建 conventional commit"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cron 定时 PR 审查
|
||||||
|
|
||||||
|
```
|
||||||
|
Cron: 工作时间每 30 分钟
|
||||||
|
1. gh pr list --state open
|
||||||
|
2. 对每个 PR: 拉分支、运行测试、code-reviewer 审查
|
||||||
|
3. GitHub MCP 发布评论
|
||||||
|
4. memory 更新审查状态
|
||||||
|
```
|
||||||
|
|
||||||
|
### 带成本控制的持续循环
|
||||||
|
|
||||||
|
```bash
|
||||||
|
continuous-claude --prompt "为未测试函数添加单元测试" --max-runs 10
|
||||||
|
continuous-claude --prompt "修复所有 linter 错误" --max-cost 5.00
|
||||||
|
continuous-claude --prompt "提升测试覆盖率" --max-duration 8h
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 反模式
|
||||||
|
|
||||||
|
| 反模式 | 问题 | 正确做法 |
|
||||||
|
|--------|------|---------|
|
||||||
|
| 无退出条件的循环 | 无限烧钱 | 始终设 max-runs/max-cost |
|
||||||
|
| 单 agent 自审自 | 作者偏见 | Santa Method 双独立 reviewer |
|
||||||
|
| 用否定指令约束生成 | 质量下降 | De-Sloppify 独立 pass |
|
||||||
|
| 迭代间无上下文桥 | 重复劳动 | SHARED_TASK_NOTES.md |
|
||||||
|
| 所有阶段同一上下文 | 偏见累积 | 每阶段独立进程 |
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [[Autonomous Loops 自主循环模式]]
|
||||||
|
- [[dmux 多Agent并行编排]]
|
||||||
|
- [[Ralphinho RFC-DAG 编排模式]]
|
||||||
|
- [[ECC 编排替代方案 (orchestrate 迁移)]]
|
||||||
|
- [[Everything Claude Code 完整指南]]
|
||||||
@@ -9,7 +9,7 @@ source: "~/.claude/skills/autonomous-loops/SKILL.md"
|
|||||||
|
|
||||||
ECC 提供的让 Claude Code 在无人干预下持续循环工作的模式集合。v1.10.0 中 `autonomous-loops` 已标记为兼容保留，新的 canonical 名称是 `continuous-agent-loop`。
|
ECC 提供的让 Claude Code 在无人干预下持续循环工作的模式集合。v1.10.0 中 `autonomous-loops` 已标记为兼容保留，新的 canonical 名称是 `continuous-agent-loop`。
|
||||||
|
|
||||||
相关笔记：[[dmux 多Agent并行编排]]、[[Everything Claude Code 完整指南]]、[[Ralphinho RFC-DAG 编排模式]]
|
相关笔记：[[dmux 多Agent并行编排]]、[[Everything Claude Code 完整指南]]、[[Ralphinho RFC-DAG 编排模式]]、[[Autonomous Agent Harness 自主代理框架]]、[[ECC 编排替代方案 (orchestrate 迁移)]]
|
||||||
|
|
||||||
## 模式选择流程
|
## 模式选择流程
|
||||||
|
|
||||||
|
|||||||
285
4 - Resources/Claude-Code/ECC 编排替代方案 (orchestrate 迁移).md
Normal file
285
4 - Resources/Claude-Code/ECC 编排替代方案 (orchestrate 迁移).md
Normal file
@@ -0,0 +1,285 @@
|
|||||||
|
---
|
||||||
|
created: "2026-04-06"
|
||||||
|
updated: "2026-04-14"
|
||||||
|
type: resource
|
||||||
|
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"
|
||||||
|
---
|
||||||
|
|
||||||
|
# ECC 编排替代方案 (orchestrate 迁移)
|
||||||
|
|
||||||
|
`/ecc:orchestrate` 已标记为 legacy shim。底层委托给 `dmux-workflows`（需 tmux）和 `autonomous-agent-harness`（部分依赖 tmux）。Windows 上基本不可用。本文档记录迁移路径。
|
||||||
|
|
||||||
|
> **先看决策表**：见文末「一张表选编排方式」。
|
||||||
|
|
||||||
|
相关笔记：[[Autonomous Agent Harness 自主代理框架]]、[[Everything Claude Code 完整指南]]
|
||||||
|
|
||||||
|
## orchestrate 做了什么
|
||||||
|
|
||||||
|
原来的 `/ecc:orchestrate feature "描述"` 内部流程：
|
||||||
|
1. Plan（规划）
|
||||||
|
2. TDD（测试驱动开发）
|
||||||
|
3. Code Review（代码审查）
|
||||||
|
4. Security Review（安全审查）
|
||||||
|
5. Verify（验证）
|
||||||
|
|
||||||
|
接受参数：`feature`、`bugfix`、`refactor`、`security`、`custom`。
|
||||||
|
|
||||||
|
## 替代方案
|
||||||
|
|
||||||
|
### 路线 A：单功能/任务 — `/ecc:feature-dev`（推荐）
|
||||||
|
|
||||||
|
**orchestrate 的最直接替代品。** 7 阶段全在 Claude Code 内部完成：
|
||||||
|
|
||||||
|
```
|
||||||
|
/ecc:feature-dev "add JWT authentication"
|
||||||
|
```
|
||||||
|
|
||||||
|
内部自动走：
|
||||||
|
1. **Discovery** — 读取需求，识别约束和验收标准
|
||||||
|
2. **Codebase Exploration** — 用 `code-explorer` 分析相关代码
|
||||||
|
3. **Clarifying Questions** — 提出设计/边界问题，等用户回答
|
||||||
|
4. **Architecture Design** — 用 `code-architect` 设计，等用户批准
|
||||||
|
5. **Implementation** — TDD 实现，小粒度提交
|
||||||
|
6. **Quality Review** — 用 `code-reviewer` 审查，修复 critical/high 问题
|
||||||
|
7. **Summary** — 总结构建内容，列出跟进项
|
||||||
|
|
||||||
|
### 路线 B：手动拆步骤
|
||||||
|
|
||||||
|
如果想更精细控制每一步：
|
||||||
|
|
||||||
|
```
|
||||||
|
/ecc:plan "描述" # 规划，等确认
|
||||||
|
/ecc:tdd # RED → GREEN → REFACTOR
|
||||||
|
/ecc:code-review # 代码审查
|
||||||
|
/ecc:security-review # 安全审查（涉及 auth/支付时）
|
||||||
|
/ecc:verify # 构建 + 测试 + lint + 覆盖率
|
||||||
|
```
|
||||||
|
|
||||||
|
按工作类型选择组合：
|
||||||
|
|
||||||
|
| 工作类型 | 推荐组合 |
|
||||||
|
|----------|---------|
|
||||||
|
| 新功能 | `/ecc:feature-dev` 一条龙 |
|
||||||
|
| Bug 修复 | `/ecc:tdd` → `/ecc:code-review` |
|
||||||
|
| 重构 | `/ecc:plan` → `/ecc:tdd` → `/ecc:code-review` |
|
||||||
|
| 安全相关 | 任何组合 + `/ecc:security-review` |
|
||||||
|
| 最终验证 | `/ecc:verify` |
|
||||||
|
|
||||||
|
### 路线 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 原生可用。
|
||||||
|
|
||||||
|
**安装：**
|
||||||
|
```bash
|
||||||
|
npx get-shit-done-cc@latest
|
||||||
|
```
|
||||||
|
|
||||||
|
**单阶段执行：**
|
||||||
|
```
|
||||||
|
/gsd:discuss-phase 1 # 讨论实现决策
|
||||||
|
/gsd:plan-phase 1 # 研究 + 规划 + 验证
|
||||||
|
/gsd:execute-phase 1 # 按 wave 并行执行
|
||||||
|
/gsd:verify-work 1 # 验收测试
|
||||||
|
/gsd:ship 1 # 创建 PR
|
||||||
|
```
|
||||||
|
|
||||||
|
**全自动执行：**
|
||||||
|
```
|
||||||
|
/gsd:autonomous # 执行所有剩余阶段
|
||||||
|
/gsd:autonomous --from 6 # 从阶段 6 开始
|
||||||
|
```
|
||||||
|
|
||||||
|
**GSD 完整生命周期：**
|
||||||
|
```
|
||||||
|
/gsd:new-project # 初始化（研究 → 需求 → 路线图）
|
||||||
|
/gsd:plan-phase 1 # 规划阶段 1
|
||||||
|
/gsd:execute-phase 1 # 执行
|
||||||
|
/gsd:verify-work 1 # 验收
|
||||||
|
/gsd:next # 自动推进到下一步
|
||||||
|
... 重复 ...
|
||||||
|
/gsd:complete-milestone # 归档并打 tag
|
||||||
|
/gsd:new-milestone # 开始下一个版本
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 迁移对照表
|
||||||
|
|
||||||
|
| 旧命令 | 新命令 | 说明 |
|
||||||
|
| ---------------------------------- | --------------------------------------------- | ------------------------ |
|
||||||
|
| `/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 接管 |
|
||||||
|
| 并行编排（tmux） | `claude-devfleet` MCP 或 Agent+worktree | Windows 原生替代 |
|
||||||
|
| PRD → 实施 | `/prp-plan <prd.md>` → `/prp-implement` | 自动解析 phases |
|
||||||
|
| 多模型协同 | `/multi-workflow` | Codex+Gemini+Claude |
|
||||||
|
|
||||||
|
## CLAUDE.md 更新
|
||||||
|
|
||||||
|
项目 CLAUDE.md 中 Step 2 应从：
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
| New feature | `/ecc:orchestrate feature` |
|
||||||
|
```
|
||||||
|
|
||||||
|
改为：
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
| New feature | `/ecc:feature-dev <desc>` |
|
||||||
|
| Bug fix | `/ecc:tdd` then `/ecc:code-review` |
|
||||||
|
| Refactor | `/ecc:plan` then `/ecc:tdd` then `/ecc:code-review` |
|
||||||
|
| Full phase | `/gsd:execute-phase N` |
|
||||||
|
| All phases | `/gsd:autonomous` |
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Windows 可用性总结
|
||||||
|
|
||||||
|
| 方案 | Windows | 原理 |
|
||||||
|
|------|---------|------|
|
||||||
|
| `/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（除非 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`）只在以下场景有价值：
|
||||||
|
|
||||||
|
1. **上下文窗口不够** — 一个 phase 太大，塞不进单次会话
|
||||||
|
2. **无人值守** — 睡觉前启动，醒来看结果
|
||||||
|
3. **消除作者偏见** — Reviewer 必须在不同会话（Santa Method）
|
||||||
|
4. **可审计** — 每步有独立日志文件
|
||||||
|
|
||||||
|
## Related
|
||||||
|
|
||||||
|
- [[Autonomous Agent Harness 自主代理框架]]
|
||||||
|
- [[Autonomous Loops 自主循环模式]]
|
||||||
|
- [[dmux 多Agent并行编排]]
|
||||||
|
- [[Everything Claude Code 完整指南]]
|
||||||
|
- [[GSD 方法论与最佳实践]]
|
||||||
@@ -1,5 +1,6 @@
|
|||||||
---
|
---
|
||||||
created: "2026-03-08 21:30"
|
created: "2026-03-08 21:30"
|
||||||
|
updated: "2026-04-14"
|
||||||
type: resource
|
type: resource
|
||||||
tags: [resource, claude-code, AI-tools, development-workflow, reference]
|
tags: [resource, claude-code, AI-tools, development-workflow, reference]
|
||||||
source: "https://github.com/affaan-m/everything-claude-code"
|
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 完整指南
|
# 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 用法速查]]。
|
||||||
|
|
||||||
自主循环和并行编排详见：[[Autonomous Loops 自主循环模式]]、[[dmux 多Agent并行编排]]、[[Ralphinho RFC-DAG 编排模式]]
|
> **仓库关键参考文档**（实测路径 `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)
|
everything-claude-code/ (v1.10.0)
|
||||||
├── agents/ (112个) - 专用子代理 (.agents/ + agents/)
|
├── agents/ (~48) - 专用子代理（code-reviewer、planner、tdd-guide、...）
|
||||||
├── skills/ (215个) - 工作流定义和领域知识
|
├── skills/ (~183) - 工作流定义和领域知识
|
||||||
├── commands/ (82个) - slash 命令
|
├── commands/ (~79) - slash 命令
|
||||||
├── hooks/ - 基于事件的自动化
|
├── hooks/ - 基于事件的自动化（hooks.json + scripts/hooks/*）
|
||||||
├── rules/ - 始终遵循的规则（15种语言 + common）
|
├── rules/ - 始终遵循的规则（python/typescript/golang/... + common + zh）
|
||||||
├── scripts/ (93个) - 跨平台 Node.js 工具脚本
|
├── scripts/ - 跨平台 Node.js 工具脚本（orchestrate-worktrees、harness-audit、...）
|
||||||
├── mcp-configs/- MCP 服务器配置模板
|
├── mcp-configs/- MCP 服务器配置模板
|
||||||
└── contexts/ - 动态注入的上下文文件
|
├── contexts/ - 动态注入的上下文文件
|
||||||
|
├── docs/ - COMMAND-AGENT-MAP、SKILL-PLACEMENT-POLICY 等
|
||||||
|
└── plugins/ - 独立子插件（gsd、obsidian、planning-with-files、...）
|
||||||
```
|
```
|
||||||
|
|
||||||
|
> 数字随版本浮动，以 `ls commands/*.md | wc -l` 等实测为准。
|
||||||
|
|
||||||
## 安装
|
## 安装
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
@@ -47,7 +59,14 @@ bash install.sh python typescript golang # 按需选语言
|
|||||||
|
|
||||||
| Legacy Command | 替代 Skill |
|
| Legacy Command | 替代 Skill |
|
||||||
|---|---|
|
|---|---|
|
||||||
| `/ecc:orchestrate` | `dmux-workflows` / `autonomous-agent-harness` |
|
| `/ecc:orchestrate` | `dmux-workflows` / `autonomous-agent-harness`（**注意：dmux 需 tmux，Windows 不可用。实际替代见下方**） |
|
||||||
|
|
||||||
|
> **orchestrate 迁移指南**（详见 [[ECC 编排替代方案 (orchestrate 迁移)]]）：
|
||||||
|
> - 单功能：`/ecc:feature-dev "描述"` — 7 阶段全流程，Windows 可用
|
||||||
|
> - 手动拆步：`/ecc:plan` → `/ecc:tdd` → `/ecc:code-review` → `/ecc:verify`
|
||||||
|
> - 多阶段自动：`/gsd:autonomous` — GSD 系统，Windows 可用
|
||||||
|
> - Bug 修复：`/ecc:tdd` → `/ecc:code-review`
|
||||||
|
> - 重构：`/ecc:plan` → `/ecc:tdd` → `/ecc:code-review`
|
||||||
| `/ecc:verify` | `verification-loop` |
|
| `/ecc:verify` | `verification-loop` |
|
||||||
| `/ecc:tdd` | `tdd-workflow` |
|
| `/ecc:tdd` | `tdd-workflow` |
|
||||||
| `/ecc:eval` | `eval-harness` |
|
| `/ecc:eval` | `eval-harness` |
|
||||||
@@ -78,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)
|
### 核心基础设施 (9)
|
||||||
|
|
||||||
@@ -222,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 | 职责 |
|
| Agent | 职责 |
|
||||||
| ---------------------- | ----------------- |
|
| ---------------------- | ----------------- |
|
||||||
@@ -248,16 +285,22 @@ Rules 新增：java, kotlin, dart, csharp, cpp, rust, perl, php, web, zh (中文
|
|||||||
## 常用 Commands
|
## 常用 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 编排
|
### 多 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`
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -296,9 +339,12 @@ ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
|
|||||||
### Resources
|
### Resources
|
||||||
- [[Everything Claude Code 方法论与最佳实践]]
|
- [[Everything Claude Code 方法论与最佳实践]]
|
||||||
- [[Everything Claude Code 用法速查]]
|
- [[Everything Claude Code 用法速查]]
|
||||||
|
- [[ECC 编排替代方案 (orchestrate 迁移)]] ← **编排机制全景表**
|
||||||
- [[Autonomous Loops 自主循环模式]]
|
- [[Autonomous Loops 自主循环模式]]
|
||||||
|
- [[Autonomous Agent Harness 自主代理框架]]
|
||||||
- [[dmux 多Agent并行编排]]
|
- [[dmux 多Agent并行编排]]
|
||||||
- [[Ralphinho RFC-DAG 编排模式]]
|
- [[Ralphinho RFC-DAG 编排模式]]
|
||||||
|
- [[GSD 方法论与最佳实践]]
|
||||||
|
|
||||||
### Zettelkasten
|
### Zettelkasten
|
||||||
- [[Everything Claude Code 最佳实践]]
|
- [[Everything Claude Code 最佳实践]]
|
||||||
|
|||||||
@@ -9,7 +9,7 @@ source: "~/.claude/skills/ralphinho-rfc-pipeline/SKILL.md"
|
|||||||
|
|
||||||
最复杂的自主循环模式。把 RFC/PRD 分解为依赖 DAG，按层并行执行，每个 unit 过分级质量管道，最后通过合并队列着陆。由 enitrat 创建。
|
最复杂的自主循环模式。把 RFC/PRD 分解为依赖 DAG，按层并行执行，每个 unit 过分级质量管道，最后通过合并队列着陆。由 enitrat 创建。
|
||||||
|
|
||||||
相关笔记：[[Autonomous Loops 自主<EFBFBD><EFBFBD>环模式]]、[[dmux 多Agent并行编排]]
|
相关笔记：[[Autonomous Loops 自主循环模式]]、[[dmux 多Agent并行编排]]、[[Autonomous Agent Harness 自主代理框架]]、[[ECC 编排替代方案 (orchestrate 迁移)]]
|
||||||
|
|
||||||
## 架构总览
|
## 架构总览
|
||||||
|
|
||||||
|
|||||||
@@ -7,9 +7,12 @@ source: "~/.claude/skills/dmux-workflows/SKILL.md"
|
|||||||
|
|
||||||
# dmux 多Agent并行编排
|
# dmux 多Agent并行编排
|
||||||
|
|
||||||
用 tmux 管理多个 AI agent 面板，每个面板跑独立 agent 会话，最后合并结果。ECC v1.10.0 中 `/ecc:orchestrate` 的并行执行部分路由到此 skill。
|
> **平台限制：需要 tmux，仅 Linux/macOS 可用。Windows 不可用（除非使用 WSL）。**
|
||||||
|
> Windows 替代方案见 [[ECC 编排替代方案 (orchestrate 迁移)]]。
|
||||||
|
|
||||||
相关笔记：[[Autonomous Loops 自主循环模式]]、[[Everything Claude Code 完整指南]]
|
用 tmux 管理多个 AI agent 面板，每个面板跑独立 agent 会话，最后合并结果。ECC v1.10.0 中 `/ecc:orchestrate` 已标记为 legacy，底层的并行部分路由到此 skill。
|
||||||
|
|
||||||
|
相关笔记：[[Autonomous Loops 自主循环模式]]、[[Everything Claude Code 完整指南]]、[[ECC 编排替代方案 (orchestrate 迁移)]]、[[Autonomous Agent Harness 自主代理框架]]
|
||||||
|
|
||||||
## 什么是 dmux
|
## 什么是 dmux
|
||||||
|
|
||||||
|
|||||||
@@ -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 隔离策略（同源思路）
|
||||||
0
Everything Claude Code ��整指南.md
Normal file
0
Everything Claude Code ��整指南.md
Normal file
Reference in New Issue
Block a user