设计文档索引

design/ 已于 2026-07-16 并入本目录，不再分两处。原因：那条界线是历史形成的 （design/ 早期放专题/重构笔记，docs/ 放主设计文档），但两边都在长，且 「这份算专题还是主文档」没有可判定的标准——查文档的人只想知道它在不在、 现在还算不算数。跨目录相对链接（../docs/…）也是纯粹的税。 老路径 design/xxx.md 一律改到 docs/xxx.md，文件内容与 git 历史（rename）不变。

先读：design-principles.md —— 项目级硬约束的唯一出处 （§1 无真实需求不建 / §2 框架无关 / §3 一个 ChatClient 绑定一个 TCM，不跨边界）。 提新抽象、审 PR、写新设计文档时援引它，不要重新推导一遍。

约定：每份文档头部有 状态： 行，是该文档当下是否算数的唯一判据—— ✅ 已实施 / 🚧 进行中 / 🗑️ 已废弃留档。先看状态再读正文。

---

权威参考（讲某个体系「现在长什么样」）

文档	讲什么
filter-chain-design.md	Filter 体系整合权威参考：洋葱机制、装配期预编译、:tool/:chat/:iteration/:turn 四链的粒度与契约、递归重入、内置 filter、硬规则
token-stream-filter-design.md	第五钩子 :token-xform（transducer 变换出站 token 流）的权威参考。四条 around 链见上一份，本文只讲 token 粒度
hitl-timeline-design.md	HITL（暂停/resume/审批）与 Timeline 多分支的整合权威参考
agent-loop-concurrency-design.md	Agent 并发模型：§9 工具批 MapReduce（:writes + :state-slots 屏障折叠）、§11 暂停持久化、§12 timeline
tool-calling-manager-design.md	工具执行引擎（线程模型 + 隔离边界 + 调度策略）；含 deftool :backend 的否决记录（§5）
advisor-alignment-design.md	逐个对齐 Spring AI 2.0 Advisor：有什么、对应什么、吸收还是不跟、为什么

设计中（🚧 已定稿未施工）

文档	讲什么
agent-runtime-design.md	新建 clj-agent-agui 模块：借鉴 CopilotKit runtime 的「run 与 HTTP 请求解耦」机制并原生实现（会话注册表 + 有界事件缓冲 + :seq 偏移续传 + 跨请求 stop/resume），从而不需要它的 remote agent。§6 是对现有框架的强化清单（框架侧只有 resume 收不到 :on-token/:cancel-token 一处必须改），§7 是能力缺口清单（真缺的只有跨 run 共享状态；前端工具是既有 HITL 词汇的一个用法）。也是一份「抄一半」的记录：事件折叠 / 事件日志持久化 / Runner 协议 / 全局单例 / hooks 逐条否决并记明重启条件

已实施（专题 / 重构记录）

文档	讲什么
provider-variant-design.md	一个标准 provider 如何承载多套厂商方言（MiniMax thinking）：三类差异三种机制，不动 ILLMProvider 而用可选协议 + satisfies? 探测。修了 config 白名单（provider 专属键递不到底）与 thinking 回传丢失（实测正确率 100%→82.5%）。也是「预注册判据双向作数」的范例：判据先否掉一次、卡住一次，最后才放行同一个结论
tool-timeout-design.md	工具超时：借鉴 beamai 但不照搬三层（JVM 无 exit(Pid,kill)，超时=放弃等待≠终止执行）。修了 :timeout 死选项与 timeout-filter 平台线程两个真 bug；§5.7 记工具声明查询合成 ToolMeta 一张表 + 同名工具装配期拒绝
streaming-async-design.md	真增量 SSE 传输选型 + 异步框架整合。也是 §2《框架无关》的出处
async-chat-model-design.md	异步入口全链路：可选协议 IAsyncChatModel / IAsyncLLMProvider + satisfies? 探测 + 虚拟线程兜底、retry/run-async、post-stream-deferred、react 循环同步/异步同源。也是「判据被越过」的记录（P2 的门槛写在 §2，本轮按指示提前实施，判据不撤销）
onion-filter.md	洋葱式 filter + chat-client 瘦身（loop/memory 下沉 client 模块）
memory-filter-refactor.md	消除显式 Context，转向 Memory Filter + 中立消息
unified-invoke-agent.md	统一 invoke + 合并 Agent
response-path-consolidation.md	D6/D7：响应路径整理、core 收回厂商 wire 知识、双消息体系统一
error-model-unification.md	D5：一个 canonical 错误值 + 四条边界信封规则（修了 401 被误标可重试的真 bug）
mcp-module-design.md	clj-agent-mcp 模块：按 MCP 2026-07-28 实现 client + server 两侧（Streamable HTTP + stdio），并双时代兼容 initialize 握手的老实现。记了判时代的规则表（两条反直觉：-32021/-32020 不回退；回退判据不得只认一个错误码）、三处施工时才看清的坑（_meta 不能按版本号猜、MCP Apps 的键是 _meta.ui.resourceUri、服务端默认不外泄异常消息），以及 6 条否决记录（MRTR 状态机 / 长流 / OAuth / 已废弃的 roots·sampling·logging …）
subagent-event-attribution-design.md	子 Agent 事件归属：三个中立事件 :subagent/started|finished|error + :subagent-run-id 打在 lane 事件上。agui.subagent 把 subagent/manager 的协议无关钩子翻译成 lane 发射器，§7 逐条记否决（delegations 状态槽 / lane 级插件 / 子 agent HITL …）

已废弃留档（🗑️ 不代表现状，只留教训）

Process 框架（V1/V2/Timeline）于 2026-07-11 整体删除，重新思考的结论落在 agent-loop-concurrency-design.md。以下三份只作教训留档，不是现行设计：

文档	为什么留
process-framework-design.md	V2 曾完整落地并全绿，当天判定有结构性问题、整模块删除
process-parallel-design.md	并行化方案，随上者一并撤下
timeline-snapshot-checkpoint.md	旧 Timeline；唯一消费者是 process 快照，一并撤下。旧 Timeline 的教训来源（现行 Timeline 见 hitl-timeline-design.md）