ETF Agent · Engineering Notes

从真实开发与故障出发，读懂一套 Agent 系统如何运行、演化与交付。

模块机制 × 架构思考 × AI Agent 研发工程 · 63 篇正文，三条主线

首要必读 · 六层调用全景 V3 · 架构原则 · 九条核心判断 · 模块维度 · 架构设计与系统思考 · AI Agent 研发工程实践 · 金融可信工程专题：合规·安全·韧性·留痕·审查 · 全部文章 · 个人博客

---

2026-10-26 · 研究推进的第二种阅读视角

六层调用全景 V3微调了研究推进的三个时间尺度；新增投研 Agent 的关键不是多调用工具：Model、Harness 与 Loop沿同一基金问题讲清模型判断、真实工具回执、重开研究问题、停放接续与交付。它不是六层的替代版本，也不新增独立研究调度器。两篇均提供完整中文与英文正文。

2026-10-26 · 一次重构，两种阅读视角

一个 Subagent 改动，为什么拖住了我们整整一天？复盘职责耦合、旧测试入口与并行整合的真实代价；Agent 架构如何做到该稳定的稳定，该变化的变化？用 Child、Memory、金融计算与 Provider 案例解释差异化演进契约。两篇均有完整英文版，分别收录于研发工程与架构思考，开头和文末互相引用。

新增架构原则：局部改善与系统进步

• 局部改善不等于整体进步——结合工具结果投影、Trace 与独立 Judge 的真实案例，区分局部修复、测量修正和完整任务的收益；对应第九核心原则。

新增模块实践：让用户自定义专家真正可用

• 自定义专家，不应该只是一个 Prompt 输入框：个人研究方法如何保存、冻结版本、正确送入 Child，并在 History 中保留真实归属；包含用户 Prompt 请求层级与设置页并发编辑的工程教训。原 Subagent 专文 继续解释通用执行底座。

最近的 Owner 专文：控制事件与 Provider 容量

• A08：Agent 收到控制指令后，为什么不能立刻执行 · A30：模型返回 HTTP 200，为什么下一次还要排队。两个独立模块案例均提供中文及完整英文版本；A32 模型目录边界则深化在既有 Provider 专文中，不增重复文章。

最近的机制文章：人机协作、时间与用量

• 持久 HIL：回答怎样回到原研究 · Temporal semantics：用户的今天与美股交易日 · Shadow Credits：用量事实与未知。三篇均已准备完整中英正文；主分类归模块维度，真实模型质量和生产资格不由文章入库证明。

多 Agent 投研系列：机制、视角与展望

• 当两个 Agent 开始直接对话：从反方价值读到真实消息、预算和恢复。
• 多视角 Agent 如何共同检验投资假设：六种投资方法怎样选择、共享事实、挑战关键前提并由 Main 综合。
• 从多个专家到一份研究：2026 架构展望：跨能力协作的目标、缺口和未来与单 Main 对照的验收标准。

自定义 Agent 仍是独立草稿，暂不纳入正式目录；展望文章不代表完整协作效果已验收。

初次访问：90 秒找到最相关的工程证据

两篇首要必读： 六层调用全景 V3 是运行地图，沿一次请求讲清会话、Main/Subagent、可选工具、发布与界面；Agent 架构原则与系统方法 是设计判断地图，归纳跨模块原则和按需工程方法。两篇共同服务后续模块精讲，不增加第四个文章分类。

本仓库是一套公开可读的 Agent 工程案例与技术文集，而不是 ETF Agent 的可执行开源实现。作者的前端背景见个人博客 About；下表按读者的关注点推荐最短路径。

关注方向	建议先读	可以观察到什么
AI-native 前端与交互	渐进式回答 → 异步研究的前端交付 → 答案发布与版本 → HTML/文件交付	分段正文、后台通知、重连重读、事件去重与 Host 交付边界；可另读Relay 数据建模案例
Agent 应用开发	六层调用全景 V3 → Model / Harness / Loop 研究推进 → Subagent → 自定义专家 → Python 工作台	工具调用、任务协作、资料处理、计算、错误恢复与产物交接
Agent 系统架构	模型/Runtime/MCP/Skill 分工 → 工具可见性与 A34 → A35 内容信任 → 授权与事实归属 → 否决权治理 → 架构演化与五不原则	为什么划分职责、如何控制局部失败影响、怎样降低长期复杂度
AI 辅助工程研发	Spec 与 Evidence → 分期交付 → 知识退役 → 测试生命周期 → 真实任务收敛	如何让 Coding Agent 从完整设计走向首份交付，同时不被旧规范与测试束缚

公开证据的边界： 本仓库的文章、架构图、目录源码与 GitHub Pages 构建流程 可以直接查看；博客站点源码也公开。ETF Agent 的核心应用源码和完整运行证据不在本公开仓库。文章记录特定版本的真实案例或设计判断，但不等于第三方已经复核生产级性能、长期成功率、用户业务收益或 AI-native 前端的完整运行 Demo。

从在线阅读站开始 · 博客与作者简介 · 金融领域案例专题

按问题选择阅读主线

阅读入口	回答的问题	范围
模块维度	Agent 如何运行？	31 篇 / 4 组，Entry、Web、PDF、MCP、Portfolio、Provider、Python、Memory、Runtime 与交付
架构设计与系统思考	为什么这样设计？	24 篇 / 4 组，Owner、授权、复杂度、恢复与演化
AI Agent 研发工程实践	如何持续开发和验证？	8 篇 / 2 组，Spec、分期交付、工程知识、History、假绿与任务收敛
金融科技 × Agent 专题	这些机制怎样进入金融业务？	跨分类风险与控制阅读地图；不作为第四个一级分类，不重复正文

交互式 Owner 架构图册：按完整能力及最终效果归属分类，保留已核实的专文与相关文章映射。研发规范文章不因涉及 Agent 就强行挂到运行时 Owner。

推荐起点

原则与方法： 核心判断与外围方法 · 现有文章深化与新题预告。两者是阅读导航，不计入 63 篇正文；仍以 book.mjs 为唯一文章分类与顺序来源。

模块： A08 持久控制 · A30 容量租约 · Provider 共享准入 · 定时研究 · Main 压缩 · Python 计算工作台 · Memory 持久效果 · Publication 独立发布

架构： 想聊就聊：异步后台研究 · 故障域感知切换 · 模型会理解，代码才授权 · 否决权与 Run 终结权 · 架构演化与五不原则

研发： Spec 与 Evidence · 周报分期交付 · 文档、History 与知识退役 · 测试生命周期 · 任务收敛

金融： 投顾与交易边界 · 金融数字复算 · Python 结果消费 · 可信证据链 · 持续投资研究的历史与论点

全部文章

阅读次序、侧栏与上一篇／下一篇的唯一结构来源是 book.mjs。同一读者问题由一篇主稿承接；旧链接保留合稿说明，不作为独立文章重复计数。

1 / 模块维度

进入在线目录 →

01 · 研究入口、阅读与计算（10 篇）

• Entry：为什么入口越来越简单
• Web：从搜索到连续阅读
• Agent 说“今天”时，到底是哪一天
• PDF：从文本到证据
• Subagent：从隔离到专业化协作
• 自定义专家，不应该只是一个 Prompt 输入框
• Adaptive Research 与 Python
• Python：从工具到计算工作台
• 把个人持仓接入 Agent：我们怎样设计一个只读金融 MCP
• 数据过期后的受控刷新

02 · 上下文、研究资产与知识（4 篇）

• 结果外置与完整性：模型到底读到了多少
• Main 压缩：摘要不改写原始事实
• Memory：遗忘已提交，回答却失败
• RAG：文档撤权与历史回放

03 · 运行时、扩展与观测（13 篇）

• Provider：统一接口之后，为什么还需要共享准入
• 模型返回 HTTP 200，为什么下一次还要排队
• Extension Host：从功能机到智能机
• 从接上 MCP 到真正用上工具：Agent 的接入链路怎样构建
• Tool Surface：Agent 有工具，模型为什么看不到
• A35 内容信任：Prompt Injection 不只是恶意文本
• 多生态 Hook：Claude、Pi 与 Codex
• 工具调用到模型输入的观测链
• Run 预算与约束治理
• Agent 的请求数、Token 与 Credits 记账
• Agent 收到控制指令后，为什么不能立刻执行
• 定时研究：会话结束后继续
• Langfuse：从 Trace 到可信观测

04 · 答案、发布与恢复（4 篇）

• Publication：为什么需要独立发布系统
• 渐进式回答如何保持连贯
• 异步研究：离开页面后怎样按时交付
• Agent 问完用户之后：持久人机交互

2 / 架构设计与系统思考

进入在线目录 →

按 Roadmap 的三项技术攻坚与金融业务价值验证方向组织成四组；每篇文章只收录一次，V1/V2 历史链接保持可访问。

01 · 深度持续研究（5 篇）

• 想聊就聊，没收 AI 对话框的中止按钮！一天让你的 Agent 支持异步后台深度研究
• 一份周报过去后，Agent 还记得为什么这样判断吗？
• HTML 保存了，为什么还是交付失败
• 故障切换：换路线，不重置任务
• Run 终结权、阶段预算与安全恢复

02 · Subagent 与专家（3 篇）

• 不止一个投资专家：多视角 Agent 如何共同检验投资假设
• 当两个 Agent 开始直接对话：有界多空协作的 Runtime 设计
• 从多个专家到一份研究：多层 Agent 协作的下一站（2026 展望）

关联阅读（以下两篇主分类为「模块维度」，不计入本组篇数）：

• Subagent：从隔离到专业化协作
• 自定义专家，不应该只是一个 Prompt 输入框

03 · 金融与工程（12 篇）

• 金融数据 MCP 为什么变成决策系统
• 从投资研究到投顾与交易的边界
• 金融数字的时点、口径与复算
• Python 算过了，投研报告为什么还会错
• 金融 Agent 的可信证据链
• 投研 Agent 的关键不是多调用工具：Model、Harness 与 Loop
• 很多引用为什么不等于可靠
• 一个 ETF 投资助手的工程起点
• 代码越来越便宜，为什么系统却越来越难升级？
• Agent 架构如何做到该稳定的稳定，该变化的变化？
• 别把每个失败都算给模型
• 局部改善不等于整体进步：怎样判断 Agent 真的变好了？

04 · 其他（3 篇）

• 六层调用全景 V3：从提问到答案可见
• 模型会理解，代码才授权
• 别让模型当状态机
• Model / Runtime / MCP / Skill 的分工

3 / AI Agent 研发工程实践

进入在线目录 →

01 · Spec、证据与工程记忆（3 篇）

• Spec、Evidence 与可验证研发关闭
• 周报做了整晚，为何首份交付还没完成？
• 工程知识：按需加载、长期记忆与退役

02 · 真实验证与任务收敛（5 篇）

• Open ETF Agent v0.1：从第一份可回读报告开始
• 测试与评测：绿灯究竟证明什么
• 测试也会过期：把重构、退役和删除前移到 Spec
• 一个 Subagent 改动，为什么拖住了我们整整一天？
• 从 Bug 循环到完整任务收敛

延伸阅读与边界

• 金融科技 × Agent 主题阅读：跨分类精选，不另外生成文章副本。
• Agent 架构原则速查：用于设计、重构与 Code Review 的判断清单，不计入 63 篇正文。
• 架构图册 · 工程选题预告 · 六层系统图文版
• 个人博客：按时间阅读的文章；此仓库用于主题与连续阅读。新收录的 Spec、History 文章保留博客原文链接。

正文记录特定时间点的工程事实、问题和验证边界；内部通过、正式关闭、公开发布和真实业务效果是不同事实。本文集不构成投资或法律建议。

本地检查

npm install
npm run check:catalog
npm run docs:build

六层架构的历史版本

当前目录仅收录六层调用全景 V3。V2 全文（2026-10-23）与V1 全文（2026-10-20）保留独立网址、原始正文和版本演进说明，不计为新增当前文章；历史全文与合并到主稿的旧入口是两种不同处理方式。

已合并文章的旧链接

旧版 023 发布治理、runtime-natural-language-boundary 和 028 反馈专题仍保留指向现有主稿的合稿引导，不另算正文。不为分类调整创建旧文章副本。

English editions / 双语发布

The Chinese originals remain at /articles/<slug>. Reviewed complete English translations use /en/articles/<slug>; both editions share the same stable slug, canonical category and order in book.mjs. book.en.mjs holds only English display labels and the list of actually translated slugs, never a competing article index. The English catalog marks untranslated essays “Chinese original.”

• Open ?lang=en or ?lang=zh on a site page to set the language preference; the reader switcher stores etf-agent:language in localStorage. A URL parameter overrides storage. Direct /en/ links select English.
• The language switch preserves equivalent article paths only when a complete translation exists. Otherwise the Chinese original remains visible with a clear availability notice, never a fake translation.
• For each newly approved article, publish and review both articles/<slug>.md and en/articles/<slug>.md, register its English title and translated slug in book.en.mjs, and run npm run check:catalog && npm run docs:build. English must preserve code, evidence status, warnings, dates, diagrams, and citation semantics. Do not label a placeholder translated.
• Existing Chinese-only articles are not claimed to have English translations.

Bilingual diagrams and illustrations / 图表双语规则

Each English article is a full Markdown edition, not a summary. Mermaid source for each article is localized inside the corresponding language's Markdown: Chinese diagram nodes and edge labels in articles/<slug>.md, English nodes/edges in en/articles/<slug>.md. Technical identifiers and stable field names remain unchanged; decision conditions, failure branches and connector counts must match. Markdown table headings and cell descriptions are translated too.

Language-bearing SVG, HTML illustrations and image captions must be localized separately: prefer visuals/<slug>/... for the Chinese edition and visuals/en/<slug>/... for English, with the English article linking its localized asset. Truly language-neutral images may be shared; do not link Chinese-labeled SVG/HTML from English pages. Diagram links, image URLs and figures must survive GitHub Pages base-path resolution. Standalone interactive HTML visualizations need independently localized UI labels and text; translating the linking article is not enough.

Run npm run check:catalog to validate canonical slugs, route tests and bilingual visual structure (Mermaid blocks, table rows, image counts, and Chinese text in English Mermaid/SVG/HTML). Review diagram semantics manually: structural checks cannot translate embedded screenshots or certify semantic equivalence.

The first retrospective translation batch adds seven complete articles: long-term Memory, RAG revocation, investment research authorization, coding-agent task convergence, the project origin story, tool lifecycle tracing, and false-green test evidence. Combined with the earlier tool-result essay there are eight complete English article editions in this batch's snapshot; the authoritative live list is book.en.mjs, not this count.

唯一正式发布链 / One canonical publication path

公开正文只由 hpoenixf/myblog-v2 发布到 **https://hpoenixf.com/eff-agent-article/**。 本仓库是唯一文章源；每次发布由博客仓库的 reader-source.json 锁定已审核 source commit 及本次中英正文 SHA-256。文章源提交通过检查以后，仍须更新并提交博客发布锁，等待其 Pages 部署并读回新域名的 reader-release.json 和实际正文，才算发布完成。

本仓库 CI 保留目录、双语、构建检查，但给旧 github.io Pages 上传的只有逐页跳转， 没有第二套正文或静态应用资产。旧中英文、历史版本和图册 URL 跳到新域同路径，保留 查询参数与章节 hash。不要恢复独立正文部署，也不要用文章仓库 CI 代替新域名验收。

The article repository is the source, not a second publishing owner. The blog's immutable release pin selects the source commit; its deployment receipt and exact public HTML bytes must agree on the canonical domain. Legacy GitHub Pages serves redirects only.