Merge pull request #24 from desirecore/codex/docs-capability-tools

docs: update tool capability docs

Author: yi-ge

docs/02-user-guide/09-capabilities/01-tool-system.md

@@ -33,10 +33,24 @@ DesireCore 的工具系统分为三层，由内到外，能力逐步扩展：
 
 ### 第一层：内置工具
 
-DesireCore 自带的基础能力，开箱即用，无需额外配置。包括文件读写、目录浏览、内容搜索、命令执行、网页获取、用户提问、智能体协作、工作流和调度等核心功能。
+DesireCore 自带的基础能力，开箱即用，无需额外配置。包括文件读写、目录浏览、内容搜索、命令执行、网页获取、PDF 读取、用户提问、智能体协作、工作流、调度、文档导出、媒体生成和任务管理等核心功能。
 
 工具是否进入智能体上下文取决于当前平台、权限和运行环境。例如 PowerShell 只在 Windows 环境注册；当某个工具不可用时，对应能力声明也不会注入给智能体。
 
+### Skill-scoped 工具
+
+有些工具只在对应技能启用后才会暴露给智能体。这类工具称为 Skill-scoped tools。
+
+例如 Web Access v2 启用后，智能体才会看到浏览器控制、CDP 代理、站点经验和本地书签相关工具。这样可以避免普通任务误用重型或高权限工具，也能让能力说明和实际可用工具保持一致。
+
+常见模式：
+
+| 技能 | 激活后可用的能力 |
+|------|------------------|
+| Web Access | Browser 工具族、CDP、SitePattern、LocalBookmarks |
+| Media Generation | GenerateImage、GenerateVideo、BeautifyImage |
+| Office / Documents | 文档渲染、表格/演示文稿处理、PDF 导出 |
+
 ### 第二层：MCP 工具
 
 通过 MCP（Model Context Protocol）协议连接外部服务。MCP 是一个开放标准，让智能体可以安全地访问 GitHub、文件系统、数据库、Slack 等第三方服务。

docs/02-user-guide/09-capabilities/02-builtin-tools.md

@@ -6,7 +6,7 @@ keywords: [内置工具, 工具列表, 文件操作, 搜索, 命令执行, 网
 
 # 内置工具一览
 
-内置工具是 DesireCore 自带的基础能力，随客户端一起安装。智能体会根据当前操作系统、已启用的权限、可用工具和任务上下文自动选择工具；不可用的工具不会进入智能体的能力声明。
+内置工具是 DesireCore 自带的基础能力，随客户端一起安装，无需额外配置即可使用。工具会随客户端版本更新，因此本文按能力域说明常用工具，而不是固定成某个数量。智能体会根据当前操作系统、已启用的权限、可用工具和任务上下文自动选择工具；不可用的工具不会进入智能体的能力声明。
 
 ## 文件操作类
 
@@ -18,7 +18,9 @@ keywords: [内置工具, 工具列表, 文件操作, 搜索, 命令执行, 网
 |------|-----|
 | 风险等级 | 低 |
 | 需要确认 | 否 |
-| 典型场景 | 查看代码、阅读文档、检查配置、预览图片 |
+| 典型场景 | 查看代码、阅读文档、检查配置、预览图片、读取长 PDF 或扫描 PDF |
+
+读取指定路径的文件内容。支持文本文件的行号显示和分页读取，能自动检测图片文件并以视觉方式呈现。PDF 会根据文件大小和内容类型选择读取策略：小文件直接读取，大文件分段读取；扫描页或图表页可按页渲染为图片交给视觉模型。
 
 ### Write — 写入文件
 
@@ -174,6 +176,17 @@ keywords: [内置工具, 工具列表, 文件操作, 搜索, 命令执行, 网
 | 需要确认 | 取决于请求内容 |
 | 典型场景 | 调用 API、检查服务状态、获取结构化数据 |
 
+### Web Access 工具族 — 浏览器访问
+
+| 属性 | 值 |
+|------|-----|
+| 风险等级 | 低 - 中 |
+| 需要确认 | 视操作而定 |
+
+Web Access 技能启用后，智能体可以使用浏览器标签页访问动态网页、登录态页面和需要 JavaScript 的站点。工具族包含导航、点击、滚动、截图、执行受控脚本、文件上传和关闭标签页等能力。
+
+**典型场景**：阅读需要登录的网页、操作动态表单、采集 SPA 页面、复用站点经验。详见 [Web Access](./web-access)。
+
 ## 智能体协作类
 
 ### Delegate — 委派任务
@@ -256,7 +269,27 @@ keywords: [内置工具, 工具列表, 文件操作, 搜索, 命令执行, 网
 | 需要确认 | 取决于操作内容 |
 | 典型场景 | 组建专业团队、调整团队成员、分配团队任务 |
 
-## 工作空间与数据类
+## 任务与上下文类
+
+### CompactSession — 压缩会话
+
+| 属性 | 值 |
+|------|-----|
+| 风险等级 | 低 |
+| 需要确认 | 否 |
+
+整理当前长对话，把较早消息压缩成摘要，帮助模型继续处理长任务。详见 [上下文控制](../conversations/context-control)。
+
+### TaskCreate / TaskList / TaskGet / TaskUpdate — 任务板
+
+| 属性 | 值 |
+|------|-----|
+| 风险等级 | 低 |
+| 需要确认 | 否 |
+
+让智能体维护一次对话内的任务板，记录子任务、状态、优先级、依赖和进度。详见 [执行监控](../04-delegation/03-execution-monitoring.md)。
+
+## 工作空间管理类
 
 ### ManageWorkDirs — 管理工作目录
 
@@ -393,3 +426,51 @@ keywords: [内置工具, 工具列表, 文件操作, 搜索, 命令执行, 网
 | 风险等级 | 低 |
 | 需要确认 | 否 |
 | 典型场景 | 查看流程结构、审查节点配置 |
+
+### HeartbeatRespond — 心跳响应
+
+| 属性 | 值 |
+|------|-----|
+| 风险等级 | 低 |
+| 需要确认 | 否 |
+| 典型场景 | 提交心跳巡检结果、通知文本、产出文件和下次检查建议 |
+
+让智能体在心跳巡检后提交 outcome、通知文本、产出文件和下次检查建议。详见 [心跳监控](../08-automation/01-heartbeat.md)。
+
+## 文档与媒体类
+
+### ExportDocument — 导出文档
+
+| 属性 | 值 |
+|------|-----|
+| 风险等级 | 低 - 中 |
+| 需要确认 | 视目标路径而定 |
+
+把 Markdown 或编辑器内容导出为 PDF、DOCX 等格式，使用统一渲染链路保留标题、表格、代码块、图片和公式。
+
+### GenerateImage / GenerateVideo — 生成图像和视频
+
+| 属性 | 值 |
+|------|-----|
+| 风险等级 | 中 |
+| 需要确认 | 视供应商和费用而定 |
+
+调用已配置的图像或视频生成 provider，支持文生图、图生图、文生视频、参考素材和首尾帧等能力。详见 [媒体生成](./media-generation)。
+
+### BeautifyImage — 美化图片
+
+| 属性 | 值 |
+|------|-----|
+| 风险等级 | 中 |
+| 需要确认 | 视供应商和费用而定 |
+
+对图片进行美化、居中、去边框或质量优化，并对输出体积做保护。
+
+### MathCalc — 高精度计算
+
+| 属性 | 值 |
+|------|-----|
+| 风险等级 | 低 |
+| 需要确认 | 否 |
+
+执行确定性的高精度数学计算，适合金额、比例、统计和公式校验。

docs/02-user-guide/09-capabilities/06-integrations-overview.md

@@ -14,6 +14,8 @@ DesireCore 不是一个封闭系统。它通过多层集成架构连接外部世
 
 这篇文档帮助你快速了解 DesireCore 所有集成能力的全貌，然后指引你到具体文档深入阅读。
 
+较新的 DesireCore 还提供 [应用与服务目录](./app-service-catalog)，用于管理应用安装、服务注册、健康探测、启停更新和审批请求。
+
 ## 集成能力全景
 
 | 集成类型 | 说明 | 详细文档 |
@@ -24,6 +26,7 @@ DesireCore 不是一个封闭系统。它通过多层集成架构连接外部世
 | **Computer Use** | 通过 HostAgent 操控桌面和移动设备的 GUI | [GUI 桌面自动化](./computer-use) |
 | **邮件** | 统一管理 Gmail / Outlook / IMAP 邮箱 | [邮件管理](../email/overview) |
 | **工作流** | 用可视化 DSL 编排触发器、代码、LLM、Agent 和人工确认节点 | [任务编排](../../concepts/task-orchestration) |
+| **应用与服务目录** | 管理应用安装、派生服务、审批和健康状态 | [应用与服务目录](./app-service-catalog) |
 
 :::tip 一句话理解
 内置工具是"出厂能力"，MCP 是"扩展接口"，技能包是"工作流模板"，Computer Use 是"万能后备"——四者互补，覆盖几乎所有场景。

docs/02-user-guide/09-capabilities/07-web-access.md

@@ -0,0 +1,60 @@
+---
+title: Web Access
+description: 使用 Web Access v2 访问动态网页、登录态页面、本地书签和站点经验。
+keywords: [Web Access, Browser, CDP, SitePattern, LocalBookmarks, 网页访问]
+---
+
+# Web Access
+
+Web Access v2 让智能体在需要时使用受控浏览器访问网页。它适合普通网页抓取无法覆盖的场景：动态页面、需要登录的后台、复杂表单、单页应用、内网系统和需要截图验证的页面。
+
+## 启用方式
+
+Web Access 是 Skill-scoped 能力。只有相关技能启用后，浏览器控制、CDP 代理、站点经验和本地书签工具才会暴露给智能体。
+
+这种设计可以避免普通任务误用浏览器工具，也能让你清楚知道智能体什么时候可能操作网页。
+
+## 能做什么
+
+| 能力 | 说明 |
+|------|------|
+| 标签页控制 | 打开、列出、切换和关闭浏览器标签页 |
+| 页面操作 | 点击、滚动、输入、选择元素 |
+| 截图观察 | 截取页面或元素状态，辅助视觉判断 |
+| CDP 代理 | 通过 Chrome DevTools Protocol 读取更细的页面状态 |
+| 文件上传 | 在需要时选择本地文件上传，通常需要确认 |
+| 本地书签 | 查询 Chrome / Edge 等浏览器的书签和历史线索 |
+| 站点经验 | 记录某个站点的登录入口、选择器、操作路径和注意事项 |
+
+## SitePattern
+
+SitePattern 是站点经验记录。它帮助智能体记住某个网站如何使用，例如：
+
+- 登录入口和常见跳转
+- 搜索框、筛选器、导出按钮的位置
+- 常见错误和弹窗处理方式
+- 哪些页面需要等待动态加载
+
+写入站点经验前会进行校验，避免把无效或过度宽泛的规则保存下来。
+
+## LocalBookmarks
+
+LocalBookmarks 可以从本机浏览器书签和历史中寻找 URL 线索。它不会自动登录网站，也不会绕过权限；只是帮助智能体找到你常用系统的入口。
+
+## 安全边界
+
+- 默认只允许 `http` 和 `https` URL
+- 上传文件、提交表单、删除或发布内容等有外部影响的操作会触发审批
+- 浏览器会尽量隔离会话标签页，避免不同任务互相污染
+- 截图和页面内容会进入当前任务上下文，请避免在敏感页面开启无关任务
+
+## 与 WebFetch / WebSearch 的关系
+
+优先级通常是：
+
+1. `WebSearch` 查找公开信息
+2. `WebFetch` 读取静态网页正文
+3. Web Access 处理动态、登录态或需要操作的页面
+
+如果普通抓取足够完成任务，智能体不需要打开浏览器。
+

docs/02-user-guide/09-capabilities/08-media-generation.md

@@ -0,0 +1,59 @@
+---
+title: 媒体生成
+description: 使用 GenerateImage、GenerateVideo 和 BeautifyImage 生成、编辑和优化图片视频。
+keywords: [图像生成, 视频生成, GenerateImage, GenerateVideo, BeautifyImage, 文生图, 文生视频]
+---
+
+# 媒体生成
+
+DesireCore 可以通过已配置的媒体 provider 生成图片、视频，并对已有图片做美化或修复。媒体生成通常由技能或智能体在合适的任务中调用。
+
+## 前置条件
+
+你需要在「设置 > 算力服务」中启用支持对应服务类型的 provider：
+
+| 服务类型 | 用途 |
+|----------|------|
+| `image_gen` | 文生图、图生图、多图融合 |
+| `video_gen` | 文生视频、图生视频、首尾帧视频 |
+| `image_understanding` / `ocr` | 生成后复核、图片理解 |
+
+官方云端算力、第三方 API Key 和自定义 OpenAI-compatible provider 都可以作为来源，具体取决于供应商能力。
+
+## GenerateImage
+
+`GenerateImage` 用于生成或编辑图片。常见能力包括：
+
+- 根据文本提示词生成图片
+- 使用一张或多张参考图生成新图
+- 调整风格、构图、尺寸和细节
+- 自动保存输出并在聊天中展示
+
+## GenerateVideo
+
+`GenerateVideo` 用于生成视频。常见能力包括：
+
+- 文生视频
+- 以图片作为首帧或参考素材生成视频
+- 使用首尾帧约束镜头变化
+- 输出后作为媒体文件附加到对话
+
+## BeautifyImage
+
+`BeautifyImage` 用于优化已有图片，例如：
+
+- 图片居中和裁切
+- 去除多余边框
+- 质量增强或尺寸调整
+- 输出体积保护，避免生成异常大文件
+
+## 审批与费用
+
+媒体生成可能消耗 API 额度或账号 credit。涉及付费 provider、上传参考素材或写入本地文件时，系统会按风险和权限策略请求确认。
+
+## 使用建议
+
+- 需要“看懂图片”时使用视觉模型，而不是图像生成模型
+- 需要聊天回复时选择 chat 模型，图像/视频生成模型不会出现在普通对话模型选择器中
+- 对正式素材，生成后让智能体用视觉理解工具复核一次，检查文字、构图和明显错误
+

docs/02-user-guide/09-capabilities/09-app-service-catalog.md

@@ -0,0 +1,56 @@
+---
+title: 应用与服务目录
+description: 了解应用安装、服务注册、运行状态、审批和更新管理。
+keywords: [应用目录, 服务目录, Apps, Services, 安装, 审批, MCP]
+---
+
+# 应用与服务目录
+
+应用与服务目录把第三方应用、MCP 服务和由应用派生的本地服务集中管理。它不只是一个列表，而是从安装、注册、审批到启停更新的闭环。
+
+## 目录里有什么
+
+| 条目 | 说明 |
+|------|------|
+| 应用 | 可安装的第三方能力包或集成入口 |
+| 服务 | 应用安装后注册出的 MCP、HTTP 或本地服务 |
+| 待审批项 | 服务注册、调用、提权或测试连接时需要你确认的请求 |
+| 安装记录 | 已安装、失败、运行中、已停止、可更新等状态 |
+
+## 安装流程
+
+1. 在 Marketplace 或应用目录中选择应用
+2. DesireCore 委派核心智能体执行安装
+3. 安装记录写回本地
+4. 应用派生的服务被 watcher 发现并注册
+5. 需要权限的服务进入待审批面板
+
+安装完成后，你可以从目录中打开、启动、停止、重启或更新应用/服务。
+
+## 服务审批
+
+服务可能请求以下操作：
+
+- 注册新服务
+- 调用外部 API
+- 访问本地文件或端口
+- 提升权限
+- 执行健康探测
+
+这些请求会进入审批流程。你可以批准、拒绝或查看详情。未经审批的 stdio 服务不会被后台静默执行。
+
+## 状态与排障
+
+常见状态包括：
+
+| 状态 | 含义 |
+|------|------|
+| Installed | 已安装但不一定运行中 |
+| Running | 服务正在运行 |
+| Stopped | 已停止 |
+| Failed | 安装或启动失败 |
+| Update available | 有可用更新 |
+| Pending approval | 等待你审批 |
+
+如果服务不可用，可以先查看详情页中的健康检查结果、日志摘要和审批状态。
+