docs(v2): 补齐会话、团队协作与 Agent 检索说明

.release-notes/codex-docs-v2-workflows.md

@@ -0,0 +1,6 @@
+# V2 会话与团队使用说明
+<!-- release-target: v2 -->
+
+## Bug 修复
+
+- 补齐会话索引与继续工作、团队协作和 Agent 检索的操作说明，明确离线阅读、导出恢复及搜索范围，修正团队指南中过时的 CLI 限制说明。

docs/README.md

@@ -8,9 +8,10 @@
 | --- | --- |
 | 安装、更新、回滚或卸载 | [安装指南](../Install.md) |
 | 使用稳定版 | [V1 指南](v1/guide.md) · [English](v1/guide.en.md) |
-| 开始使用 V2，搜索和恢复会话 | [V2 使用指南](v2/guide.md) |
-| 连接团队、Pull/Push、分享会话或管理资源 | [团队空间](v2/team-workspace.md) |
+| 开始使用 V2，搜索和恢复会话 | [V2 使用指南](v2/guide.md) · [会话生命周期](v2/session-lifecycle.md) |
+| 连接团队、Pull/Push、分享会话或管理资源 | [团队协作流程](v2/team-collaboration.md) · [团队空间操作](v2/team-workspace.md) |
 | 编写团队资产清单，了解安装和恢复规则 | [团队资产参考](v2/team-assets.md) |
+| 让 Agent 查找处理经验、规范和 Skill | [Agent 检索指南](v2/agent-search.md) |
 | 用命令行配置团队、查询会话和资源 | [CLI 使用与配置](v2/cli.md) |
 | 处理 Electron 安装失败 | [安装排障](troubleshooting-electron-installation.md) |
 

docs/spec/README.md

@@ -11,6 +11,7 @@
 | [架构与数据边界](architecture.md) | V1/V2/CLI | 哪一层拥有操作、数据和生命周期 |
 | [会话索引](session-indexing.md) | V1/V2 | 文件观察状态与持久化状态、增量、重建、查询 |
 | [团队资产](team-assets.md) | V2/CLI | Pull/Push 的阶段、输入输出、归属和冲突矩阵 |
+| [会话与资源检索](knowledge-search.md) | V2/CLI/MCP | 范围、结果模型、分页、权限与本地读取 |
 | [Runtime](runtime.md) | V2 | 请求、调用记录、原生会话与终态顺序 |
 | [Workflow](workflow.md) | V2 | 图版本、调度、节点状态、事务与恢复 |
 | [Eval](evaluation.md) | V2 | 实验对象、产物来源、判断证据和后台运行 |

docs/spec/architecture.md

@@ -8,7 +8,7 @@
 | --- | --- | --- |
 | V1 Electron | 稳定版会话查询、管理、恢复和个人同步 | SQLite；独立应用数据和更新通道 |
 | V2 Electron | 会话体验，以及 Runtime、Workflow、Eval、Memory、Skill 库和团队空间 | PostgreSQL；不隐式导入 V1 数据 |
-| CLI | 无桌面的团队配置与资产管理 | 使用 workspace-core；当前不提供桌面全部能力 |
+| CLI | 独立团队配置与资产管理，以及连接 V2 的会话/资源检索 | 资产操作使用 workspace-core；检索复用 V2 本地服务，不直接访问数据库 |
 | workspace-core | 团队配置、Git 资产、安装归属和分发 | 不依赖 Electron；CLI 和 V2 主进程共同调用 |
 
 两版可以读取相同编码 Agent 的源文件，但各自持有索引。源文件、索引、用户整理状态和远端分享不是同一个数据副本。隔离理由见 [ADR 0001](../adr/0001-product-data-isolation.md)。

docs/spec/knowledge-search.md

@@ -0,0 +1,84 @@
+# 会话与资源检索契约
+
+范围：V2 的 `KnowledgeSearchService`、CLI 查询入口与 MCP 直接工具。本文描述当前实现，不表示所有来源已提供相同搜索语义。V1 继续使用自己的会话 MCP 和 SQLite 索引，不读取 V2 团队副本。使用示例见[Agent 检索指南](../v2/agent-search.md)，设计取舍见 [ADR 0011](../adr/0011-separate-agent-search.md)。
+
+## 调用链与所有权
+
+```mermaid
+flowchart LR
+    CLI[CLI session / resource] --> Bridge[认证的本地桥接]
+    MCP[MCP 直接工具] --> Bridge
+    Bridge --> Gate[当前来源和工具权限]
+    Gate --> Search[KnowledgeSearchService]
+    Search --> Local[本机会话查询与读取]
+    Search --> Team[团队本地会话服务]
+    Search --> Assets[托管 Skill / 团队工作副本]
+```
+
+CLI 不连接 PostgreSQL，也不解析原始 Agent 日志。服务复用已有索引和工作副本，不新建搜索数据库，不在查询过程中隐式 Pull 或补全远端正文。后续模型如何使用返回内容属于调用方行为。
+
+| 所有者 | 责任 |
+| --- | --- |
+| [CLI 命令解析](../../apps/cli/src/cli.ts) | 校验命令支持的参数，转换为请求，检查最终终端输出大小 |
+| [CLI 传输](../../apps/cli/src/search-client.ts) | 读取 V2 连接信息、认证请求、限制响应长度、释放响应 reader |
+| [Automation 服务](../../apps/main-2.0/src/main/services/automation-service.ts) | 将查询接入桥接并执行来源和工具开关检查 |
+| [检索服务](../../apps/main-2.0/src/main/services/knowledge-search-service.ts) | 严格解析输入、选择范围、验证团队引用、限制完整回复 |
+| 会话 store / 团队服务 / workspace-core | 保有原数据和领域规则；检索层不直接维护另一份副本 |
+
+## 范围与返回模型
+
+| 操作 | 本机范围 | 团队范围 |
+| --- | --- | --- |
+| searchSessions | 转发 query、source、project、limit 到本机会话查询 | 调用指定团队的本地分享搜索，返回 page、hasMore、pageSize、items |
+| getSession | 转发 sessionKey、offset、maxMessages，按消息读取 | 按分享版本选择 record，再读取轮次目录或指定 turnId |
+| searchResources | 本机托管 Skill 条目 | 团队工作副本里的 Skill、文档、共享指令 |
+| getResource | 用 id 与 type 定位正文 | 同时用团队范围、id 与 type 定位正文 |
+
+会话与资源不混排；会话的本机响应沿用已有查询接口，不能假定它与团队 items 具有同样封装。团队搜索的一项是一份分享，match 可指向其中某个子会话的轮次；不得把它拆成多份虚构分享。
+
+默认 scope 为 local。team 必须指定 teamId；local 带 teamId 会拒绝。团队会话不接受 source/project 筛选；本机会话不接受团队分页或 includeTools。分页方式与数值上限由 [CLI 参考](../v2/cli.md#分开搜索会话与资源)维护，调用方不能混用。
+
+## 资源匹配与分页
+
+资源查询 trim 后按空白分词，对标题、说明和完整正文拼接结果进行大小写不敏感的包含判断，所有词都必须匹配。它不是向量检索，不计算统一相关性分数；结果顺序沿用资源枚举顺序，调用方不能宣称第一项一定最相关。
+
+搜索只返回 id、type、title、scope、teamId、description、snippet 以及 nextOffset，不直接返回完整 content。snippet 从正文中第一个查询词附近取片段；若命中只在标题或说明，正文片段不一定包含命中词。调用方应继续读取原文确认。
+
+读取返回 content、totalChars、nextOffset。offset 按 JavaScript 字符串切片位置解释，不是 UTF-8 字节偏移或用户可见字形数量。后续分页使用返回的 nextOffset，不能用终端显示宽度自行推算。
+
+当前分页没有冻结资源快照。分页期间内容变化时，调用方需要重新搜索和读取；不能将多次请求拼接后视为同一版本的强一致快照。资源大小、结果条数和回复字节数是不同边界。
+
+## 团队会话引用
+
+团队搜索返回的 sessionKey 使用 `shared:` 前缀，编码团队 ID、仓库、分享 ID 和摘要。它是定位信息，不是访问令牌，也不是可执行路径。
+
+读取时重新解析引用并验证当前团队配置。仓库改变时拒绝旧引用；分享版本或本地准备状态由团队服务进一步校验。调用方应保留服务返回的完整键，不用标题、作者或列表序号替换。
+
+record 默认为主会话。未提供 turnId 时读取对应记录的轮次目录；提供 turnId 时读取具体轮次。普通本机会话不接受 record/turnId 的团队定位语义。超大单轮仍受完整回复上限约束，没有以静默截断工具输出绕过限制的路径。
+
+## 权限与传输
+
+会话查询受会话工具源及搜索/读取工具开关控制；资源查询还需满足 Skills 来源及对应基础工具和资源工具的开关。CLI 复用服务端验证，不能因它不是 MCP 客户端而跳过权限。
+
+CLI 读取 V2 的桥接发现文件，只接受 `127.0.0.1`、有效端口和规定格式的 token；不接受远程主机或 HTTP 重定向。连接信息损坏、应用未运行、连接失败或超时都返回错误。不要将该发现文件或 token 放入共享仓库。
+
+检索不会列出 MCP/Env 配置，但文档、Skill 和会话正文自身可能包含敏感信息。限定资源类型不是通用脱敏器，也不构成对正文安全性的保证。
+
+## 失败与兼容
+
+| 条件 | 行为 |
+| --- | --- |
+| 未知字段、非法类型或分页参数 | schema 拒绝，不猜测用户意图 |
+| 团队关闭、缺少团队 ID 或范围不匹配 | 拒绝对应查询，不自动切换到默认团队 |
+| 分享未整理或版本不匹配 | 返回本地读取错误，由用户主动 Pull 或重新搜索 |
+| 资源已删除 | 报资源不存在，要求重新搜索 |
+| 完整回复超过限制 | 报错，不截掉尾部后标记成功 |
+| 桌面未运行或连接信息无效 | CLI 提示启动或重启 V2 |
+
+当前没有跨本机与多个团队的聚合搜索、资源语义排序、搜索驱动的自动安装，以及脱离 V2 的会话检索进程。添加这些能力需要明确新的范围和生命周期，不能作为一次查询的隐式副作用。
+
+## 验证入口
+
+[检索服务测试](../../apps/main-2.0/src/main/services/knowledge-search-service.test.ts)覆盖资源与会话分流、关键词匹配、正文分页、团队范围、旧仓库引用、非法参数及完整回复字节限制。[CLI 传输测试](../../apps/cli/test/search-client.test.ts)覆盖连接边界。服务测试存在不等于每个 Agent 客户端已经完成真实联调。
+
+修改时优先保护：查询不联网同步、团队不可串读、关闭工具后不能通过 CLI 绕过、正文超限明确报错、分页参数不在本机与团队之间混用。示例和测试均使用合成内容，不读取开发者真实会话或凭据。

docs/spec/mcp.md

@@ -64,6 +64,8 @@ V2 为 Codex 和 Claude Code 管理名为 agent-recall 的 Gateway 配置。客
 
 ## 会话与资源搜索
 
+查询分流、引用身份、分页一致性和传输失败的完整契约见[检索规格](knowledge-search.md)，操作示例见[Agent 检索指南](../v2/agent-search.md)。
+
 V2 Gateway 的 search_sessions/get_session 和 search_resources/get_resource 分别处理历史过程与可复用资源，不合并排名。CLI 的 session/resource search/get 使用同一已认证本地桥接；范围、分页、限制由 [CLI 指南](../v2/cli.md#分开搜索会话与资源)维护。V1 沿用独立 SQLite 会话 MCP，不读取 V2 团队数据。
 
 [搜索服务](../../apps/main-2.0/src/main/services/knowledge-search-service.ts)校验所有请求，复用本机会话 store、团队会话服务和团队资产工作副本。团队引用包含仓库及分享摘要，每次读取重新验证配置；团队关闭或仓库改变后拒绝旧引用。资源不包含 MCP/Env。没有额外磁盘索引或数据库迁移。

docs/v2/agent-search.md

@@ -0,0 +1,77 @@
+# 让 Agent 检索会话与团队资源
+
+要找“以前怎么解决”，搜索会话；要找“现在应该遵守什么”，搜索文档、Skill 或共享指令。两条检索入口分开，不混合排名。CLI 命令表见[CLI 指南](cli.md#分开搜索会话与资源)，接口契约见[检索规格](../spec/knowledge-search.md)。
+
+## 准备条件
+
+- 启动 AgentRecall V2，保持运行。CLI 配置管理可独立运行，检索命令需要 V2 提供本地服务。
+- 本机会话先完成来源索引；团队会话先 Pull 并完成本地整理。
+- 在 MCP 页面启用所需来源和工具。CLI 检索也遵守这些开关。
+- 搜索团队时开启团队功能，明确选择团队；本机范围不会自动搜索所有团队。
+
+使用 MCP 时，按[Gateway 连接说明](guide.md#7-通过-mcp-gateway-使用工具)接入客户端。使用 CLI 时先按[CLI 包说明](../../apps/cli/README.md)构建安装；当前仍是源码预览包。
+
+## 找到处理过程，再读命中的轮次
+
+以下命令中的团队 ID、会话键和轮次 ID 均需替换为本机返回的值。
+
+```sh
+agentrecall team list
+agentrecall session search "端口冲突" --scope team --team engineering
+agentrecall session get '<返回的 sessionKey>'
+agentrecall session get '<返回的 sessionKey>' --record 0 --turn '<命中的 turnId>'
+```
+
+搜索命中附带轮次位置时，使用返回的 record 和 turnId；不要总是假设命中主会话的第一轮。没有正文命中位置时先读轮次目录，再选择需要的正文。会话键是返回的标识，不是可自行拼接的文件路径。
+
+本机历史使用 `agentrecall session search "端口冲突"`，读取按消息分页；团队历史按分享、子会话和轮次组织。具体分页参数见 CLI 指南。需要查日志时，团队搜索可加 `--include-tools`；未开启时不要将“没搜到日志”解释为内容丢失。
+
+## 找到规范，再读原文
+
+```sh
+agentrecall resource search "代码审查" --scope team --team engineering --type skill
+agentrecall resource search "部署 回滚" --scope team --team engineering --type document
+agentrecall resource get '<返回的 id>' --scope team --team engineering --type document
+```
+
+搜索返回摘要，读取返回正文；正文有 nextOffset 时继续传入该 offset，直到获得所需范围。读取必须沿用搜索时的团队和资源类型，资源 ID 单独并不足以确定范围。
+
+当前资源搜索是大小写不敏感的关键词包含匹配，空白分隔的词必须全部出现，可以分布在标题、说明和正文中。`部署 回滚` 因此比 `部署` 更严格。没有结果时可减少词数或换成文档实际使用的术语，不把它当成语义搜索。
+
+## 搜索覆盖什么
+
+| 范围 | 会话搜索 | 资源搜索 |
+| --- | --- | --- |
+| local | 本机已索引会话 | 本机托管 Skill 库 |
+| team | 指定团队已整理的完整分享与片段 | 本地团队工作副本中的 Skill、文档、共享指令 |
+
+团队资源包括本机尚未 Push 的修改，所以 A 和 B 在各自电脑上可能搜到不同版本。搜索不会主动 Pull，也不会替用户发布草稿。资源搜索不扫描任意个人目录，不覆盖 MCP 和 Env 配置。
+
+## MCP 中的对应操作
+
+| 意图 | 工具 |
+| --- | --- |
+| 找会话 | `search_sessions` |
+| 读会话或命中轮次 | `get_session` |
+| 找规范与 Skill | `search_resources` |
+| 读资源正文 | `get_resource` |
+
+这四个工具可直接使用，不必先通过 `search_tools` 查找。目录可见、工具已启用、具体读取成功是不同状态；实际操作仍会验证当前权限和团队配置。
+
+## 检索结果怎么使用
+
+先用标题和摘要选择，再读取原文核实结论、上下文与适用范围。会话说明曾经发生什么，不能自动取代当前规范。引用结果时保留团队、资源或会话标识，必要时注明片段范围；只读过摘要时不要声称已经审阅完整历史。
+
+检索到 Skill 不会自动安装它，读到共享指令不会自动写入客户端配置。团队资源安装由 Pull 分发负责；Agent 是否读取普通文档由当前任务和客户端行为决定。
+
+## 常见问题
+
+| 情况 | 处理 |
+| --- | --- |
+| 提示先启动 V2 | 启动或重启 V2，再运行命令 |
+| 桌面能看，CLI 被拒绝 | 检查对应 MCP 来源和工具开关，以及团队范围 |
+| 团队无结果 | 确认团队 ID、Pull 整理状态和实际关键词 |
+| 仓库改变或旧引用失效 | 重新搜索，再读取新返回的引用 |
+| 完整响应超限 | 缩小读取范围；单个团队 Turn 仍过大时不能靠减小搜索条数解决 |
+
+检索只访问本机服务，但调用它的 Agent 可能把返回正文放入所选模型的上下文；不要把“检索不联网”理解为后续模型调用不会传输这些内容。

docs/v2/cli.md

@@ -161,6 +161,8 @@ ID 使用小写字母开头，后续可包含小写字母、数字和连字符
 
 ## 分开搜索会话与资源
 
+完整的“搜索 → 选结果 → 读原文”示例与排障见[Agent 检索指南](agent-search.md)。
+
 这组只读命令连接正在运行的 AgentRecall V2，复用其本地搜索服务；无需单独启动数据库。它不触发 Pull、网络会话补全或上传。其他配置、资产管理命令仍可脱离桌面使用。
 
 ```sh

docs/v2/guide.md

@@ -6,6 +6,8 @@ AgentRecall v2 是预览版，提供会话搜索和整理，也包含 Runtime、
 
 v2 使用独立的启动命令、应用数据和数据库，可以和 v1 同时运行，默认不会自动读取 v1 数据；如需迁移，可在 **设置 → 关于 → V1 数据迁移** 中手动导入。
 
+专题阅读：[会话从索引到继续工作](session-lifecycle.md) · [团队协作流程](team-collaboration.md) · [Agent 检索会话与资源](agent-search.md)。
+
 ## 1. 安装与快速开始
 
 AgentRecall v2 支持 macOS 和 Windows，需要 Node.js 22.13 或更高版本。安装最新的 v2 Release：