NEW

Author: PythonnotJava

src/pkg/remindai/index.html

@@ -164,11 +164,11 @@ <h1>RemindAI Agent 工作流</h1>
 <h2 style="border:none;margin-top:4px;padding:0;font-size:16px;font-weight:500;color:var(--text2)">工具外壳、技能系统与持久记忆的工程实践</h2>
 
 <div class="meta-block">
-<strong>作者：</strong>RemindAI 团队 &nbsp;|&nbsp; <strong>版本：</strong>v1.0 &nbsp;|&nbsp; <strong>日期：</strong>2026年<br>
-<strong>摘要：</strong>本文系统阐述 RemindAI Agent 工作流的设计理念、核心架构与工程实现。RemindAI 提出 <strong>"Agent = LLM（决策推理）+ ToolShell（工具执行）+ Permissions（权限控制）"</strong> 的核心公式，通过五层分层架构（表现层、智能核心层、工具外壳层、工具生态层、基础设施层）和四大横向支撑系统（Memory、Schedule、Worktree、Security），构建了一个可控、可扩展、可记忆的 AI Agent 框架。本文详细分析了 Agent Loop 对话循环的工作机制、ToolShell 工具外壳的设计模式、Skill 技能系统的注入架构、MCP 协议的工具扩展能力、Memory 系统的持久化与召回策略，以及 Schedule 任务管理与 Worktree 隔离实验等关键子系统。
+<strong>作者：</strong>RemindAI 团队 &nbsp;|&nbsp; <strong>版本：</strong>v1.0.5 &nbsp;|&nbsp; <strong>日期：</strong>2026年7月<br>
+<strong>摘要：</strong>本文系统阐述 RemindAI Agent 工作流的设计理念、核心架构与工程实现。RemindAI 提出 <strong>"Agent = LLM（决策推理）+ ToolShell（工具执行）+ Permissions（权限控制）"</strong> 的核心公式，通过五层分层架构（表现层、智能核心层、工具外壳层、工具生态层、基础设施层）和四大横向支撑系统（Memory、Schedule、Worktree、Security），构建了一个可控、可扩展、可记忆的 AI Agent 框架。本文详细分析了 Agent Loop 对话循环的工作机制（含 DSML 兼容层、Tool Call 三层防御、Cache-Aligned 上下文压缩）、ToolShell 工具外壳的设计模式（含智能并行执行与资源冲突检测）、多 Agent 协作系统（Commander/Worker/Reviewer 角色体系）、Skill 技能系统的相关性路由与注入架构、MCP 协议的工具扩展能力、Memory 系统的双写容灾与软失效过滤、知识库的中文友好切块策略，以及宠物经济系统、在线协作服务与对外 API 服务器等完整功能矩阵。
 </div>
 <div class="meta-block" style="margin-top:-12px">
-<strong>关键词：</strong>AI Agent；ToolShell；Agent Loop；Skill 系统；MCP；持久记忆；工作计划管理；权限控制
+<strong>关键词：</strong>AI Agent；ToolShell；Agent Loop；Cache-Aligned 压缩；DSML 兼容层；多 Agent 协作；Skill 相关性路由；MCP；持久记忆；知识库；资源冲突检测；宠物经济
 </div>
 
 <!-- TOC -->
@@ -187,11 +187,14 @@ <h3>📑 目录</h3>
 <li><a href="#s10">Worktree 隔离实验</a></li>
 <li><a href="#s11">权限与安全模型</a></li>
 <li><a href="#s12">System Probe 环境探测</a></li>
-<li><a href="#s13">系统集成与工作流全景</a></li>
-<li><a href="#s14">实践经验与工程教训</a></li>
-<li><a href="#s15">相关工作与对比分析</a></li>
-<li><a href="#s16">未来展望</a></li>
-<li><a href="#s17">结论</a></li>
+<li><a href="#s13">多 Agent 协作系统</a></li>
+<li><a href="#s14">知识库与在线服务</a></li>
+<li><a href="#s15">宠物经济与 API 服务器</a></li>
+<li><a href="#s16">系统集成与工作流全景</a></li>
+<li><a href="#s17">实践经验与工程教训</a></li>
+<li><a href="#s18">相关工作与对比分析</a></li>
+<li><a href="#s19">未来展望</a></li>
+<li><a href="#s20">结论</a></li>
 </ol></div>
 
 <hr>
@@ -273,9 +276,10 @@ <h3>3.1 表现层（Presentation Layer）</h3>
 <h3>3.2 智能核心层（Intelligence Core）</h3>
 <p>智能核心层是 Agent 的"大脑"，负责决策和推理：</p>
 <ul>
-<li><strong>Prompt Engine（提示词引擎）</strong>：负责 System Prompt 的组装，包括 Skill 上下文的拼接、Memory 召回结果的注入、System Probe 结果的嵌入。这是决定 Agent "知道什么"的关键环节。</li>
-<li><strong>Context Manager（上下文管理器）</strong>：负责 Token 预算控制、滑动窗口裁剪和历史压缩摘要。</li>
-<li><strong>LLM Client</strong>：统一的 LLM API 调用层，支持 Anthropic、Gemini、OpenAI 等多种后端。</li>
+<li><strong>Prompt Engine（提示词引擎）</strong>：负责 System Prompt 的组装，包括身份锚定、当前日期注入、Skill 上下文的相关性路由拼接、Memory 召回结果的注入、System Probe 结果的嵌入。这是决定 Agent "知道什么"的关键环节。</li>
+<li><strong>Context Manager（上下文管理器）</strong>：<strong>Cache-Aligned</strong> 压缩策略实现 95%+ Prompt Cache 命中率；Token 预算驱动保留（25% 可用输入空间）；Output Reservation（12.8K tokens 预留输出）；超大工具结果压缩（>5000字符截断）；频繁压缩检测与自适应调整；记忆沉淀（压缩前提取值得记住的信息存入向量库）。</li>
+<li><strong>LLM Client</strong>：统一的 LLM API 调用层，支持 OpenAI / Anthropic / Gemini 三协议原生实现，含 DSML 兼容层处理 DeepSeek 非标行为、不完整 JSON 自修复、流截断恢复。</li>
+<li><strong>Hook 系统</strong>：8 个生命周期钩子（onSessionStart/End、onBeforeUserMessage、onBefore/AfterLlmCall、onBefore/AfterToolResult、onAgentDone），已实现 MemoryRecallHook、MemoryStoreHook、KbRecallHook、ScheduleHook、SystemProbeHook。</li>
 </ul>
 
 <h3>3.3 工具外壳层（ToolShell Layer）</h3>
@@ -401,6 +405,17 @@ <h3>4.3 循环效率优化</h3>
 
 <p><strong>原则三：结果标准化。</strong>工具执行的结果以结构化格式返回（包含状态码、stdout、stderr、图片路径等），便于 Agent Loop 解析和下一轮决策。</p>
 
+<h3>4.4 DSML 兼容层</h3>
+<p>DeepSeek 等模型有时不通过标准 <code>tool_calls</code> 协议返回工具调用，而是在文本内容中嵌入 DSML 标记。RemindAI 的 <code>_DsmlParser</code> 自动检测并解析这些非标输出，转换为标准 <code>ToolCall</code> 对象。支持三种变体前缀（全角/半角），确保无论模型以何种方式输出工具调用，Agent Loop 都能正确处理。</p>
+
+<h3>4.5 Tool Call 配对完整性（三层防御）</h3>
+<p>LLM API 要求每个 <code>tool_calls</code> 都必须有对应的 <code>tool</code> 结果消息。压缩、截断、中断等异常路径可能破坏这种配对关系，导致 HTTP 400 错误。RemindAI 构建了三层防御：</p>
+<ol>
+<li><strong>ContextCompactor 压缩清理</strong>：压缩边界切割时自动清理孤立的 tool_calls 和无主的 tool 结果</li>
+<li><strong>保真区向前/向后扩展</strong>：保留区包含 tool 结果时，自动扩展到对应的 assistant tool_calls；反之亦然</li>
+<li><strong>AgentLoop 发送前验证</strong>：最后一道防线，调用 <code>_validateToolCallPairing</code> 检测所有 assistant 的 tool_calls 是否都有对应结果，发现孤立项时自动修复而非报错</li>
+</ol>
+
 <hr>
 
 <!-- ===== 5. ToolShell ===== -->
@@ -467,7 +482,16 @@ <h3>6.2 Skill 工作流命令</h3>
 <li><strong>Install</strong>：调用 <code>toolshell_install_skill</code> 提升为全局技能，清理 staging</li>
 </ol>
 
-<h3>6.3 Skill 的价值</h3>
+<h3>6.3 SkillRouter 相关性匹配引擎</h3>
+<p>RemindAI 不会将所有技能无差别注入 System Prompt，而是通过 <code>SkillRouter</code> 进行智能相关性匹配，三层评分策略：</p>
+<ul>
+<li><strong>Pinned Skills</strong>：会话中被实际使用过的技能，后续轮次始终注入（满分 1.0）</li>
+<li><strong>关键词匹配</strong>：双向匹配——技能名出现在输入中加 0.5 分，反向关键词命中每个加 0.08，正向每个加 0.06。中文 bigram 分词 + 停用词过滤</li>
+<li><strong>语义匹配</strong>（可选）：实时计算用户输入与技能描述的 embedding 余弦相似度</li>
+</ul>
+<p>阈值 0.2，单轮最多注入 10 个技能。项目级技能始终全量注入不受路由限制。</p>
+
+<h3>6.4 Skill 的价值</h3>
 <ul>
 <li><strong>知识补全</strong>：为 LLM 提供它可能不知道的最新信息（如新框架的 API 用法）</li>
 <li><strong>规范固化</strong>：将项目编码规范、命名约定、架构决策固化为可复用的文档</li>
@@ -547,14 +571,17 @@ <h3>8.2 重要性评分</h3>
 <li><strong>0.1~0.4</strong>：临时信息、琐碎细节</li>
 </ul>
 
-<h3>8.3 召回策略（REMIND）</h3>
+<h3>8.3 软失效过滤（Supersede）</h3>
+<p>写入新记忆前，以 0.85 相似度阈值检索语义高度重合的旧记忆，标记为 <code>superseded=true</code>（不物理删除），召回时自动过滤被标记的旧记忆。典型场景：用户偏好变更时防止旧结论污染检索结果。这是 v1.0.5 引入的关键优化，解决了"过时记忆与新记忆同权重混合"的问题。</p>
+
+<h3>8.4 召回策略（REMIND）</h3>
 <p>当 <code>memory.json</code> 中 <code>REMIND=true</code> 时，每次新任务开始前 Memory 系统自动触发召回。召回策略有两种：</p>
 <ul>
 <li><strong>SQLite 关键词匹配</strong>：基于 SQLite 的 LIKE 查询进行关键词检索——始终可用</li>
 <li><strong>Qdrant 向量检索</strong>：如果配置了嵌入模型 API，则对记忆生成向量嵌入，使用语义相似度排序——可选启用</li>
 </ul>
 
-<h3>8.4 生命周期策略（MIND）</h3>
+<h3>8.5 生命周期策略（MIND）</h3>
 <p><code>memory.json</code> 中的 <code>MIND</code> 字段控制记忆的生命周期策略：</p>
 <ul>
 <li><strong>MIND=true（长期记忆）</strong>：跨会话持久存储，会话结束时记忆保留</li>
@@ -665,8 +692,90 @@ <h2 id="s12">12. System Probe 环境探测</h2>
 
 <hr>
 
-<!-- ===== 13. 系统集成 ===== -->
-<h2 id="s13">13. 系统集成与工作流全景</h2>
+<!-- ===== 13. 多 Agent 协作 ===== -->
+<h2 id="s13">13. 多 Agent 协作系统</h2>
+
+<p>RemindAI v1.0.5 实现了完整的多 Agent 协作框架，支持六种角色体系和多种通信机制。</p>
+
+<h3>13.1 角色体系</h3>
+<table>
+<tr><th>角色</th><th>职责</th><th>数量限制</th></tr>
+<tr><td><strong>Commander</strong></td><td>总指挥，拆解需求、分配任务、协调各 Agent</td><td>唯一</td></tr>
+<tr><td><strong>Worker</strong></td><td>通用工作者</td><td>多个</td></tr>
+<tr><td><strong>Reviewer</strong></td><td>审查员，校验其他 Agent 产出</td><td>多个</td></tr>
+<tr><td><strong>Researcher</strong></td><td>研究员，信息收集和分析</td><td>多个</td></tr>
+<tr><td><strong>Coder</strong></td><td>编码员，专注代码实现</td><td>多个</td></tr>
+<tr><td><strong>Custom</strong></td><td>自定义角色</td><td>多个</td></tr>
+</table>
+
+<h3>13.2 权限隔离</h3>
+<p>每个 Agent 独立配置权限集（fileRead/fileWrite/fileDelete/exec/network），工具加载时按权限过滤。Commander 默认拥有全部权限，Worker 按任务需求精确授权。</p>
+
+<h3>13.3 通信机制</h3>
+<ul>
+<li><strong>广播（Broadcast）</strong>：指挥部向所有 Agent 发送消息，注入 <code>[指挥部广播]</code> 前缀</li>
+<li><strong>点对点（Direct）</strong>：Agent 间直接通信，注入 <code>[发送者 对你说]</code> 前缀</li>
+<li><strong>自动路由</strong>：Agent 产出后自动将摘要注入其他 Agent 上下文；短内容直接转发，长内容（>300字）调用 LLM 压缩后转发</li>
+<li><strong>文件分发</strong>：支持向单个 Agent 发送文件或全局分发</li>
+</ul>
+
+<h3>13.4 Sub-Readers 并行理解编排</h3>
+<p>三阶段流程：<strong>规划</strong>（主模型拆解为 1-6 个不重叠子任务）→ <strong>并行执行</strong>（独立只读 Agent + ReadOnlyExecutor，通过 Future.wait 并行）→ <strong>合并</strong>（主模型去重汇总）。ReadOnlyExecutor 仅允许 read/search 两个工具，保证多 Agent 指向同一目录时无冲突。</p>
+
+<hr>
+
+<!-- ===== 14. 知识库与在线服务 ===== -->
+<h2 id="s14">14. 知识库与在线服务</h2>
+
+<h3>14.1 知识库系统</h3>
+<p>知识库系统实现了"文档 → 文本 → 切块 → 嵌入 → 写入 Qdrant"的完整索引流水线。</p>
+<ul>
+<li><strong>中文友好切块策略</strong>：默认 chunkSize=900、overlap=120。先按段落聚合，超长段落按句末标点切分，极端情况硬切。相邻块保留重叠维持上下文连贯。</li>
+<li><strong>多知识库独立检索</strong>：每个知识库使用独立 Qdrant collection + 独立嵌入模型配置，通过 KbRecallHook 在会话中按需接入。</li>
+<li><strong>文本提取</strong>：纯文本类直接读取，办公文档通过 pandoc/pdftotext 转换。</li>
+</ul>
+
+<h3>14.2 在线协作服务</h3>
+<p>基于 WebSocket 的在线多人协作服务，支持：</p>
+<ul>
+<li>内置完整 HTTP 服务器（静态资源 + WebSocket + 文件下载）</li>
+<li>白名单机制（IP 精确/CIDR 网段/通配符）+ 连接数限制 + 拉闸开关</li>
+<li>每个白名单条目独立分配模型卡、MCP 服务器、技能、搜索引擎</li>
+<li>Artifact 提取（从 LLM 回复中提取代码块）+ ZIP 批量下载</li>
+<li>管理员（localhost）完全控制，普通用户按白名单限制</li>
+</ul>
+
+<hr>
+
+<!-- ===== 15. 宠物经济与 API 服务器 ===== -->
+<h2 id="s15">15. 宠物经济与 API 服务器</h2>
+
+<h3>15.1 宠物经济系统</h3>
+<p>六层架构的完整养成系统：</p>
+<ul>
+<li><strong>数据层</strong>：精灵图元数据（帧尺寸、动画序列、FPS）</li>
+<li><strong>逻辑层</strong>：11 种状态 × 8 种事件的状态机，加权随机转换</li>
+<li><strong>引擎层</strong>：单 Timer 驱动帧推进 + 状态超时触发</li>
+<li><strong>注册层</strong>：内置 3 种猫咪精灵 + 用户自定义注册</li>
+<li><strong>观察层</strong>：12 种全局事件类型 + 3 分钟 idle 检测 + 50 条事件历史</li>
+<li><strong>经济层</strong>：Token→宠物币兑换 + 20 种食物商店 + 投喂/饱腹/心情 + 13 个成就</li>
+</ul>
+<p>所有 LLM 调用入口（主聊天/记忆提取/API 服务/在线服务）均计入 token 统计→兑换宠物币→驱动养成循环。</p>
+
+<h3>15.2 对外 API 服务器</h3>
+<p>内置 HTTP 服务器，提供三种独立端点：</p>
+<table>
+<tr><th>端点</th><th>路径</th><th>功能</th></tr>
+<tr><td><strong>OpenAI 聚合</strong></td><td><code>/v1/chat/completions</code></td><td>跑完整 AgentLoop（技能/MCP/记忆/搜索），流式/非流式</td></tr>
+<tr><td><strong>Claude 聚合</strong></td><td><code>/v1/agent/messages</code></td><td>同样跑聚合 Agent，以 Anthropic 协议输出 SSE</td></tr>
+<tr><td><strong>Claude 代理</strong></td><td><code>/v1/messages</code></td><td>纯协议转换透传，让任意模型伪装成 Claude</td></tr>
+</table>
+<p>安全设计：默认仅 127.0.0.1 + Bearer token 鉴权 + IP 白名单（CIDR）+ 三端点独立开关 + 记忆三档位（none/isolated/shared）。</p>
+
+<hr>
+
+<!-- ===== 16. 系统集成 ===== -->
+<h2 id="s16">16. 系统集成与工作流全景</h2>
 
 <p>将以上所有子系统串联起来，RemindAI 的完整工作流如下：</p>
 
@@ -690,8 +799,8 @@ <h2 id="s13">13. 系统集成与工作流全景</h2>
 
 <hr>
 
-<!-- ===== 14. 实践经验 ===== -->
-<h2 id="s14">14. 实践经验与工程教训</h2>
+<!-- ===== 17. 实践经验 ===== -->
+<h2 id="s17">17. 实践经验与工程教训</h2>
 
 <h3>14.1 实践案例：音乐播放器开发</h3>
 <p>作者手动编写了一个 8000 多行的音乐播放器，花了半个月时间。而用 RemindAI 开发同样的功能，只用了 <strong>10 分钟、2000 多行代码、8 毛钱的 DeepSeek V4 Pro API 费用</strong>。这背后是 Flutter CLI + Dart 编译器 + Android SDK 完整工具链的支持，以及项目规范和架构指导通过 Skill 系统的注入。</p>
@@ -715,8 +824,8 @@ <h3>14.3 常见反模式</h3>
 
 <hr>
 
-<!-- ===== 15. 相关工作 ===== -->
-<h2 id="s15">15. 相关工作与对比分析</h2>
+<!-- ===== 18. 相关工作 ===== -->
+<h2 id="s18">18. 相关工作与对比分析</h2>
 
 <table>
 <tr><th>维度</th><th>AutoGPT / BabyAGI</th><th>Claude Code / Codex CLI</th><th>RemindAI</th></tr>
@@ -737,8 +846,8 @@ <h2 id="s15">15. 相关工作与对比分析</h2>
 
 <hr>
 
-<!-- ===== 16. 未来展望 ===== -->
-<h2 id="s16">16. 未来展望</h2>
+<!-- ===== 19. 未来展望 ===== -->
+<h2 id="s19">19. 未来展望</h2>
 
 <h3>16.1 可视化 Skill 编辑器</h3>
 <p>当前的 Skill 和 Schedule 主要通过文本配置。一个可视化的拖拽式编辑器可以让非技术用户也能创建和定制 Agent 工作流。</p>
@@ -754,19 +863,22 @@ <h3>16.4 跨平台扩展</h3>
 
 <hr>
 
-<!-- ===== 17. 结论 ===== -->
-<h2 id="s17">17. 结论</h2>
+<!-- ===== 20. 结论 ===== -->
+<h2 id="s20">20. 结论</h2>
 
 <p>本文系统阐述了 RemindAI Agent 工作流的设计理念、核心架构与工程实现。我们提出了 <strong>"Agent = LLM + ToolShell + Permissions"</strong> 的核心公式，并通过五层分层架构和四大横向支撑系统将其工程化。</p>
 
 <p>核心贡献包括：</p>
 <ol>
 <li><strong>五层分层架构</strong>：表现层 → 智能核心层 → 工具外壳层 → 工具生态层 → 基础设施层，清晰的职责分离使得每一层可以独立演进。</li>
-<li><strong>Agent Loop 对话循环</strong>：七阶段循环（输入→组装→控制→调用→执行→捕获→反馈），形成了完整的"思考-行动-观察"闭环。</li>
-<li><strong>Memory 记忆系统</strong>：基于 SQLite 的持久记忆 + 可选的向量检索 + MIND/REMIND 灵活策略，让 Agent 具备了跨会话的学习和进化能力。</li>
-<li><strong>Schedule 计划管理</strong>：P0/P1/P2 优先级体系 + 自动拆解追踪，将 Agent 从"执行者"提升为"项目管理者"。</li>
-<li><strong>Skill 技能注入</strong>：项目级/全局技能的分层管理 + /skill-temp 和 /skill-cti 工作流，实现了知识的模块化和可复用。</li>
-<li><strong>Worktree 隔离实验</strong>：基于 Git 的隔离工作树 + Checkpoint 存档/回退机制，让探索性开发零风险。</li>
+<li><strong>Agent Loop 对话循环</strong>：七阶段循环 + DSML 兼容层 + Tool Call 三层防御，形成了完整的"思考-行动-观察"闭环。</li>
+<li><strong>Cache-Aligned 上下文压缩</strong>：复用原始消息前缀实现 95%+ Prompt Cache 命中率；Token 预算驱动保留（25%）+ Output Reservation（12.8K）+ 记忆沉淀 + 频繁压缩检测。</li>
+<li><strong>智能并行执行</strong>：资源冲突检测允许操作不同目标的写/删/执行并行，仅拒绝真正存在竞态的组合。</li>
+<li><strong>多 Agent 协作</strong>：六种角色体系 + 广播/点对点通信 + 自动路由 + Sub-Readers 并行理解编排。</li>
+<li><strong>Memory 记忆系统</strong>：SQLite + Qdrant 双写容灾 + 软失效过滤 + MIND/REMIND 灵活策略，让 Agent 具备跨会话学习和进化能力。</li>
+<li><strong>Skill 相关性路由</strong>：三层评分（Pin + 关键词 + 语义）的按需注入，解决了"System Prompt 过长导致性能下降"的问题。</li>
+<li><strong>Hook 系统</strong>：8 个生命周期钩子支持不修改核心循环即可扩展记忆/知识库/计划/探测等能力。</li>
+<li><strong>完整功能矩阵</strong>：知识库中文切块索引 + 在线协作服务 + 三端点 API 服务器 + 宠物经济养成闭环。</li>
 </ol>
 
 <p>在架构设计上，五层分层架构提供了清晰的职责分离，而横向支撑系统（Schedule、Worktree、Memory、Security、Logging）则为各层提供了非功能性的保障。这种"分层 + 横向"的架构模式，使得 RemindAI 既保持了系统各部分的独立性，又确保了整体的一致性。</p>