From 41bd8854eb5562b77d1916ec12f43ec58b5d3650 Mon Sep 17 00:00:00 2001 From: ThreeFish Date: Fri, 4 Sep 2026 10:03:39 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs(research):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E9=87=8F=E5=8C=96=E4=B8=8E=E6=8A=95=E8=B5=84=E7=A7=91=E5=AD=A6?= =?UTF-8?q?=E5=88=86=E7=BB=84=E6=9A=A8=E5=87=AF=E5=88=A9=E5=85=AC=E5=BC=8F?= =?UTF-8?q?=E6=8A=95=E8=B5=84=E6=95=B0=E5=AD=A6=E8=B0=83=E7=A0=94=E6=96=87?= =?UTF-8?q?=E7=8C=AE;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 docs/research/quant-finance/150-kelly-criterion-and-investment-math.md： 以凯利公式 f*=(bp−q)/b 为起点，梳理七块严格成立的投资数学定理 （凯利仓位/统计功效/期望值与破产风险/波动拖累/复利年金/Markowitz 分散化/Sharpe 主动管理算术），配合经多智能体交叉核验的实证数据 （SPIVA/巴菲特十年赌局/Barber & Odean/上交所全账户研究），推导 中国市场 2026 时点可执行操作路径与避坑清单；全文严格区分 A 类 恒等式与 B 类实证统计，18 条 IEEE 引用； - 新增分组 _category_.json（position 7「量化与投资科学」）； - 同步 docs/research/readme.md 新增第七分组阅读入口； - 同步 docs/.agents/knowledge-map.md 研究文献索引，并顺带清理 协同协议小节三条历史死链（PR #1120 前协议文档已上移用户级配置）； - 已验证 build_docs_pack 正确拾取新文档与分组标签。 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang --- docs/.agents/knowledge-map.md | 5 +- ...150-kelly-criterion-and-investment-math.md | 252 ++++++++++++++++++ docs/research/quant-finance/_category_.json | 5 + docs/research/readme.md | 8 +- 4 files changed, 266 insertions(+), 4 deletions(-) create mode 100644 docs/research/quant-finance/150-kelly-criterion-and-investment-math.md create mode 100644 docs/research/quant-finance/_category_.json diff --git a/docs/.agents/knowledge-map.md b/docs/.agents/knowledge-map.md index 4b03ae821..cd9e88e9c 100644 --- a/docs/.agents/knowledge-map.md +++ b/docs/.agents/knowledge-map.md @@ -5,9 +5,7 @@ ## 协同协议与规范 -- [Agent 协作协议（CLAUDE.md / AGENTS.md）](../../AGENTS.md) — 项目根工程行为准则 -- [浏览器验证协议](./browser-validation.md) — 浏览器实机验证规范（A 类 claude-in-chrome 交互 / B 类系统默认 Playwright MCP 自治） -- [引用规范 (IEEE)](./reference-specifications.md) — 决策引用与文献格式 +- Agent 协作协议（AGENTS.md）、浏览器验证协议、引用规范 (IEEE) — 已上移至用户级全局配置（`~/.claude/CLAUDE.md` 与 `~/.agents/docs/`），仓库不再承载 Agent 指令源 - [Wiki 文档排序元数据规范](./wiki-docs-ordering.md) — `sidebar_position`（文件 frontmatter）+ `_category_.json`（目录）驱动 docs/ → wiki 导航排序 ## 工程经验沉淀 @@ -63,6 +61,7 @@ ## 研究文献 / Research - [Research（研究文献索引）](../research/) — 认知增强、上下文工程、Agent runtime、向量检索、知识图谱、Agent Sandbox 等领域基线调研 +- [凯利公式与股市投资的数学基石](../research/quant-finance/150-kelly-criterion-and-investment-math.md) — 七块严格成立的投资数学定理（凯利仓位/统计功效/破产风险/波动拖累/复利年金/Markowitz 分散化/Sharpe 主动管理算术）+ 经多智能体交叉核验的实证数据（SPIVA/巴菲特赌局/Barber & Odean/上交所全账户研究）+ 中国市场 2026 时点可执行操作路径（个人养老金/宽基 ETF 费率/QDII 溢价/A-C 份额临界公式）与避坑清单；全文严格区分 A 类恒等式与 B 类实证统计 - [Snowflake 数据云平台深度调研](../research/retrieval-storage/034-snowflake-data-cloud.md) — 基于 Snowflake 官方文档的 10 正交维度（架构/存储/计算/数据工程/开发/AI/安全治理/数据共享/业务连续性/成本）全景调研 + 主流方案（BigQuery/Redshift/Databricks/OceanBase）横向对比与选型建议 - [ADK 2.0 升级调研](../research/agent-runtime/020b-adk-2.0-upgrade.md) — Google ADK 2.0 核心新特性、Breaking Changes、本项目影响评估与渐进式升级路径 - [Routine Agent 迭代模式调研](../research/self-evolution/110-routine-agent-iteration.md) — ReAct/Reflexion/Self-Refine/LATS/Voyager + LLM-as-Judge + Claude Code/Codex/Gemini/OpenHands 工程实践与停止护栏（长周期自主任务理论基础） diff --git a/docs/research/quant-finance/150-kelly-criterion-and-investment-math.md b/docs/research/quant-finance/150-kelly-criterion-and-investment-math.md new file mode 100644 index 000000000..9de901749 --- /dev/null +++ b/docs/research/quant-finance/150-kelly-criterion-and-investment-math.md @@ -0,0 +1,252 @@ +--- +sidebar_position: 1 +title: "凯利公式与股市投资的数学基石：定理、实证与可执行操作" +--- + +# 凯利公式与股市投资的数学基石：定理、实证与可执行操作 + +> **摘要**：本报告以凯利公式 f\* = (bp − q)/b 为起点，系统梳理「应用于股市投资、在其假设下数学上严格成立」的七块定理基石（凯利仓位、统计功效、期望值与破产风险、波动拖累、复利与年金、Markowitz 分散化、Sharpe 主动管理算术），配合经独立核验的公开实证数据（SPIVA、巴菲特十年赌局、Barber & Odean、上交所全账户研究等），推导出面向普通投资者的可执行操作路径，并给出常见误区的数学拆解。全文严格区分 **A 类**（数学恒等式/定理，附成立假设）与 **B 类**(实证统计，附样本与时间范围)两类结论，所有数字均经多来源交叉核验与独立复算。 +> +> **免责声明**：本文为教育与科普性质的调研文献，不构成投资建议。费率、限购、收益率等均为 2023–2026 年间公开报道的时点快照。 + +--- + +## 0. 结论先行："绝对正确"在股市里分两种 + +**没有任何公式能"绝对正确地预测市场"**——若有人如此宣称，其本身就违反本文 §1.7 的算术恒等式。真正严格成立的只有两类： + +- **A 类 · 数学恒等式/定理**：只要假设成立，结论必然成立。它们不预测明天涨跌，只约束"怎么下注、怎么付钱、怎么复利"。 +- **B 类 · 实证统计**：被反复核验的历史数据，高度可信但依赖样本期，不是定律。 + +七块 A 类数学拼起来，推出一个明确到有点扫兴的操作答案： + +```mermaid +flowchart TD + A["Sharpe 算术恒等式
全体主动扣费后必然平均跑输指数"]:::math + B["SPIVA / 上交所数据
几十年如一日地实证验证"]:::evidence + C["凯利公式
无被证明的优势 ⇒ 最优仓位 = 0"]:::math + D["统计功效
证明优势需 ~617 笔独立交易
多数人一生攒不够"]:::math + E["核心结论
核心仓位买低成本指数
把精力花在成本 · 分散 · 时间上"]:::action + + A --> E + B --> E + C --> E + D --> C + + classDef math fill:#1e3a5f,stroke:#4a90d9,color:#e8f1fa + classDef evidence fill:#3d2e1e,stroke:#d9a54a,color:#faf3e8 + classDef action fill:#1e3d2a,stroke:#4ad97e,color:#e8faf0 +``` + +--- + +## 1. 七块数学基石（A 类，附成立假设与算例） + +### 1.1 凯利公式：决定"押多少"，而非"押哪边" + +**离散形式**（Kelly 1956 [1]）： + +$$f^* = \frac{bp - q}{b}$$ + +其中 p 为胜率、q = 1 − p、b 为净赔率（每冒 1 元亏损风险能赢几元）。f\* 是最大化长期对数财富增长率 g(f) = p·ln(1+bf) + q·ln(1−f) 的唯一解。 + +**成立假设**：各次下注独立同分布且可无限重复；p、b 已知且精确；以最大化 E[ln W] 为目标；资金可无限细分。 + +**算例**：胜率 55%、赔率 1:1（b = 1）⇒ f\* = (0.55 − 0.45)/1 = **10%**。此时每注对数增长率 ≈ +0.50%；若押到 2 倍凯利（20%），增长率变为 **−0.014%** —— 从最优直接跌穿零，长期几乎必然归零（数值经复算）。 + +两条最反直觉的性质： + +1. **期望不正就别玩**：bp ≤ q 时 f\* ≤ 0，最优仓位是**零**。凯利从不告诉你买什么，它只在你已证明有优势之后才开口。 +2. **押过头的惩罚不对称**：少押损失的是速度，多押赌上的是生死。 + +**连续形式**（Thorp 2006 [2]）：资产漂移 μ、波动 σ、无风险利率 r 下，g(f) = r + f(μ−r) − f²σ²/2，最优杠杆 + +$$f^* = \frac{\mu - r}{\sigma^2}$$ + +**算例**：μ = 8%、r = 2%、σ = 20% ⇒ f\* = 0.06/0.04 = **150% 仓位**——全凯利在股市根本不可执行，这正是实务采用分数凯利的入口。 + +**分数凯利性质**（MacLean-Thorp-Ziemba 2010 [3]，由 g(f) 二次型可直接推出 c(2−c) 系数关系）：下注 c·f\* 时超额增长率 = c(2−c)·(μ−r)²/(2σ²)。 + +| 凯利倍数 c | 超额增长率保留 | 波动率 | 方差 | +|:---:|:---:|:---:|:---:| +| 1.0（全凯利） | 100% | 1× | 1× | +| **0.5（半凯利）** | **75%** | **0.5×** | **0.25×** | +| 2.0 | **0%**（= 无风险利率） | 2× | 4× | +| > 2.0 | 为负（若 r=0 则长期归零） | — | — | + +### 1.2 统计功效：你凭什么相信自己有优势？ + +凯利的前提"p 已知"恰是最难的一环。检验 H₀: p = 0.5 vs H₁: p = 0.55，所需独立交易笔数（单比例检验样本量公式，Penn State STAT 507 [14]；经正态近似与精确二项分布双重复算）： + +| 检验设定 | 所需笔数 | +|:---|:---:| +| 仅 5% 显著性（功效 ≈ 50%） | ≈ 271 笔 | +| 5% 显著性 + 80% 功效 | **≈ 617 笔**（精确二项：n=617 时功效 78.7%，n=650 达 80.7%） | +| 5% 显著性 + 95% 功效 | ≈ 1077 笔 | + +**操作含义**：绝大多数散户十年也攒不出 617 笔独立交易——即**多数人终其一生无法在统计上证明自己有选股优势，只能"感觉有"**。在攒够样本之前，f\* 的诚实估计就是 0。 + +**成立假设**：各笔交易独立同分布、真实胜率恒定；若交易相关（同一行情下的连环止损/止盈）或胜率漂移，所需样本更大。 + +### 1.3 期望值与破产风险：正期望也可能死在半路 + +- **期望值**（概率论定义，无条件成立）：E = p·W − q·L。E ≤ 0 的系统玩得越久亏得越多，没有仓位技巧能挽救。 +- **赌徒破产定理**（Grinstead & Snell [15]）：固定注额 1:1 下注、胜率 p > q、初始资金 z 个单位，破产概率 R = (q/p)^z；p ≤ q 时 R = 1。 + +**算例**：p = 0.55 时，本金 10 个单位 ⇒ 破产概率 (0.45/0.55)¹⁰ ≈ **13.4%**；本金 20 个单位 ⇒ ≈ **1.8%**。同样的优势，单笔仓位小一半，存活概率完全不同——这就是"单笔风险不超过总资金 1%–2%"纪律的数学出处。 + +### 1.4 波动拖累与回本恒等式：亏 50% 要赚 100% 才回本 + +- **回本恒等式**（纯代数，无条件成立）：亏损 L 后需涨 L/(1−L) 回本。亏 20% → 需 +25%；亏 50% → 需 **+100%**；亏 70% → 需 +233%。 +- **波动拖累**（Messmore 1995 [4]）：几何平均 G ≈ 算术平均 A − σ²/2（对数正态下有精确式 1+G = (1+A)·e^{−s²/2}）。 + +**算例**：先 +50% 再 −50%，算术平均 0%，实际 100 → 150 → 75，**亏 25%**（每期几何平均 −13.4%）。A = 10%、σ = 20% ⇒ G ≈ 8%（精确 7.82%）。 + +**操作含义**：两个平均收益相同的策略，波动小者长期更值钱。控制回撤不是胆小，是算术。 + +### 1.5 复利与定投公式：时间是唯一免费的杠杆 + +普通年金终值（等比数列求和，纯代数 [16]）： + +$$FV = PMT \times \frac{(1+i)^n - 1}{i}$$ + +**算例**：每月末定投 1000 元、年化 6%（i = 0.5%）、20 年（n = 240）⇒ 终值 ≈ **462,041 元**，其中本金 24 万、复利收益约 22.2 万（经逐月现金流模拟复核）。公式对"早开始"的奖励远大于"多聪明"。 + +### 1.6 Markowitz 分散化：唯一的"免费午餐" + +组合方差 σp² = ΣΣ wᵢwⱼρᵢⱼσᵢσⱼ（方差定义的直接推论 [5]）。当任意两资产 ρ < 1 时，组合波动率**严格小于**成分波动率的加权平均，而期望收益按权重线性保留——收益不牺牲、风险白降。 + +**算例**：两资产各 50%、σ 均为 30%、ρ = 0.3 ⇒ σp = **24.19%**（ρ=1 时 30%、ρ=0 时 21.21%、ρ=−1 时 0%；经复算）。反过来说：满仓一只股票 = 主动放弃这份免费午餐。 + +> 注："分散化是唯一免费午餐"一语广为归于 Markowitz，但 1952 原文并无此原话；本文仅对 ρ<1 ⇒ 波动严格下降这一数学内核负责。 + +### 1.7 Sharpe 主动管理算术：全体跑赢市场在算术上不可能 + +会计恒等式（Sharpe 1991 [6]，"only on the laws of addition, subtraction, multiplication and division"）：**市场收益 = 全体投资者收益的资金加权平均**（市场本来就是所有人持仓的总和）。故： + +1. 主动资金**扣费前**的资金加权平均收益必然等于市场收益； +2. 主动交易成本更高 ⇒ **扣费后**全体主动资金平均必然跑输指数。 + +**算例**：市场涨 10%，80% 资金被动、20% 主动 ⇒ 10% = 0.8×10% + 0.2×X ⇒ X = 10%（被加法锁定）；扣 1.5% 成本后剩 8.5%。 + +**成立边界**（Pedersen 2018 [7]）：须先选定"市场"且主动+被动完整覆盖其市值；按资金而非人数加权；被动部分持有市场组合本身。它不排除个别人跑赢——但"大家一起跑赢"在算术上不存在。 + +--- + +## 2. 实证数据（B 类，数字均经独立核验） + +| 数据点 | 数字 | 含义 | +|:---|:---|:---| +| SPIVA 美国记分卡（截至 2024 年底）[10] | 15 年期 **89.50%** 大盘主动基金费后跑输 S&P 500 | 主动选股长期赢是少数例外 | +| SPIVA 持续性记分卡（截至 2024 年底） | 2020-12 业绩头部四分位的大盘主动基金，**4 年后无一**仍在头部（随机基准 ≈ 0.39%） | 今年的冠军不可外推 | +| 巴菲特 vs Protégé 十年赌局（2008–2017，伯克希尔 2017 股东信原表） | 指数基金累计 **+125.8%**（年化 8.5%）vs 五只 FoF 平均 **+36.3%**（各自年化 0.3%–6.5%） | 费率 + 主动管理的十年复利差距（n=1 案例而非统计证明） | +| Morningstar 费率研究（Kinnel 2016 [12]） | 费率最低五分位基金 5 年"存活且跑赢同类"比例 **62%**，最贵五分位 **20%** | 费率是挑基金最可靠的预测变量 | +| Barber & Odean 2000 [8]（66,465 账户，1991–1996） | 换手最高组年化 **11.4%** vs 最低组 **18.5%**（市场 17.9%），费前收益几乎无差 | 频繁交易者费前不比人笨，费后差 7 个点/年 | +| 上交所全账户研究（施东辉、Jones、张晓燕，SSRN 3628809 [13]；2016.1–2019.6） | 市值 10 万以下散户平均 **−20.53%**，机构 **+11.22%**，同期上证指数约 +9% | A 股小散整体倒亏；"七亏二平一赚"的精确比例无官方出处，但方向被账户级数据支持 | +| Vanguard 一次性 vs 定投（1976–2022 [11]） | 一次性投入在 **61.6%–73.7%** 的 12 个月窗口胜出，中位多赚 1.2–2.2 个点；仅第 5 百分位尾部定投更优 | 钱越早入场期望越高；定投的价值主要是行为纪律 | +| 行为差距 | DALBAR 口径 2024 年差 8.5 个点（其方法论被 Edesess/Pfau/Kitces 批评为系统性夸大）；Morningstar《Mind the Gap》IRR 口径 10 年年均约 **1.1 个点** | 追涨杀跌的代价真实存在，但常被夸大；引用须并述两口径 | + +--- + +## 3. 可执行操作路径（结合中国市场 2026 时点） + +> 以下费率与制度为 2024–2026 年公开报道/公告快照，实操以最新法律文件为准。 + +### Step 0 · 入场前——收益率"有保证"的两件事 + +先还清高息债务（还掉 18% 的信用卡债 = 无风险赚 18%）；留 6–12 个月生活费于货币基金（2026-03 全市场 7 日年化均值约 1.10%）或国债逆回购（门槛 1000 元；GC001 平时约 1%–1.5%，长假前冲高，2025-12-30 达 2.28%）。 + +### Step 1 · 个人养老金账户（政策白送的钱） + +每年 **12,000 元**税前抵扣、领取时按 3% 单独计税——边际税率高于 3% 即为确定性正收益（边际 20% 者年省税 2,400 元）。账户内指数基金 **Y 份额**管理费五折且免销售服务费（最低 0.15% + 0.05%/年）；2024-12 起制度全国推广并纳入首批 85 只指数基金。**注意**：资金锁定至法定退休；边际税率 ≤ 3% 的低收入者税收上可能不划算。 + +### Step 2 · 核心仓位 = 最低费率的宽基指数 + +2024-11 费率改革后主流宽基 ETF 最低档合计 **0.20%/年**（管理费 0.15% + 托管费 0.05%；旧档 0.60%）。持有 10 万元，费率差每年 400 元——§2 中 Morningstar 的数据说明这是全场最可靠的一笔"投资"。 + +看长期收益必须用**全收益指数**（含股息再投资）：沪深300 全收益自 2004-12-31 基日至 2024 年初年化约 **8.8%**（Wind 口径），价格指数同期仅约 7.3%——差出的 2–2.5 个点/年就是被"忽略分红"吃掉的。 + +### Step 3 · 定投自动化，用纪律代替判断 + +设置每月自动扣款（遇非交易日顺延；扣款失败不影响征信，连续 3 次失败协议通常自动终止）。数学上一次性投入胜率约 2/3（§2 Vanguard），但定投把"这次是不是高点"这个无法回答的问题从流程里删掉——行为差距主要死于择时。 + +### Step 4 · 跨市场分散，看清跨境工具的溢价 + +A 股 + 海外（QDII）兑现 §1.6 的免费午餐。但 2025–2026 年 QDII 额度紧张：场外限购低至单日 10–100 元；场内 QDII-ETF 溢价常态 1%–3%，高峰散点见 4% 以上直至个别 ~20%（2026-06 曾有 12 只纳指 ETF 集体停牌提示风险）。**溢价买入 = 先输一笔**：净值 1.00 元的 ETF 按 1.05 元买入，溢价收敛到 1% 时即使指数不跌也浮亏约 4%。 + +### Step 5 · 每年再平衡一次，只多不少 + +60/40 股债组合放任不管会漂成 80/20，组合波动上升约 1/3。年度再平衡或偏离 5% 阈值触发即可——Vanguard 研究：月/季/年频率的风险调整后收益无实质差异，更频繁只增加成本；再平衡的作用是**控风险**，不是抓收益。 + +### Step 6 · 把交易频率压到最低 + +A 股一买一卖成本约 **0.08%–0.12%**（印花税 0.05% 卖出单边 + 佣金典型万 1–万 2.5 + 经手费 0.00341% + 证管费 0.002% + 过户费 0.001%；**ETF 免印花税**，成本约低一半）。看似小钱，§2 的 Barber & Odean 数据说明高换手者正是被这些小钱千刀万剐。 + +场外基金 A/C 份额按持有期选：临界持有期 t = A 类实付申购费率 ÷ C 类年销售服务费率（费用结构恒等式）。典型参数下约 4–5 个月：短于此选 C，长于此选 A；2027-01 起指数基金持有超 1 年免收销售服务费，C 类适用面扩大。 + +--- + +## 4. 若坚持主动交易：凯利给出的三道门 + +1. **先证明优势**：完整记录扣费后交易，区分 55% vs 50% 胜率需约 617 笔（§1.2）；样本外（非回测调参所得）期望 E = pW − qL 必须 > 0。 +2. **警惕自己的回测**：97 个学术发表的选股因子，样本外收益平均衰减 26%、发表后再衰减 58%（McLean & Pontiff 2016 [9]）；纯噪声试得够多也必然出漂亮曲线——从 N 次尝试挑出的最大样本内 Sharpe 按 √(2·ln N) 膨胀（Bailey et al. 2014 [17]），因子研究界已把显著性门槛提高到 t > 3.0（Harvey-Liu-Zhu 2016）。 +3. **仓位 ≤ 1/4 凯利、单笔风险 ≤ 总资金 1%–2%**：参数是估计值，估计误差只会让真实凯利更低（§1.1 押过头惩罚不对称 + §1.3 破产风险）。 + +--- + +## 5. 避坑清单（每条背后都是上文的数学） + +| 坑 | 一句话拆穿 | 数学/证据锚点 | +|:---|:---|:---| +| 长期持有杠杆 ETF | 每日重置：标的 +10% 再 −10% 剩 0.99，3 倍基金剩 0.91；真实案例 2008.12–2009.4 指数 +8% 而 3 倍做多 ETF **−53%**（FINRA 09-31） | §1.4 波动拖累（杠杆放大 σ²） | +| 亏损加倍摊平（马丁格尔） | 100 元起注连输 10 次后下一注需 10,240 元；有限资金下破产概率随轮次趋近 1（可选停时定理：公平赌局任何策略期望不变，负期望下严格为负） | §1.3 破产风险 | +| 追热点"拿着总会回来" | 纳指 2000-03 峰值后跌 78%，价格口径 **15 年**回本；日经 225 用了 **34 年**（1989-12 → 2024-02）。含股息口径回本更早，引用须注明 | §1.4 回本恒等式 | +| "感觉不对就清仓躲躲" | 2003–2022 持有 S&P 500 的 1 万美元变 6.48 万；错过最好 10 天只剩 2.97 万。但须并述批评：约 76%–78% 的最好交易日聚集在熊市或牛市头两个月，"错过最好 N 天"与"避开最差 N 天"都是事后反事实（Estrada 2008：前者 −50.8%、后者 +150.4%） | §2 行为差距 | +| 技术分析稳赚/全无效 | 学术综述（Park & Irwin 2007）：95 篇现代研究 56 正/20 负/19 混合，多数有数据窥探缺陷，经校正后显著性普遍减弱——既非"全玄学"也绝非"稳赚" | §4 回测过拟合 | +| 迷信历史冠军基金 | 幸存者偏差：>15 年样本的基金数据库业绩虚高约 1%/年（Carhart et al. 2002）；SPIVA 20 年期近 64% 的基金已清盘消失 | §2 SPIVA 持续性 | + +--- + +## 6. 一句话收尾 + +凯利公式教你的不是怎么赢，而是**在没有被证明的优势面前保持零仓位，在有优势时押多少才不会死在证明成立之前**——而对绝大多数人，这条公式的输出就是：低成本指数基金 + 定投 + 分散 + 再平衡 + 别动。 + +--- + +## 参考文献（IEEE） + +[1] J. L. Kelly Jr., "A New Interpretation of Information Rate," *Bell System Technical Journal*, vol. 35, no. 4, pp. 917–926, 1956. [Online]. Available: https://www.princeton.edu/~wbialek/rome/refs/kelly_56.pdf + +[2] E. O. Thorp, "The Kelly Criterion in Blackjack, Sports Betting, and the Stock Market," in *Handbook of Asset and Liability Management*, vol. 1, Elsevier, 2006, pp. 385–428. [Online]. Available: https://gwern.net/doc/statistics/decision/2006-thorp.pdf + +[3] L. C. MacLean, E. O. Thorp, and W. T. Ziemba, "Long-term capital growth: the good and bad properties of the Kelly and fractional Kelly criteria," *Quantitative Finance*, vol. 10, no. 7, pp. 681–687, 2010. [Online]. Available: https://www.stat.berkeley.edu/~aldous/157/Papers/Good_Bad_Kelly.pdf + +[4] T. E. Messmore, "Variance Drain," *Journal of Portfolio Management*, vol. 21, no. 4, pp. 104–110, 1995. + +[5] H. Markowitz, "Portfolio Selection," *Journal of Finance*, vol. 7, no. 1, pp. 77–91, 1952. + +[6] W. F. Sharpe, "The Arithmetic of Active Management," *Financial Analysts Journal*, vol. 47, no. 1, pp. 7–9, 1991. [Online]. Available: https://web.stanford.edu/~wfsharpe/art/active/active.htm + +[7] L. H. Pedersen, "Sharpening the Arithmetic of Active Management," *Financial Analysts Journal*, vol. 74, no. 1, pp. 21–36, 2018. + +[8] B. M. Barber and T. Odean, "Trading Is Hazardous to Your Wealth: The Common Stock Investment Performance of Individual Investors," *Journal of Finance*, vol. 55, no. 2, pp. 773–806, 2000. [Online]. Available: https://faculty.haas.berkeley.edu/odean/papers%20current%20versions/individual_investor_performance_final.pdf + +[9] R. D. McLean and J. Pontiff, "Does Academic Research Destroy Stock Return Predictability?" *Journal of Finance*, vol. 71, no. 1, pp. 5–32, 2016. + +[10] S&P Dow Jones Indices, *SPIVA U.S. Scorecard Year-End 2024*. [Online]. Available: https://www.spglobal.com/spdji/en/spiva/article/spiva-us/ + +[11] Vanguard, *Cost averaging: Invest now or temporarily hold your cash?* 2023. [Online]. Available: https://www.nl.vanguard/professional/vanguard-365/cost-averaging + +[12] R. Kinnel, *Predictive Power of Fees: Why Mutual Fund Fees Are So Important*, Morningstar, 2016. [Online]. Available: https://www.morningstar.com/funds/fund-fees-predict-future-success-or-failure + +[13] C. M. Jones, D. Shi, X. Zhang, and X. Zhang, "Retail Trading and Return Predictability in China," SSRN Working Paper 3628809（基于上交所全样本账户数据，2016.1–2019.6）. [Online]. Available: https://papers.ssrn.com/sol3/papers.cfm?abstract_id=3628809 + +[14] Penn State University, *STAT 507: Epidemiological Research Methods — Lesson 10: Power and Sample Size*. [Online]. Available: https://online.stat.psu.edu/stat507/Lesson10.html + +[15] C. M. Grinstead and J. L. Snell, *Introduction to Probability*, §12.2 Gambler's Ruin. [Online]. Available: https://stats.libretexts.org/Bookshelves/Probability_Theory/Introductory_Probability_(Grinstead_and_Snell)/12:_Random_Walks/12.02:_Gambler's_Ruin + +[16] OpenStax, *Principles of Finance*, Ch. 8.2 Annuities. [Online]. Available: https://openstax.org/books/principles-finance/pages/8-2-annuities + +[17] D. H. Bailey, J. M. Borwein, M. López de Prado, and Q. J. Zhu, "Pseudo-Mathematics and Financial Charlatanism: The Effects of Backtest Overfitting on Out-of-Sample Performance," *Notices of the AMS*, vol. 61, no. 5, pp. 458–471, 2014. [Online]. Available: https://www.ams.org/notices/201405/rnoti-p458.pdf + +[18] FINRA, *Regulatory Notice 09-31: Leveraged and Inverse ETFs*. [Online]. Available: https://www.finra.org/rules-guidance/notices/09-31 diff --git a/docs/research/quant-finance/_category_.json b/docs/research/quant-finance/_category_.json new file mode 100644 index 000000000..02b76b31c --- /dev/null +++ b/docs/research/quant-finance/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 7, + "label": "量化与投资科学", + "description": "投资决策中的数学定理与实证证据：凯利公式、波动拖累、组合分散化、主动管理算术与低成本指数化实务" +} diff --git a/docs/research/readme.md b/docs/research/readme.md index 7211b0354..c5d4c6358 100644 --- a/docs/research/readme.md +++ b/docs/research/readme.md @@ -1,6 +1,6 @@ # 研究文献总览 -> Negentropy 技术调研索引。34 篇原始调研按「认知 → 框架 → 存储 → 图谱 → 执行 → 进化」六段论归档，逐层递进；本页为各主题分组的阅读入口。 +> Negentropy 技术调研索引。原始调研按「认知 → 框架 → 存储 → 图谱 → 执行 → 进化」六段论归档，逐层递进，另设独立主题分组（量化与投资科学）；本页为各主题分组的阅读入口。 --- @@ -79,6 +79,12 @@ | [经验时代的自驱迭代进化智能体](./self-evolution/140-experience-era-self-improvement.md) | 88 页综述精读 + Routine 闭环诊断 | | [Skill 进化闭环 × 自我改进评测](./self-evolution/141-skills-evolution-and-si-measurement.md) | Skills 三阶段进化 + SI 六目标度量 | +## 七、量化与投资科学 · `quant-finance/` + +| 文档 | 主旨 | +|:---|:---| +| [凯利公式与股市投资的数学基石](./quant-finance/150-kelly-criterion-and-investment-math.md) | 七块严格成立的定理（凯利仓位 / 统计功效 / 破产风险 / 波动拖累 / 复利年金 / Markowitz 分散化 / Sharpe 算术）+ 经核验的实证数据（SPIVA / 上交所账户研究等）+ 中国市场可执行操作路径与避坑清单 | + --- > 阅读建议：首次按一→六段论顺序通读；选型查阅直接跳到对应分组。各子目录的 `_category_.json` 提供分组级描述，wiki 左栏可折叠展开。 From 0007556692573f04aa78e6a78d3f25a16d08d028 Mon Sep 17 00:00:00 2001 From: ThreeFish Date: Fri, 4 Sep 2026 10:42:51 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs(quant-finance):=20=E4=BF=AE=E6=AD=A3?= =?UTF-8?q?=E5=87=AF=E5=88=A9=E5=85=AC=E5=BC=8F=E8=B0=83=E7=A0=94=E6=96=87?= =?UTF-8?q?=E7=8C=AE=E7=9A=84=E6=95=B0=E5=80=BC=E3=80=81=E5=8F=A3=E5=BE=84?= =?UTF-8?q?=E4=B8=8E=E5=BC=95=E7=94=A8=E7=BC=BA=E9=99=B7;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 代码审查发现 5 处问题，逐条修正： - §5 马丁格尔算例数字少一位：100 元起注连输 10 次后下一注为 100 × 2¹⁰ = 102,400 元（此前累计已投入 102,300 元），原值 10,240 把「有限资金撑不住翻倍序列」的论证削弱了一个数量级，方向与结论相反； - §3 Step 1 个人养老金节税额与同句口径不一致：前半句以「税前抵扣 − 领取时 3% 单独计税」定义净收益，但 2,400 元为未扣领取端税负的毛额； 改为展开净额推导 2,400 − 360 = 年净节税 2,040 元； - §0 立论与 §1.7 自述边界冲突：Sharpe 恒等式约束的是全体主动资金的 资金加权平均，并不排除个别人跑赢（§1.7 原文即如此），故「存在预测 公式」本身不违反该恒等式；条件收紧为「人人靠某公式跑赢市场」； - §1.4「精确 7.82%」依赖未声明的口径切换：补充 σ 为简单收益率标准差、 s 为对数收益率标准差及 s² = ln(1+σ²/(1+A)²) 换算关系，精确值按 σ 口径重算为 8.23%；同时将 e^{−s²/2} 改写为 exp(−s²/2)，消除正文裸 花括号在 react-markdown + rehype-katex 下原样显示的问题； - §5 杠杆 ETF 行以文字形式引用「FINRA 09-31」，致参考文献 [18] 成为 全篇唯一无正文锚点的条目，按 IEEE 格式补上编号引用。 验证：全部 18 条引用编号双向闭合（无孤儿、无未定义）；表格列数一致； 正文无裸花括号；G = 8.23% 与 102,400 元经 Python 独立复算确认。 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang --- .../150-kelly-criterion-and-investment-math.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/research/quant-finance/150-kelly-criterion-and-investment-math.md b/docs/research/quant-finance/150-kelly-criterion-and-investment-math.md index 9de901749..53ab6185f 100644 --- a/docs/research/quant-finance/150-kelly-criterion-and-investment-math.md +++ b/docs/research/quant-finance/150-kelly-criterion-and-investment-math.md @@ -13,7 +13,7 @@ title: "凯利公式与股市投资的数学基石：定理、实证与可执行 ## 0. 结论先行："绝对正确"在股市里分两种 -**没有任何公式能"绝对正确地预测市场"**——若有人如此宣称，其本身就违反本文 §1.7 的算术恒等式。真正严格成立的只有两类： +**没有任何公式能"绝对正确地预测市场"**——而"人人靠某公式跑赢市场"这类宣称，更是直接违反本文 §1.7 的算术恒等式（该恒等式约束的是全体主动资金的**资金加权平均**，并不排除个别人跑赢）。真正严格成立的只有两类： - **A 类 · 数学恒等式/定理**：只要假设成立，结论必然成立。它们不预测明天涨跌，只约束"怎么下注、怎么付钱、怎么复利"。 - **B 类 · 实证统计**：被反复核验的历史数据，高度可信但依赖样本期，不是定律。 @@ -98,9 +98,9 @@ $$f^* = \frac{\mu - r}{\sigma^2}$$ ### 1.4 波动拖累与回本恒等式：亏 50% 要赚 100% 才回本 - **回本恒等式**（纯代数，无条件成立）：亏损 L 后需涨 L/(1−L) 回本。亏 20% → 需 +25%；亏 50% → 需 **+100%**；亏 70% → 需 +233%。 -- **波动拖累**（Messmore 1995 [4]）：几何平均 G ≈ 算术平均 A − σ²/2（对数正态下有精确式 1+G = (1+A)·e^{−s²/2}）。 +- **波动拖累**（Messmore 1995 [4]）：几何平均 G ≈ 算术平均 A − σ²/2，其中 σ 为**简单收益率**标准差。对数正态下有精确式 1+G = (1+A)·exp(−s²/2)，其中 s 为**对数收益率**标准差，经 s² = ln(1 + σ²/(1+A)²) 与 σ 换算——两者数值不同，不可互相代入。 -**算例**：先 +50% 再 −50%，算术平均 0%，实际 100 → 150 → 75，**亏 25%**（每期几何平均 −13.4%）。A = 10%、σ = 20% ⇒ G ≈ 8%（精确 7.82%）。 +**算例**：先 +50% 再 −50%，算术平均 0%，实际 100 → 150 → 75，**亏 25%**（每期几何平均 −13.4%）。A = 10%、σ = 20% ⇒ 近似 G ≈ 8%；精确解 s² = ln(1 + 0.04/1.21) = 0.0325 ⇒ **G = 8.23%**。 **操作含义**：两个平均收益相同的策略，波动小者长期更值钱。控制回撤不是胆小，是算术。 @@ -158,7 +158,7 @@ $$FV = PMT \times \frac{(1+i)^n - 1}{i}$$ ### Step 1 · 个人养老金账户（政策白送的钱） -每年 **12,000 元**税前抵扣、领取时按 3% 单独计税——边际税率高于 3% 即为确定性正收益（边际 20% 者年省税 2,400 元）。账户内指数基金 **Y 份额**管理费五折且免销售服务费（最低 0.15% + 0.05%/年）；2024-12 起制度全国推广并纳入首批 85 只指数基金。**注意**：资金锁定至法定退休；边际税率 ≤ 3% 的低收入者税收上可能不划算。 +每年 **12,000 元**税前抵扣、领取时按 3% 单独计税——边际税率高于 3% 即为确定性正收益（边际 20% 者：缴存端抵税 2,400 元 − 领取端 3% 计税 360 元 = **年净节税 2,040 元**）。账户内指数基金 **Y 份额**管理费五折且免销售服务费（最低 0.15% + 0.05%/年）；2024-12 起制度全国推广并纳入首批 85 只指数基金。**注意**：资金锁定至法定退休；边际税率 ≤ 3% 的低收入者税收上可能不划算。 ### Step 2 · 核心仓位 = 最低费率的宽基指数 @@ -198,8 +198,8 @@ A 股一买一卖成本约 **0.08%–0.12%**（印花税 0.05% 卖出单边 + | 坑 | 一句话拆穿 | 数学/证据锚点 | |:---|:---|:---| -| 长期持有杠杆 ETF | 每日重置：标的 +10% 再 −10% 剩 0.99，3 倍基金剩 0.91；真实案例 2008.12–2009.4 指数 +8% 而 3 倍做多 ETF **−53%**（FINRA 09-31） | §1.4 波动拖累（杠杆放大 σ²） | -| 亏损加倍摊平（马丁格尔） | 100 元起注连输 10 次后下一注需 10,240 元；有限资金下破产概率随轮次趋近 1（可选停时定理：公平赌局任何策略期望不变，负期望下严格为负） | §1.3 破产风险 | +| 长期持有杠杆 ETF | 每日重置：标的 +10% 再 −10% 剩 0.99，3 倍基金剩 0.91；真实案例 2008.12–2009.4 指数 +8% 而 3 倍做多 ETF **−53%**（FINRA 09-31 [18]） | §1.4 波动拖累（杠杆放大 σ²） | +| 亏损加倍摊平（马丁格尔） | 100 元起注连输 10 次后下一注需 102,400 元（此前累计已投入 102,300 元）；有限资金下破产概率随轮次趋近 1（可选停时定理：公平赌局任何策略期望不变，负期望下严格为负） | §1.3 破产风险 | | 追热点"拿着总会回来" | 纳指 2000-03 峰值后跌 78%，价格口径 **15 年**回本；日经 225 用了 **34 年**（1989-12 → 2024-02）。含股息口径回本更早，引用须注明 | §1.4 回本恒等式 | | "感觉不对就清仓躲躲" | 2003–2022 持有 S&P 500 的 1 万美元变 6.48 万；错过最好 10 天只剩 2.97 万。但须并述批评：约 76%–78% 的最好交易日聚集在熊市或牛市头两个月，"错过最好 N 天"与"避开最差 N 天"都是事后反事实（Estrada 2008：前者 −50.8%、后者 +150.4%） | §2 行为差距 | | 技术分析稳赚/全无效 | 学术综述（Park & Irwin 2007）：95 篇现代研究 56 正/20 负/19 混合，多数有数据窥探缺陷，经校正后显著性普遍减弱——既非"全玄学"也绝非"稳赚" | §4 回测过拟合 | From 55ab5ebb567531e39b690101bd6f44357f5b6669 Mon Sep 17 00:00:00 2001 From: ThreeFish Date: Fri, 4 Sep 2026 10:46:19 +0800 Subject: [PATCH 3/3] =?UTF-8?q?docs(links):=20=E6=94=B6=E5=8F=A3=20Agent?= =?UTF-8?q?=20=E6=8C=87=E4=BB=A4=E6=BA=90=E4=B8=8A=E7=A7=BB=E9=81=97?= =?UTF-8?q?=E7=95=99=E7=9A=84=2042=20=E5=A4=84=E4=BB=93=E5=BA=93=E5=86=85?= =?UTF-8?q?=E6=AD=BB=E9=93=BE;?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 协作协议文档上移用户级配置后（AGENTS.md / CLAUDE.md / browser-validation.md / reference-specifications.md 四份已从仓库移除）， docs/ 下仍有 42 处相对链接指向这些不存在的文件，发布到 wiki 后全部为死链。 前一次仅清理了 docs/.agents/knowledge-map.md 的 3 处，本次全量收口： - 本仓自有文档（concepts / research / i18n / reference/wiki，共 25 处）： 改指用户级规范路径 `~/.claude/CLAUDE.md`、 `~/.agents/docs/browser-validation.md`、 `~/.agents/docs/reference-specifications.md`，保留原句语义与锚点作用； - 历史 Issue 记录（docs/.agents/issue.md，13 处）：仅去链接、原文表述 与当时的仓内路径一并保留，不改写历史事实； - perceives 镜像目录（4 处）：该目录描述的是另一仓库的结构，同样仅去 链接、不改指向，避免把本仓路径错误地断言给上游。 同步修正去链接后残留的两处中文排版空格。 验证：四份文档的仓库内死链归零（改前 42 处）；diff 未新增任何链接； 19 个受改文件表格列数无回归；build_docs_pack 重跑，wiki 导航正常构建。 🤖 Generated with [Claude Code](https://github.com/claude), [CodeX](https://openai.com), [Gemini](https://github.com/apps/gemini-code-assist) Co-Authored-By: Aurelius Huang --- docs/.agents/issue.md | 24 +++++++++---------- .../browser-automation-mcp-integration.md | 10 ++++---- docs/concepts/design/context-layer.md | 2 +- docs/concepts/design/self-evolving-agents.md | 2 +- docs/concepts/design/sso.md | 2 +- docs/concepts/framework.md | 2 +- .../subsystems/025-the-memory-system.md | 2 +- .../subsystems/035-the-knowledge-base.md | 2 +- .../subsystems/036-the-knowledge-graph.md | 2 +- docs/concepts/subsystems/037-federated-kg.md | 2 +- docs/concepts/user-guide/chat-essentials.md | 2 +- docs/concepts/user-guide/faq.md | 2 +- docs/concepts/user-guide/memory-automation.md | 2 +- .../user-guide/skills-troubleshooting.md | 2 +- docs/i18n/zh-CN/README.md | 2 +- .../perceives/agents/knowledge-map.md | 6 ++--- docs/reference/perceives/issue.md | 2 +- docs/reference/wiki/design/knowledge-graph.md | 2 +- .../120-browser-automation-mcp.md | 10 ++++---- 19 files changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/.agents/issue.md b/docs/.agents/issue.md index e9fa632f4..05a1fc250 100644 --- a/docs/.agents/issue.md +++ b/docs/.agents/issue.md @@ -282,7 +282,7 @@ - **处理方式**（Expand → Backfill → Contract 三段式无破坏迁移）： 1. **架构沉淀**（本次 PR）：[`035-the-knowledge-base.md` §15 单实例 Catalog 收敛（Phase 4）](../concepts/subsystems/035-the-knowledge-base.md#15-单实例-catalog-收敛phase-4在-nm-之上叠加聚合根不变量) 作为 ADR 等价记录，明确「Phase 4 在 Phase 3 N:M schema 之上叠加聚合根不变量，不是回退」；[`wiki/ops.md` §12](../reference/wiki/ops.md#12-单实例-catalog-与-wiki-发布版本管理运维) 沉淀 Phase B merge runbook（含 `pg_dump` 强制备份、守恒断言、回退 SQL）； 2. **Phase A Migration 0007**（独立 PR）：纯加法——`CREATE UNIQUE INDEX uq_doc_catalogs_app_singleton ON doc_catalogs(app_name) WHERE is_archived=false`、`CREATE UNIQUE INDEX uq_wiki_pub_catalog_active ON wiki_publications(catalog_id) WHERE status='LIVE'`、`ALTER TABLE doc_catalogs ADD COLUMN merged_into_id UUID NULL REFERENCES doc_catalogs(id) ON DELETE SET NULL`。downgrade 完全可逆； - 3. **Phase B Migration 0008**（独立 PR + 强制 `pg_dump` 备份）：按「根节点合并为子树」策略——按 `(app_name) ORDER BY created_at ASC LIMIT 1` 选 survivor，其它 catalog 的顶层 entry 嫁接到 survivor 顶层新建的虚拟 `CATEGORY` 节点（slug 加 `legacy-` 后缀避免冲突），整树 `catalog_id` UPDATE 到 survivor，WikiPublication 的 LIVE 降级为 ARCHIVED 并重指向，`navigation_config` JSONB 中的 catalog_id 显式 rewrite，源 catalog 设 `is_archived=true, merged_into_id=survivor.id`（**严禁物理删除**，与 [AGENTS.md 数据库管理规范](../CLAUDE.md) 一致）。声明 `DESTRUCTIVE_DOWNGRADE = true`，回退依赖快照； + 3. **Phase B Migration 0008**（独立 PR + 强制 `pg_dump` 备份）：按「根节点合并为子树」策略——按 `(app_name) ORDER BY created_at ASC LIMIT 1` 选 survivor，其它 catalog 的顶层 entry 嫁接到 survivor 顶层新建的虚拟 `CATEGORY` 节点（slug 加 `legacy-` 后缀避免冲突），整树 `catalog_id` UPDATE 到 survivor，WikiPublication 的 LIVE 降级为 ARCHIVED 并重指向，`navigation_config` JSONB 中的 catalog_id 显式 rewrite，源 catalog 设 `is_archived=true, merged_into_id=survivor.id`（**严禁物理删除**，与 AGENTS.md 数据库管理规范 一致）。声明 `DESTRUCTIVE_DOWNGRADE = true`，回退依赖快照； 4. **后端 API**（独立 PR）：新增 `GET /catalogs/resolve?app_name=X`（幂等读，404 表示不存在）、`POST /catalogs/ensure`（upsert-or-get），`POST /catalogs` 加 guard：active 已存在则 409 `catalog_already_exists` 并返回 `existing_catalog_id`；`DELETE /catalogs/{id}` 改为 `is_archived=true` 软删；`CatalogService.create_catalog` 在事务内 `SELECT ... FOR UPDATE` + 捕获 `IntegrityError` 降级为 ensure 语义防御并发 race。`fetchCatalogs` 保留并标 `@deprecated` 给旧客户端 6 周宽限期； 5. **前端**（独立 PR）：新增 `features/knowledge/hooks/useAppCatalog.ts` 调 `resolveCatalog(APP_NAME)` + SWR 缓存（404 fallback ensure），新增只读 `` 显示 catalog name + tooltip（slug / app_name），`/knowledge/catalog` 与 `/knowledge/wiki` 删除 `` 与 `useState` 守卫；树渲染、节点 CRUD、Wiki 详情面板等组件全部不动，只换上游数据源。 - **后续防范**： @@ -757,11 +757,11 @@ - **表因**：AI Agent（Claude / Antigravity）在沙箱形态浏览器（Playwright 默认 `chromium.launch()` 启的空白 profile）中打开 [`localhost:3192`](http://localhost:3192) 触发项目自带的 Google OAuth 流（`/auth/google/login` → `accounts.google.com` → `/auth/google/callback`，参见 [docs/sso.md](../infrastructure/design/sso.md)），跳转到 `accounts.google.com` 后因该浏览器无任何 Google 登录态，被同意屏 / reCAPTCHA / 二步验证拦截，验证链路在此中断；用户被迫多次手动接管或放弃验证。 - **根因**：双重契约错配： 1. **会话来源错配**：默认 sandbox 浏览器的 cookie store / device fingerprint / IP 风险评分均与用户日常 Chrome 不同，Google 风控将其视为可疑设备；即便用户在沙箱内输入正确账密，亦极易被强制拉起二次验证或拒绝； - 2. **工具选型缺位**：项目 [CLAUDE.md（即 AGENTS.md）](../CLAUDE.md) 此前未约定"涉及登录态的浏览器验证应优先使用与用户常用 Chrome 共享会话的工具"，AI Agent 默认走 sandbox 即陷入上述风控； + 2. **工具选型缺位**：项目 `CLAUDE.md`（即 AGENTS.md）此前未约定"涉及登录态的浏览器验证应优先使用与用户常用 Chrome 共享会话的工具"，AI Agent 默认走 sandbox 即陷入上述风控； 3. **Playwright E2E 同样缺位**：`apps/negentropy-ui/playwright.config.ts` 之前无 `setup` project / `storageState` / `userDataDir` 复用机制，凡涉及真实 OAuth 的 E2E 都需重复人工登录或退化为 mock，长期削弱端到端覆盖。 - **处理方式**： - 1. **协议落地**：[CLAUDE.md › 术 › Browser Validation Protocol](../CLAUDE.md) 新增子节，明确"涉及登录态的浏览器验证必须复用用户常用 Chrome 会话"，首选 `mcp__claude-in-chrome__*`，退化为 `mcp__chrome_devtools__*` + Chrome `--remote-debugging-port`，禁止在 sandbox 浏览器中通过 Google 同意屏； - 2. **详尽文档**：新建 [docs/agents/browser-validation.md](./agents/browser-validation.md)，含三种 MCP 浏览器工具的能力对照、Mermaid 选型决策图、三步连通性自检脚本、storageState 工作时序、风控应对、IEEE 引用； + 1. **协议落地**：CLAUDE.md › 术 › Browser Validation Protocol 新增子节，明确"涉及登录态的浏览器验证必须复用用户常用 Chrome 会话"，首选 `mcp__claude-in-chrome__*`，退化为 `mcp__chrome_devtools__*` + Chrome `--remote-debugging-port`，禁止在 sandbox 浏览器中通过 Google 同意屏； + 2. **详尽文档**：新建 `docs/agents/browser-validation.md`，含三种 MCP 浏览器工具的能力对照、Mermaid 选型决策图、三步连通性自检脚本、storageState 工作时序、风控应对、IEEE 引用； 3. **Playwright 改造**： - `apps/negentropy-ui/playwright.config.ts` 在 `PLAYWRIGHT_AUTH=1` 时启用两个新 project：`setup`（`/.*\.setup\.ts$/`，强制 headless: false）与 `chromium-authenticated`（`dependencies: ['setup']`，注入 `storageState`），可选 `PLAYWRIGHT_USER_DATA_DIR` 走 `--user-data-dir` 复用本地 profile； - `STORAGE_STATE` 默认 `apps/negentropy-ui/.auth/user.json`，可被 `PLAYWRIGHT_STORAGE_STATE` 覆盖； @@ -778,7 +778,7 @@ 1. 所有依赖外部第三方登录的链路（Microsoft / Apple / GitHub OAuth、企业 SSO、内部 SaaS 密钥）在 sandbox 浏览器中均会遭遇同质风控，应统一按本协议复用真实浏览器会话； 2. 任何"AI Agent 帮我跑一下登录后页面"的请求都应先看协议工具选型矩阵； 3. 跨 profile 复制 storageState / Cookie 的方案在 Google / 微软等高风控供应商上不可靠，不建议作为退化方案。 -- **2026-05-06 协议演进**：实测 Claude in Chrome 扩展 MCP 在多数 Conductor / Claude Code 会话中未挂载，"首选 → 退化"两档路由长期无法生效；同时 macOS 默认配置下 `mcp__chrome_devtools__list_pages` 已能直接接入用户常用 Chrome 主 profile（含已登录 Google 账号）。因此协议统一收敛为唯一驱动 `mcp__chrome_devtools__*`，并明确"Playwright 仅用于不接触 OAuth 的 B 类隔离场景"。详见 [AGENTS.md › Browser Validation Protocol](../CLAUDE.md) 与 [docs/agents/browser-validation.md](./agents/browser-validation.md)（§1 协议演进段、§3 工具能力对照、§4 决策图、§5 两步自检）。 +- **2026-05-06 协议演进**：实测 Claude in Chrome 扩展 MCP 在多数 Conductor / Claude Code 会话中未挂载，"首选 → 退化"两档路由长期无法生效；同时 macOS 默认配置下 `mcp__chrome_devtools__list_pages` 已能直接接入用户常用 Chrome 主 profile（含已登录 Google 账号）。因此协议统一收敛为唯一驱动 `mcp__chrome_devtools__*`，并明确"Playwright 仅用于不接触 OAuth 的 B 类隔离场景"。详见 AGENTS.md › Browser Validation Protocol 与 `docs/agents/browser-validation.md`（§1 协议演进段、§3 工具能力对照、§4 决策图、§5 两步自检）。 --- @@ -1254,7 +1254,7 @@ - **后续防范**： 1. 所有"确认/危险操作"必须复用 `components/ui/ConfirmDialog`，严禁原生 confirm/alert； 2. ISSUE-045 修复时把 ConfirmDialog 放在 skills 私有目录是熵增信号——通用基础组件必须直接在 `components/ui/` 落地； - 3. 在 [`docs/AGENTS.md`](../AGENTS.md) 工程规范中已有"严禁原生 dialog"条款，建议下一轮加 ESLint 规则 `no-restricted-globals` 阻断 `window.confirm`/`alert`/`prompt` 直接调用。 + 3. 在 `docs/AGENTS.md` 工程规范中已有"严禁原生 dialog"条款，建议下一轮加 ESLint 规则 `no-restricted-globals` 阻断 `window.confirm`/`alert`/`prompt` 直接调用。 - **同类问题影响**：MCP Servers / SubAgents 等模块若仍残留原生 dialog 需统一替换；ESLint 规则升级可一次性发现所有遗漏点。 --- @@ -1868,7 +1868,7 @@ - 新增 `tests/unit_tests/knowledge/test_kg_build_pipeline_fixes.py` 9 条 UT 锁定 7 项修复契约（PageRank SQL CAST / Leiden via leidenalg / drop_params 透传 / Embedding hint / sync_relation bool 返回）； - `tests/unit_tests/knowledge/test_kg_entity_service_unit.py` 与 `test_graph_entity_service.py` 三条既有 UT 升级 — 之前实为"silent assertion of bug"（把跳过当成功），现校正为 `relations_synced=0 + relations_skipped=2`； - `uv run pytest tests/unit_tests/knowledge` 678 通过（1 pre-existing 失败 `test_extraction_llm_plan` 与本次无关）；`uv run ruff check` 全绿； - - 浏览器实机验证按 [Browser Validation Protocol](agents/browser-validation.md) 在用户主 profile 完成；端到端 KG Build 后 SQL `SELECT importance_score, community_id FROM kg_entities WHERE corpus_id=...` 非 NULL、`SELECT level, community_id FROM kg_community_summaries` 多条非空摘要、`kg_first_class_sync relations_synced` 与 `graph_loaded edge_count` 数值一致（差额由 `relations_skipped` 明示）。 + - 浏览器实机验证按 Browser Validation Protocol 在用户主 profile 完成；端到端 KG Build 后 SQL `SELECT importance_score, community_id FROM kg_entities WHERE corpus_id=...` 非 NULL、`SELECT level, community_id FROM kg_community_summaries` 多条非空摘要、`kg_first_class_sync relations_synced` 与 `graph_loaded edge_count` 数值一致（差额由 `relations_skipped` 明示）。 - **后续防范**（跨上下文准则）： 1. **PostgreSQL UPDATE-FROM-VALUES 范式**：批量 UPSERT/UPDATE 一律采用占位符级 `CAST(:p AS type)`，禁用 `AS v(col type)` 内联类型 — 后者在 asyncpg / psycopg3 / pg-protocol bridge 多驱动行为不一致。 2. **NetworkX 3.x dispatch wrapper 边界**：调用 `nx.community.*` 前必须确认是否为 dispatch wrapper（隐式 backend 派发会以 `NotImplementedError` 形式出现而非明确 `ImportError`）。Leiden / Modularity 类算法一律走 `igraph + leidenalg` / `cdlib` 直连。 @@ -1961,7 +1961,7 @@ - `community_summary_failed` 警告：1 次 → 0 次； - 终态 `status`：`completed_with_errors` → `completed`； - `build_run_updated` 字段一致性：单字段 `run_id=UUID` → 双字段 `run_uuid` + `run_id`； - - **未完成项（透明披露）**：端到端浏览器回归遵循 [browser-validation 协议](../docs/agents/browser-validation.md) 需用户在自有 Chrome 主 profile 操作真实语料库 corpus，本次未在 agent 上下文执行——本修复全由单元测试与结构断言保障。 + - **未完成项（透明披露）**：端到端浏览器回归遵循 browser-validation 协议 需用户在自有 Chrome 主 profile 操作真实语料库 corpus，本次未在 agent 上下文执行——本修复全由单元测试与结构断言保障。 - **后续防范**： 1. **事务边界单一来源**：service / repository / domain 模块层级应明确"谁开 begin / 谁负责 commit"的契约；domain service（如 summarizer）只负责写入，事务边界由 application service 持有，杜绝跨层双重事务管理； 2. **多策略消解的 ID 维度必维护**：任何"按 label 合并"的策略都必须同步暴露 ID 映射（new_id → surviving_id），下游不应被迫从 label 反推 id；新增 stage 时（如未来 LLM 验证）必须遵循此契约； @@ -1994,7 +1994,7 @@ - 单元测试：[`test_global_search.py`](../apps/negentropy/tests/unit_tests/knowledge/test_global_search.py) 新增 3 个用例（`llm_config_id` 路由到 `resolve_llm_config_by_id`、无 id 走 `resolve_llm_config` 全局默认、`evidence=0` + `candidates>0` 返回基础设施错误文案）+ 现有 7 个用例零回归；[`test_embedding.py`](../apps/negentropy/tests/unit_tests/knowledge/test_embedding.py) 新增 `TestNonRetryableFailFast` 4 个用例（AuthenticationError 不重试、NotFoundError 不重试、文本模式兜底命中、ConnectionError 仍按指数退避到上限）+ 现有 5 个用例零回归； - 范围覆盖：`tests/unit_tests/knowledge/` 全量 816 项断言通过（pre-existing `test_extraction_llm_plan.py::test_build_llm_invocation_plan_returns_none_when_serialization_fails` 失败已 `git stash` 比对验证与本次修复无关）； - 契约 smoke：`uv run python` 内联校验 `_is_non_retryable_error(AuthenticationError)` / `NotFoundError` / `BadRequestError` / 文本模式 generic Exception 全部 True，`ConnectionError` False；`GlobalSearchService(llm_config_id=...)` 构造与读字段一致； - - **未完成项（透明披露）**：浏览器端到端验证遵循 [browser-validation 协议](./agents/browser-validation.md) 需用户在自有 Chrome 主 profile + 真实语料库 corpus 操作；agent 上下文 chrome_devtools 通道被占用且不应启用 sandbox profile，本次未在 agent 内执行实机验证——本修复全由单元测试与结构断言保障。 + - **未完成项（透明披露）**：浏览器端到端验证遵循 browser-validation 协议 需用户在自有 Chrome 主 profile + 真实语料库 corpus 操作；agent 上下文 chrome_devtools 通道被占用且不应启用 sandbox profile，本次未在 agent 内执行实机验证——本修复全由单元测试与结构断言保障。 - **后续防范**： 1. **「查询侧模型 = ingestion 侧模型」契约**：所有需要在向量空间中比较的查询路径（global_search / hybrid_search / multi_hop / future rerank），必须经 `_resolve_corpus_model_ids` 解出 `embedding_config_id` 后传给 `build_embedding_fn`；新增类似路径时 review 必须显式检查此契约。 2. **重试白名单契约**：任何外部 API 重试循环必须区分「瞬时故障（5xx 网关 / 429 / timeout）」与「终态故障（4xx 凭证 / 路由 / 参数）」，前者退避重试、后者立即降级；`_is_non_retryable_error` 应作为 KG 子系统跨模块的标准 fail-fast 工具，不要在新调用点重新实现。 @@ -2028,7 +2028,7 @@ - 单元：新增 17 个用例（`tests/unit_tests/config/test_task_registry.py` 7 项、`tests/unit_tests/config/test_model_resolver_task.py` 5 项、`tests/unit_tests/interface/test_task_models_api.py` 5 项）100% 通过； - 回归：`tests/unit_tests/` 1634 通过 / 1 deselected（`test_extraction_llm_plan.py::test_build_llm_invocation_plan_returns_none_when_serialization_fails` 在 master 即失败，与本次修复无关，已 `git stash` 比对验证）； - 调试观测：resolver 命中后输出结构化日志 `task_model_resolved {task_key, corpus_id, resolved_model, source ∈ {corpus_task, global_task, default}}`，可用于线上链路核对。 - - **未完成项（透明披露）**：浏览器实机回归遵循 [browser-validation 协议](./agents/browser-validation.md) 需用户在 Chrome 主 profile + 真实凭证操作；本次未在 agent 内执行实机验证——所有路径由单元测试 + 静态检查覆盖。 + - **未完成项（透明披露）**：浏览器实机回归遵循 browser-validation 协议 需用户在 Chrome 主 profile + 真实凭证操作；本次未在 agent 内执行实机验证——所有路径由单元测试 + 静态检查覆盖。 - **后续防范**： 1. **"调用点新增 LLM 操作 → 同步登记 task_key"契约**：任何新增后台 LLM/Embedding 调用点必须先在 [`task_registry.py`](../apps/negentropy/src/negentropy/config/task_registry.py) 注册槽位，再通过 `resolve_*_for_task` 解析。Code review 时检查"裸调 `resolve_llm_config()` 或 `litellm.acompletion(model="…")`"作为 red flag。 2. **缓存命名空间隔离**：新增 resolver 时务必使用独立 cache key 前缀（`task:` / `subagent:` / `llm:` 等已建立），写操作匹配的 `invalidate_cache(prefix=...)` 必须同步覆盖；不可与全局 `llm` / `embedding` 缓存共用键。 @@ -2064,7 +2064,7 @@ - **后续防范**： 1. **同 pathname + 仅 query 变更的 URL 更新一律走 `window.history.replaceState`**：避免再次踩到 Next.js RSC 判定的 NA no-op。涉及 pathname 跳转（`/`、`/interface`、`/admin` 等）的入口继续使用 `router.replace` / `router.push`，两者职责分明。 2. **Code review 红线**：评审看到 `router.replace(somePath, { scroll: false })` 且 `somePath` 与当前 pathname 同源（仅 query 不同）时，明确要求改写为 `window.history.replaceState`。 - 3. **实机验证为兜底底线**：本类 bug 的根因在 Next.js 路由层，vitest jsdom 环境覆盖不到——单测仅能保证"写 URL 这个动作发生"，是否"真的更新了 URL 并触发派生"必须在用户主 Chrome 实机验证（参见 [browser-validation 协议](./browser-validation.md)）；任何同型 URL-only 写入改动至少 ≥ 5 个正交场景实机回归。 + 3. **实机验证为兜底底线**：本类 bug 的根因在 Next.js 路由层，vitest jsdom 环境覆盖不到——单测仅能保证"写 URL 这个动作发生"，是否"真的更新了 URL 并触发派生"必须在用户主 Chrome 实机验证（参见 browser-validation 协议）；任何同型 URL-only 写入改动至少 ≥ 5 个正交场景实机回归。 4. **故障时的错位提示**：`handleSessionChange` 仍是 `setSessionId → clearSessionState` 顺序。若未来再出现"清空但未切换"错位，说明 URL 写入又失败了——先验证 URL 是否真的更新，而不是去调换清理顺序（调换清理顺序无法解决根本问题，只会改变错位的外观）。 - **同类问题影响**： - 本仓库其余 `router.replace` / `router.push` 调用（`app/admin/layout.tsx`、`app/interface/layout.tsx`、`app/interface/task-models/page.tsx`、`app/interface/models/page.tsx`、`app/knowledge/documents/page.tsx`）均为 pathname 级跳转，不在 bug 影响面，保持不变。 @@ -2838,7 +2838,7 @@ R7 后浏览器对照 Section 2.1 区域发现两类正交缺陷： - **表因**：以模板 routine（`9e90c3c7`）复刻任务实机长跑时，发现其历史 iter2 失败于 `working directory does not exist: '/tmp/wt/dispatch-auto'`——而 `/tmp/wt/dispatch-auto` 是 `test_routine_orchestrator.py` 的测试夹具值，却写进了**生产** routine 的迭代行。顺藤摸瓜发现整个测试套件直连生产 `negentropy` 库。 - **根因**：**测试无独立数据库，与生产共享 `negentropy` 库**： 1. `tests/conftest.py::db_engine` 直接 `create_async_engine(str(settings.database_url))`——生产库； - 2. `tests/integration_tests/db/test_migrations.py::reset_database`（autouse）执行 `command.downgrade(alembic_config, "base")`——**把生产库降级到 base，DROP 全部表 = 摧毁 routines/knowledge/memory/sessions 全部数据**，违反 [AGENTS.md「严禁删除现有数据」](../../CLAUDE.md)；其 `_sync_database_url()` 亦读 `settings.database_url`（生产）； + 2. `tests/integration_tests/db/test_migrations.py::reset_database`（autouse）执行 `command.downgrade(alembic_config, "base")`——**把生产库降级到 base，DROP 全部表 = 摧毁 routines/knowledge/memory/sessions 全部数据**，违反 AGENTS.md「严禁删除现有数据」；其 `_sync_database_url()` 亦读 `settings.database_url`（生产）； 3. `orchestrator._dispatch_due` / `_evaluate_and_decide` 查询条件为 `Routine.status=='running'`（**扫描全部** running routine，不限于测试自建行）；集成测试 patch `ensure_workspace`→`WorkspaceInfo('/tmp/wt/dispatch-auto')` 后调 `_dispatch_due`，会把该假 cwd 派发给当时正在 running 的**真实**模板 routine → CC 报 cwd 不存在 → 该 routine 随后陷入会话死亡螺旋（ISSUE-110 表征的历史 iter2-5 即源于此）。 - 模板 routine 至今尚存，说明全量 `pytest tests/` 本地近期未跑全——否则 `reset_database` 一次即清空生产库。这是「跑得够全才爆」的潜伏数据灾难。 - **处理方式**（会话级强制隔离到专用测试库，单一改写点）： diff --git a/docs/concepts/design/browser-automation-mcp-integration.md b/docs/concepts/design/browser-automation-mcp-integration.md index d77f22af3..b9088374d 100644 --- a/docs/concepts/design/browser-automation-mcp-integration.md +++ b/docs/concepts/design/browser-automation-mcp-integration.md @@ -4,9 +4,9 @@ title: "浏览器操作 MCP 集成方案：Playwright MCP 全系统默认配备" --- # 浏览器操作 MCP 集成方案：Playwright MCP 全系统默认配备 -> 本文遵循 [AGENTS.md](../../../AGENTS.md) 的协作协议与循证要求。设计核心锚定： +> 本文遵循用户级全局配置 `~/.claude/CLAUDE.md` 的协作协议与循证要求。设计核心锚定： > - 选型论证与横向盘点：[浏览器操作 MCP 调研](../../research/self-evolution/120-browser-automation-mcp.md) -> - 浏览器实机验证协议（A 类交互 / B 类自治）：[browser-validation.md](../../.agents/browser-validation.md) +> - 浏览器实机验证协议（A 类交互 / B 类自治）：`~/.agents/docs/browser-validation.md` > - 全系统 MCP 注入的单一事实源：`builtin_tools(claude_code).config.mcp_config`（参见 [claude_code handler](../../../apps/negentropy/src/negentropy/engine/schedulers/handlers/claude_code.py)） ## 1. 目标与约束 @@ -82,7 +82,7 @@ Claude Code 的相位权限（[phase.py](../../../apps/negentropy/src/negentropy ## 4. 鉴权：净室默认 + dev-cookie 旁路（按需） - **默认净室（`--isolated`）**：每会话全新 profile，适用于公开 URL 与无状态回归——开箱即用，无主机相关路径依赖。 -- **鉴权回归（按需）**：回归 negentropy-ui 等需登录页面时，复用本仓既有的 **dev-cookie storageState** 旁路（[playwright.config.ts](../../../apps/negentropy-ui/playwright.config.ts) + [sign-dev-cookie.mjs](../../../apps/negentropy-ui/scripts/sign-dev-cookie.mjs)）：经 `--storage-state=` 注入自签 `ne_sso` 登录态，**严禁**在自治环境跳转真实 OAuth/SSO 同意屏（详见 [browser-validation.md](../../.agents/browser-validation.md) 的安全红线）。配置方式见 §6。 +- **鉴权回归（按需）**：回归 negentropy-ui 等需登录页面时，复用本仓既有的 **dev-cookie storageState** 旁路（[playwright.config.ts](../../../apps/negentropy-ui/playwright.config.ts) + [sign-dev-cookie.mjs](../../../apps/negentropy-ui/scripts/sign-dev-cookie.mjs)）：经 `--storage-state=` 注入自签 `ne_sso` 登录态，**严禁**在自治环境跳转真实 OAuth/SSO 同意屏（详见 `~/.agents/docs/browser-validation.md` 的安全红线）。配置方式见 §6。 ## 5. 工具面（Playwright MCP 核心工具） @@ -108,7 +108,7 @@ Claude Code 的相位权限（[phase.py](../../../apps/negentropy/src/negentropy | `npx @latest` 不确定性 | 版本钉死；预热缓存 | | `--no-sandbox` 降低隔离 | 限受控内部 URL；不在自治环境处理不可信外链 | | 运行时缺浏览器/Node | 部署预装；连接失败仅告警，不阻断 | -| 真实 OAuth 被自治流程触发 | 默认净室；鉴权一律走 dev-cookie storageState（[browser-validation.md](../../.agents/browser-validation.md) 红线） | +| 真实 OAuth 被自治流程触发 | 默认净室；鉴权一律走 dev-cookie storageState（`~/.agents/docs/browser-validation.md` 红线） | ## 8. Routine 浏览器实机回归验证 · 配方 @@ -129,7 +129,7 @@ acceptance_criteria: ## 9. 相关文档 - [浏览器操作 MCP 调研（选型论证）](../../research/self-evolution/120-browser-automation-mcp.md) -- [浏览器实机验证协议](../../.agents/browser-validation.md) +- 浏览器实机验证协议 — `~/.agents/docs/browser-validation.md` - [Claude Code 集成（BuiltinTool）](../subsystems/038-claude-code-integration.md) - [Routine 长周期自主任务系统](../subsystems/039-the-routine-system.md) - [Interface 用户指南 §6.3 MCP Server 管理](../user-guide/interface.md) diff --git a/docs/concepts/design/context-layer.md b/docs/concepts/design/context-layer.md index 1889bb167..33afcc02c 100644 --- a/docs/concepts/design/context-layer.md +++ b/docs/concepts/design/context-layer.md @@ -4,7 +4,7 @@ title: "Context Layer · 上下文治理层技术方案" --- # Context Layer · 上下文治理层技术方案 -> 本文遵循 [AGENTS.md](../../../AGENTS.md) 的协作协议与循证要求。 +> 本文遵循用户级全局配置 `~/.claude/CLAUDE.md` 的协作协议与循证要求。 > > 设计核心锚定： > - **行业对标**：[Snowflake Horizon Context](https://www.snowflake.com/en/product/features/horizon-context/) · [Snowflake 数据云调研 §D7 Horizon Catalog](../../research/retrieval-storage/034-snowflake-data-cloud.md) diff --git a/docs/concepts/design/self-evolving-agents.md b/docs/concepts/design/self-evolving-agents.md index 46aaa0ebe..db72f8587 100644 --- a/docs/concepts/design/self-evolving-agents.md +++ b/docs/concepts/design/self-evolving-agents.md @@ -4,7 +4,7 @@ title: "自进化 Agents Team 系统技术方案" --- # 自进化 Agents Team 系统技术方案 -> 本文遵循 [AGENTS.md](../../../AGENTS.md) 的协作协议与循证要求。 +> 本文遵循用户级全局配置 `~/.claude/CLAUDE.md` 的协作协议与循证要求。 > > 设计核心锚定： > - 调研基础：[自进化 Agents Team 调研](../../research/self-evolution/130-self-evolving-agents-team.md) diff --git a/docs/concepts/design/sso.md b/docs/concepts/design/sso.md index 809193006..aeb1bb477 100644 --- a/docs/concepts/design/sso.md +++ b/docs/concepts/design/sso.md @@ -4,7 +4,7 @@ title: "单点登录（SSO）方案：Google OAuth + 用户权限管理" --- # 单点登录 (SSO) 方案：Google OAuth + 用户权限管理 -> 本文遵循 [AGENTS.md](../../../AGENTS.md) 的协作协议与循证要求。设计核心锚定： +> 本文遵循用户级全局配置 `~/.claude/CLAUDE.md` 的协作协议与循证要求。设计核心锚定： > - 用户状态与权限的权威数据源：`user_states`（参见 [pulse.py](../../../apps/negentropy/src/negentropy/models/pulse.py)） > - 会话生命周期与用户 ID 的持久化一致性：`PostgresSessionService`（参见 [session_service.py](../../../apps/negentropy/src/negentropy/engine/adapters/postgres/session_service.py)） diff --git a/docs/concepts/framework.md b/docs/concepts/framework.md index ec6d726fe..f55c1c6e6 100644 --- a/docs/concepts/framework.md +++ b/docs/concepts/framework.md @@ -51,7 +51,7 @@ title: "架构设计方案 · 一核五翼总览" ### 1.2 架构哲学 -系统遵循 [AGENTS.md](../../AGENTS.md) 定义的工程行为准则，核心原则包括： +系统遵循用户级全局配置 `~/.claude/CLAUDE.md` 定义的工程行为准则，核心原则包括： - **正交分解 (Orthogonal Decomposition)**：独立变化的维度解耦，确保单一概念主体的变更具备局部性 - **复用驱动 (Composition over Construction)**：优先通过组合与集成构建系统 diff --git a/docs/concepts/subsystems/025-the-memory-system.md b/docs/concepts/subsystems/025-the-memory-system.md index b1200821c..3cfaffb73 100644 --- a/docs/concepts/subsystems/025-the-memory-system.md +++ b/docs/concepts/subsystems/025-the-memory-system.md @@ -1623,7 +1623,7 @@ timeline ### 11.1 设计哲学 -遵循 [AGENTS.md](../../../../AGENTS.md) 的**反馈闭环 (Feedback Loops)** 原则：每一项工程行动都应产生可观测的反馈信号。Memory 价值量化体系的目标是：证明 Memory 子系统对 Agent 智能水平的**可测量贡献**。 +遵循 `~/.claude/CLAUDE.md` 的**反馈闭环 (Feedback Loops)** 原则：每一项工程行动都应产生可观测的反馈信号。Memory 价值量化体系的目标是：证明 Memory 子系统对 Agent 智能水平的**可测量贡献**。 ### 11.2 核心指标四层模型 diff --git a/docs/concepts/subsystems/035-the-knowledge-base.md b/docs/concepts/subsystems/035-the-knowledge-base.md index 4d8b9b63a..8db47a0e8 100644 --- a/docs/concepts/subsystems/035-the-knowledge-base.md +++ b/docs/concepts/subsystems/035-the-knowledge-base.md @@ -829,7 +829,7 @@ flowchart LR 2. **Virtual Root 注入**：为每个被合并 Catalog 在 survivor 顶层创建一个 `node_type='CATEGORY'` 的虚拟节点，slug 加 `legacy-` 后缀避免冲突。 3. **子树嫁接**：将被合并 Catalog 的所有顶层 entry 的 `parent_entry_id` 重指向 virtual root，整树 `catalog_id` 一次性 UPDATE 到 survivor。 4. **WikiPublication 重指向**：`catalog_id` 改写到 survivor，状态为 `LIVE` 的降级为 `ARCHIVED`（保留多版本回退），`navigation_config` JSONB 内的 catalog_id 引用同步 rewrite。 -5. **Tombstone**：源 Catalog 设 `is_archived=true, merged_into_id=survivor.id`，**严禁物理删除**（与 [AGENTS.md 数据库管理规范](../../../../AGENTS.md) 一致）。 +5. **Tombstone**：源 Catalog 设 `is_archived=true, merged_into_id=survivor.id`，**严禁物理删除**（与 `~/.claude/CLAUDE.md` 的 Database Management 规范一致）。 6. **守恒断言**：迁移末尾 SELECT 校验 `count(doc_catalog_entries)` 与 `count(DISTINCT document_id)` 守恒。 **回退性**：Phase A（仅加索引/列）的 downgrade 完全可逆；**Phase B（合并）声明 `DESTRUCTIVE_DOWNGRADE = true`，downgrade 不会反向拆分子树**——回退依赖 Phase B 执行前的强制 `pg_dump` 快照。 diff --git a/docs/concepts/subsystems/036-the-knowledge-graph.md b/docs/concepts/subsystems/036-the-knowledge-graph.md index b76cef94b..2212c9706 100644 --- a/docs/concepts/subsystems/036-the-knowledge-graph.md +++ b/docs/concepts/subsystems/036-the-knowledge-graph.md @@ -1440,4 +1440,4 @@ timeline --- -> **文档维护**：本文档与代码同步演进。架构变更时需同步更新对应章节，保持代码事实与文档描述的一致性。变更遵循 [AGENTS.md](../../../../AGENTS.md) 中的 Verification Before Done 定式。 +> **文档维护**：本文档与代码同步演进。架构变更时需同步更新对应章节，保持代码事实与文档描述的一致性。变更遵循 `~/.claude/CLAUDE.md` 中的 Verification Before Done 定式。 diff --git a/docs/concepts/subsystems/037-federated-kg.md b/docs/concepts/subsystems/037-federated-kg.md index 650731278..68db1d618 100644 --- a/docs/concepts/subsystems/037-federated-kg.md +++ b/docs/concepts/subsystems/037-federated-kg.md @@ -237,7 +237,7 @@ Feature flag：`NE_KNOWLEDGE_FEATURE_FLAGS__ENABLE_CROSS_CORPUS_KG` ## 11. 浏览器实机验证清单（P0 必跑） -按 [浏览器验证协议](../../../agents/browser-validation.md) 用 `mcp__chrome_devtools` 复用用户已登录 Chrome： +按浏览器验证协议（`~/.agents/docs/browser-validation.md`）用 `mcp__chrome_devtools` 复用用户已登录 Chrome： - [ ] 单 @Corpus → Planner 启用但无 bridges - [ ] 多 @Corpus + intent=fact → Planner 启用，bridges 可能为空 diff --git a/docs/concepts/user-guide/chat-essentials.md b/docs/concepts/user-guide/chat-essentials.md index 2095ffa01..719d40a7c 100644 --- a/docs/concepts/user-guide/chat-essentials.md +++ b/docs/concepts/user-guide/chat-essentials.md @@ -11,7 +11,7 @@ title: "Home 对话 · 主模块特性手册" ## 0. 入口 - 浏览器打开 `https:///`（首页即 Home 对话）。 -- 自签 dev cookie 注入流程参见 [agents/browser-validation.md](../agents/browser-validation.md)。 +- 自签 dev cookie 注入流程参见 `~/.agents/docs/browser-validation.md`。 ## 1. 发起对话与模型选择 diff --git a/docs/concepts/user-guide/faq.md b/docs/concepts/user-guide/faq.md index d64818b01..c14157455 100644 --- a/docs/concepts/user-guide/faq.md +++ b/docs/concepts/user-guide/faq.md @@ -146,7 +146,7 @@ Wiki 使用 ISR 机制，最长 5 分钟自动更新。如需立即更新，可 | [QA 流水线](../design/qa-delivery-pipeline.md) | `docs/concepts/design/qa-delivery-pipeline.md` | 质量门禁与发布流程 | | [Wiki 运维](../../reference/wiki/ops.md) | `docs/reference/wiki/ops.md` | Wiki 站点的部署与运维 | | [工程变更日志](../operations/engineering-changelog.md) | `docs/concepts/engineering-changelog.md` | 里程碑与基线变更记录 | -| [AI 协作协议](../../../AGENTS.md) | `AGENTS.md` | Agent 协作准则与工程规范 | +| AI 协作协议 | `~/.claude/CLAUDE.md` | Agent 协作准则与工程规范 | --- diff --git a/docs/concepts/user-guide/memory-automation.md b/docs/concepts/user-guide/memory-automation.md index 120ed31b6..4df6b068c 100644 --- a/docs/concepts/user-guide/memory-automation.md +++ b/docs/concepts/user-guide/memory-automation.md @@ -128,4 +128,4 @@ pg_dump -h localhost -U postgres negentropy_db \ -t negentropy.memory_core_blocks --data-only > core_blocks_$(date +%Y%m%d).sql ``` -> 数据迁移操作严禁直接删除现有数据，参考 [`AGENTS.md`](../../../AGENTS.md) "Database Management" 章节。 +> 数据迁移操作严禁直接删除现有数据，参考 `~/.claude/CLAUDE.md` 的 "Database Management" 章节。 diff --git a/docs/concepts/user-guide/skills-troubleshooting.md b/docs/concepts/user-guide/skills-troubleshooting.md index e438a3bd8..532191ed5 100644 --- a/docs/concepts/user-guide/skills-troubleshooting.md +++ b/docs/concepts/user-guide/skills-troubleshooting.md @@ -106,5 +106,5 @@ skills_injector_unresolved_refs owner_id=... missing=[...] - 上手 → [`skills-basics.md`](./skills-basics.md) - 进阶 → [`skills-advanced.md`](./skills-advanced.md) - 原理与架构 → [`../design/skills.md`](../design/skills.md) -- 浏览器验证协议 → [`../agents/browser-validation.md`](../agents/browser-validation.md) +- 浏览器验证协议 → `~/.agents/docs/browser-validation.md` - Issue 追踪 → [`../issue.md`](../agents/issue.md)（搜索 Skills / ISSUE-045） diff --git a/docs/i18n/zh-CN/README.md b/docs/i18n/zh-CN/README.md index f899a467a..14f9bc437 100644 --- a/docs/i18n/zh-CN/README.md +++ b/docs/i18n/zh-CN/README.md @@ -227,7 +227,7 @@ graph TB | [QA 流水线](../../concepts/design/qa-delivery-pipeline.md) | 质量门禁与发布流程 | | [SSO 集成](../../concepts/design/sso.md) | Google OAuth 认证配置 | | [工程变更日志](../../concepts/operations/engineering-changelog.md) | 里程碑与基线变更记录 | -| [AI 协作协议](../../../AGENTS.md) | Agent 协作行为准则与工程规范 | +| AI 协作协议（`~/.claude/CLAUDE.md`） | Agent 协作行为准则与工程规范 | diff --git a/docs/reference/perceives/agents/knowledge-map.md b/docs/reference/perceives/agents/knowledge-map.md index b31cdb9e1..6332e7488 100644 --- a/docs/reference/perceives/agents/knowledge-map.md +++ b/docs/reference/perceives/agents/knowledge-map.md @@ -9,9 +9,9 @@ title: "Knowledge Map · 知识索引" ## 协作约定 -- [AGENTS.md](../../AGENTS.md) — 工程行为准则、命令规范、Pre-commit 流程。 -- [browser-validation.md](./browser-validation.md) — 浏览器自动化与登录态约束。 -- [reference-specifications.md](./reference-specifications.md) — IEEE 引用规范。 +- `AGENTS.md` — 工程行为准则、命令规范、Pre-commit 流程。 +- `browser-validation.md` — 浏览器自动化与登录态约束。 +- `reference-specifications.md` — IEEE 引用规范。 ## PDF Pipeline diff --git a/docs/reference/perceives/issue.md b/docs/reference/perceives/issue.md index 335c66059..e5d4d7c27 100644 --- a/docs/reference/perceives/issue.md +++ b/docs/reference/perceives/issue.md @@ -198,7 +198,7 @@ Internal error: directory mismatch for directory ".../anthropics/claude-code-act ### 根因 -1. 仓库根目录的 [CLAUDE.md](../CLAUDE.md) 是指向 [AGENTS.md](../AGENTS.md) 的 symlink，用于避免双份 Agent 指令造成 SSoT 分裂。 +1. 仓库根目录的 `CLAUDE.md` 是指向 `AGENTS.md` 的 symlink，用于避免双份 Agent 指令造成 SSoT 分裂。 2. `anthropics/claude-code-action@v1` 在 `pull_request` 场景会先快照 PR 侧的敏感启动配置，再删除并从 base 分支恢复可信版本，以防 PR 修改 `.mcp.json` / `.claude/` / `CLAUDE.md` 注入启动行为。 3. 该 action 当前对 PR 侧 `CLAUDE.md` symlink 的快照路径存在兼容性问题，导致审查 step 提前失败；workflow 用 `continue-on-error: true` 包住该 step，因此 overall check 仍为 success，但 sticky comment 会污染 PR 讨论。 4. workflow 过去只检查 `ANTHROPIC_API_KEY` 是否非空，无法识别 secret 已过期、被撤销或填错；action 直到调用 SDK 才报 `Invalid API key` 并发布错误评论。 diff --git a/docs/reference/wiki/design/knowledge-graph.md b/docs/reference/wiki/design/knowledge-graph.md index 4ec2d6192..1397bd953 100644 --- a/docs/reference/wiki/design/knowledge-graph.md +++ b/docs/reference/wiki/design/knowledge-graph.md @@ -214,7 +214,7 @@ Wiki 场景定位于"**只读浏览 + 点击跳转**"。我们**精简重做** ### 浏览器实机回归 -按 [浏览器验证协议](../../../agents/browser-validation.md) 接入用户常用 Chrome 主 profile： +按浏览器验证协议（`~/.agents/docs/browser-validation.md`）接入用户常用 Chrome 主 profile： 1. 现有 `/`、`/[pubSlug]`、`/[pubSlug]/[...entrySlug]` 不受影响 2. `/[pubSlug]/graph` SSG 首屏可见节点、无客户端等待 diff --git a/docs/research/self-evolution/120-browser-automation-mcp.md b/docs/research/self-evolution/120-browser-automation-mcp.md index 27e9b318d..6b8885e1f 100644 --- a/docs/research/self-evolution/120-browser-automation-mcp.md +++ b/docs/research/self-evolution/120-browser-automation-mcp.md @@ -4,13 +4,13 @@ title: "浏览器操作 MCP 调研：选型论证与横向盘点" --- # 浏览器操作 MCP 调研：选型论证与横向盘点 -> **摘要 / 导言**：本报告面向一个明确的工程命题——为 Negentropy（一核五翼平台）选择一款浏览器操作 MCP，**内置为全系统默认配备**，并用于**所有 Routine 任务运行时的浏览器实机回归验证**。评估锚定本项目两类真实执行上下文：(1) 6 个 ADK Agent 经 `ActionFaculty.invoke_claude_code` 调用 Claude Code（无直接 ADK→MCP 桥）；(2) Routine 任务 = 自治后台 Claude Code 子进程（**无真人、无桌面浏览器、headless**）。二者经**同一** `builtin_tools(claude_code).config.mcp_config` 注入点喂入 MCP——这意味着默认 MCP 必须能表达为 `McpServer`（stdio/sse/http）、能无人值守 headless 运行，并能复用本仓既有的 dev-cookie 鉴权旁路。结论：采用 **Microsoft 官方 `@playwright/mcp`**；落地方案见 [浏览器操作 MCP 集成方案](../../concepts/design/browser-automation-mcp-integration.md)。本文遵循 [AGENTS.md](../../../AGENTS.md) 的循证要求，引用格式遵 [reference-specifications.md](../../.agents/reference-specifications.md)。 +> **摘要 / 导言**：本报告面向一个明确的工程命题——为 Negentropy（一核五翼平台）选择一款浏览器操作 MCP，**内置为全系统默认配备**，并用于**所有 Routine 任务运行时的浏览器实机回归验证**。评估锚定本项目两类真实执行上下文：(1) 6 个 ADK Agent 经 `ActionFaculty.invoke_claude_code` 调用 Claude Code（无直接 ADK→MCP 桥）；(2) Routine 任务 = 自治后台 Claude Code 子进程（**无真人、无桌面浏览器、headless**）。二者经**同一** `builtin_tools(claude_code).config.mcp_config` 注入点喂入 MCP——这意味着默认 MCP 必须能表达为 `McpServer`（stdio/sse/http）、能无人值守 headless 运行，并能复用本仓既有的 dev-cookie 鉴权旁路。结论：采用 **Microsoft 官方 `@playwright/mcp`**；落地方案见 [浏览器操作 MCP 集成方案](../../concepts/design/browser-automation-mcp-integration.md)。本文遵循 `~/.claude/CLAUDE.md` 的循证要求，引用格式遵 `~/.agents/docs/reference-specifications.md`。 --- ## 1. 背景与评估目标 -Negentropy 的 [浏览器实机验证协议](../../.agents/browser-validation.md) 已确立"Agent 不得自行完成/绕过 OAuth、登录态须来源于真实用户"的核心不变量，并已在 `negentropy-ui` 集成 Playwright E2E（含 dev-cookie 旁路）。但平台**尚未**把任何浏览器操作 MCP 作为系统级默认能力内置——Routine 自治任务在运行时拿不到浏览器工具，无法对其刚刚改动的 Web 产物做"实机回归验证"。 +Negentropy 的浏览器实机验证协议（`~/.agents/docs/browser-validation.md`）已确立"Agent 不得自行完成/绕过 OAuth、登录态须来源于真实用户"的核心不变量，并已在 `negentropy-ui` 集成 Playwright E2E（含 dev-cookie 旁路）。但平台**尚未**把任何浏览器操作 MCP 作为系统级默认能力内置——Routine 自治任务在运行时拿不到浏览器工具，无法对其刚刚改动的 Web 产物做"实机回归验证"。 选型须同时满足三项**硬约束**（源自上述两类执行上下文）： @@ -24,7 +24,7 @@ Negentropy 的 [浏览器实机验证协议](../../.agents/browser-validation.md **Playwright MCP（`@playwright/mcp`）**[[1]](#ref1) 由 Microsoft 官方维护（仓库 `microsoft/playwright-mcp`，作者为 Playwright 核心维护者 yury-s、pavelfeldman），Apache-2.0 许可。它是一个标准 MCP 服务，可经 `npx @playwright/mcp@latest` 以 stdio 启动，或以 `--port` 暴露 HTTP/streamable 端点，二者均可直接表达为本项目的 `McpServer`。其决定性优势在于**完全无人值守的 headless 服务端运行**：`--headless` 启动无 GUI 的 Chromium，官方 `mcr.microsoft.com/playwright/mcp` 容器镜像即为此场景而生，无需 OAuth 同意屏、CAPTCHA、扩展或真实用户登录态——浏览器由 MCP 服务进程自身拉起并驱动。鉴权经 `--isolated --storage-state=` 以非交互方式注入预置 cookie/localStorage，与 negentropy-ui 现有 dev-cookie storageState 旁路一一对应。它暴露约 22 个核心工具并以 `--caps` 按需开启扩展能力组，最新版本 v0.0.75（2026-05），由拥有 Playwright 本体的团队首方背书，弃坑风险在所有候选中最低。其主要成本杠杆是每步 a11y 快照（`browser_snapshot`）的 Token 膨胀，以及"非确定性"——MCP 驱动的回归是 AI 探索式的，而非确定性 PASS/FAIL 闸门。 -**chrome-devtools-mcp**[[2]](#ref2) 由 Google / Chrome DevTools 团队维护，Apache-2.0，原生 stdio（`npx -y chrome-devtools-mcp@latest`），可直接表达为 `McpServer`。它**能**经 `--headless --isolated` 或沙箱推荐的 `--remote-debugging-port` + `--browser-url` 路径无人值守 headless 运行（注意：`--autoConnect` 需真人在 `chrome://inspect` 点击"Allow"，属交互 A 类，不可用于 Routine）。其强项是深度 DevTools 内省（网络、控制台、性能 Trace、堆快照、Lighthouse），且基于 2026 年某结账流程基准，单任务 Token 较 Playwright MCP 低约 78%[[6]](#ref6)。但对本项目的**致命短板是无 storageState 机制**：会话/登录态完全绑定 Chrome 的 user-data-dir，现有 dev-cookie storageState 旁路无法迁移，`--isolated` 的 Routine 会话恒为登出态；获取鉴权会话只能预烘焙真实 profile 或脚本注入 cookie，与 [browser-validation.md](../../.agents/browser-validation.md) 红线冲突。它本质是调试/内省工具，而非断言优先的 E2E 驱动器。 +**chrome-devtools-mcp**[[2]](#ref2) 由 Google / Chrome DevTools 团队维护，Apache-2.0，原生 stdio（`npx -y chrome-devtools-mcp@latest`），可直接表达为 `McpServer`。它**能**经 `--headless --isolated` 或沙箱推荐的 `--remote-debugging-port` + `--browser-url` 路径无人值守 headless 运行（注意：`--autoConnect` 需真人在 `chrome://inspect` 点击"Allow"，属交互 A 类，不可用于 Routine）。其强项是深度 DevTools 内省（网络、控制台、性能 Trace、堆快照、Lighthouse），且基于 2026 年某结账流程基准，单任务 Token 较 Playwright MCP 低约 78%[[6]](#ref6)。但对本项目的**致命短板是无 storageState 机制**：会话/登录态完全绑定 Chrome 的 user-data-dir，现有 dev-cookie storageState 旁路无法迁移，`--isolated` 的 Routine 会话恒为登出态；获取鉴权会话只能预烘焙真实 profile 或脚本注入 cookie，与 `~/.agents/docs/browser-validation.md` 红线冲突。它本质是调试/内省工具，而非断言优先的 E2E 驱动器。 **claude-in-chrome**[[3]](#ref3) 为 Anthropic 首方的 Chrome 扩展集成（扩展 ID `fcoeoabgfenejglbffodgkkbkcdhcgfn`），经 `claude --chrome` 或 `/chrome` 启用，工具出现在内部 `claude-in-chrome` 命名空间下。它**并非** pip/pnpm/npx 包，**无法**经 mcp_config 注入——它是 native messaging 桥接，不是 stdio/sse/http server，无法表达为 `command/url` server。它**绝对无法** headless 无人值守运行：需要可见的桌面 Chrome/Edge 窗口，遇登录页/CAPTCHA 会暂停等待真人，MV3 service worker 空闲时会静默断连，且账号级竞争消费路由无设备锁定。其真正强项——零摩擦复用用户真实已认证桌面会话——恰恰是 Routine 所禁止的人在回路。 @@ -89,7 +89,7 @@ flowchart TD 1. **自治契合**：唯一同时满足"可表达为 `McpServer` + 完全 headless 无人值守 + 复用现有 dev-cookie 旁路"三项硬约束的成熟首方选项。Routine 配置基线：`--headless --isolated --browser chromium --no-sandbox`（鉴权回归再加 `--storage-state=`），并禁用 `browser_run_code_unsafe`。 2. **回归目的工具**：`--caps=testing` 提供 `browser_verify_element_visible/text_visible/list_visible/value` 等断言动词，可将关键路径钉为半确定性校验，弥补 AI 驱动回归的非确定性。 3. **复用既有 Playwright + dev-cookie**：`--storage-state` 直接消费 negentropy-ui `playwright.config.ts` 已验证的 storageState，无第二个 LLM、无云端外泄、无真实会话强制要求。 -4. **协议一致**：stdio/http 形态经单一 `mcp_config` 注入点统一喂入两类上下文，符合单一事实源；与 [browser-validation.md](../../.agents/browser-validation.md) 中 claude-in-chrome=交互 A 类、playwright(headless)=自治 B 类的分类一致。 +4. **协议一致**：stdio/http 形态经单一 `mcp_config` 注入点统一喂入两类上下文，符合单一事实源；与 `~/.agents/docs/browser-validation.md` 中 claude-in-chrome=交互 A 类、playwright(headless)=自治 B 类的分类一致。 **须诚实纳入的对抗性 caveat（经对抗校验保留）：** @@ -100,7 +100,7 @@ flowchart TD **须纳入的事实校正：** -- **dev-cookie 与红线的精确关系**：[browser-validation.md](../../.agents/browser-validation.md) 红线禁止的是**跨上下文复制 OAuth/SSO（IdP 绑定）storageState**，**并不**禁止项目自签的 **dev-cookie storageState**——后者经协议明确**许可**用于非 OAuth B 类场景（`apps/negentropy-ui/tests/e2e/dev-cookie.setup.ts`：以与后端共享的 `NE_AUTH_TOKEN_SECRET` 签发 `ne_sso`，写入 `.auth/dev-admin.json`）。故 Playwright MCP `--storage-state` 复用的是**被许可的 dev-cookie 路径**，绝非模拟 IdP 登录。此区分（dev-cookie 许可 / IdP-storageState-复制禁止）是承重的。 +- **dev-cookie 与红线的精确关系**：`~/.agents/docs/browser-validation.md` 红线禁止的是**跨上下文复制 OAuth/SSO（IdP 绑定）storageState**，**并不**禁止项目自签的 **dev-cookie storageState**——后者经协议明确**许可**用于非 OAuth B 类场景（`apps/negentropy-ui/tests/e2e/dev-cookie.setup.ts`：以与后端共享的 `NE_AUTH_TOKEN_SECRET` 签发 `ne_sso`，写入 `.auth/dev-admin.json`）。故 Playwright MCP `--storage-state` 复用的是**被许可的 dev-cookie 路径**，绝非模拟 IdP 登录。此区分（dev-cookie 许可 / IdP-storageState-复制禁止）是承重的。 **关于 ExecuteAutomation 备选的定位**：它是唯一受认可的跨浏览器/设备 fallback（提供官方容器所缺的 Firefox/WebKit + 设备预置），但 storageState 人机工程较弱且存单维护者供应链风险。仅当确需官方服务所缺的覆盖时按任务范围采用，**不取代** `@playwright/mcp` 默认地位。