StoryCode 用户手册

适用版本：StoryCode 桌面版 v1.0（Windows / macOS） · 文档更新日期：2026-09-23

1. 产品简介

StoryCode 是一款本地优先的 AI 编码代理（AI Coding Agent）桌面应用。它基于 Tauri 2 + React/Vite 构建前端界面，以 Rust 实现代理内核、会话管理与本地服务，并可通过 MCP（Model Context Protocol） 扩展接入丰富的外部工具能力。

1.1 核心能力一览

1.2 架构概览

• 桌面界面：Tauri 桌面应用（React 18 + Vite + TailwindCSS + Radix UI），支持多窗口、系统托盘、原生菜单。
• 代理内核：Rust 实现的 Agent 运行时，负责会话管理、LLM 调用、工具调度与审批。
• 本地 API 服务：内置 HTTP/WebSocket 服务，桌面版启动时自动在 127.0.0.1 上分配一个随机空闲端口，仅供本机界面使用，并以密钥鉴权。
• 沙箱执行：按平台提供沙箱（macOS Seatbelt / Windows 沙箱 / Linux / 外部隔离运行时），保护文件系统与命令执行。
• 扩展系统：基于 MCP 协议的扩展机制，外加技能、子代理、插件包等可组合能力单元。

2. 安装与首次启动

2.1 系统要求

安装包支持中文/英文双语安装界面（Windows NSIS 安装器提供语言选择）。

2.2 首次启动引导

首次启动 StoryCode 时，会依次经过以下引导步骤：

1. 语言选择：选择界面语言（中文 / English）。选择后持久化保存，之后可在「设置 → 外观」中更改。
2. 用户协议：阅读并勾选接受 7 项条款（涵盖 AI 输出风险、用户审阅义务、本地数据访问、第三方服务、敏感数据、免责声明、禁止违法用途）。拒绝协议将退出应用。
3. 模型来源选择：选择使用云端模型（配置供应商 API Key）还是本地模型（下载 GGUF 模型在本机推理）。
   • 选择云端 → 进入供应商配置页，选择供应商并填写 API Key（见第 6 章）。
   • 选择本地 → 进入本地模型引导，应用会根据你的硬件（内存/显存）推荐合适的模型，支持一键下载安装。

2.3 应用更新

StoryCode 内置自动更新机制，会从 storycode.cc 检查新版本。Windows 上采用被动安装模式，更新下载完成后自动安装。你可以在「设置 → 关于」中检查更新、查看当前应用版本与 Agent 运行时版本。

3. 界面总览

3.1 主窗口布局

主窗口由四个区域组成：

窗口标题会随当前页面/会话动态更新；窗口大小与位置会自动记忆。

3.2 侧边栏导航

• 核心项：首页、Agent、工作区、历史会话、Story、知识库、扩展等核心入口。
• 分组：媒体中心（录音/图像/截图/录屏）、开发者工具（终端/SSH/数据库/远程 Agent）为可折叠分组。媒体编辑器不在侧边栏中，从录屏结果或媒体页面进入。
• 置顶收藏：可选页面可「置顶到收藏」，未置顶的收纳在「更多」折叠区，可一键重置菜单。
• 底部固定区：
  • 保险库（Vault）：状态指示灯（未设置/已锁定/已解锁），点击即可解锁或锁定，下拉菜单支持修改密码、重置保险库。
  • 本地模型：服务状态指示灯（运行/休眠/加载/停止/错误），悬停显示模型名、端口、后端与推理速度；操作菜单支持启动/停止/重启与开机自启开关。
  • 设置：进入设置中心。

3.3 标签页

StoryCode 采用多标签工作模式：

• 每个 Agent 会话占据一个标签，可同时并行多个会话。
• 终端、SSH、数据库、Git 等工具页也以标签形式存在。
• 工作区、录屏等页面的标签在切换后保留原有状态（编辑器内容、滚动位置等）。
• 录制中的屏幕录制标签会被拦截关闭，防止误关丢失录制。

3.4 独立窗口

除主窗口外，StoryCode 还有若干专用独立窗口：

3.5 菜单与系统托盘

应用菜单

macOS 上另有标准「应用」菜单（关于、偏好设置 ⌘+,、隐藏、退出等），Windows 上「关于」位于「帮助」菜单。菜单文案随界面语言自动切换中英文。

系统托盘

托盘菜单提供「显示窗口 / 新建窗口 / 退出」三项。Windows 上左键单击托盘图标直接显示主窗口；macOS 使用模板图标自动适配深浅色菜单栏。托盘（菜单栏）图标与 macOS Dock 图标可在「设置 → 系统」中显示/隐藏。

3.6 主题与语言

• 主题：浅色、深色、OLED 纯黑（省电）、跟随系统，共四种模式，在「设置 → 外观」中切换。
• 语言：中文 / English 双语界面，切换后应用菜单随之重建。
• 动效偏好：可减弱界面动效（无障碍友好）。

4. 快速上手

完成首次引导后，通过以下步骤开始你的第一个 Agent 任务：

1. 选择工作区：首页顶部的「工作区切换器」选择或打开一个项目目录（或使用菜单「文件 → 打开目录」，Ctrl/⌘+O）。Agent 的文件操作默认以工作区为根目录。
2. 输入任务：在首页的输入框中用自然语言描述任务，例如「帮我为这个 React 项目添加一个深色模式开关」。
3. （可选）配置工具与能力：在首页点击「工具中心」选择能力预设，批量启用/禁用工具；如有缺失的扩展，可一键启用。
4. 发送并审批：发送消息后，Agent 开始工作。是否需要你确认取决于当前的工具访问模式（见 5.3）：默认的自动模式下常规操作直接执行，仅高风险操作弹出审批条；手动模式下未匹配权限规则的每次工具调用都需要确认。
5. 查看结果：Agent 的每一步工具调用、本轮文件变更、计划更新、Todo 清单都会在对话流中以卡片形式展示。

5. Agent 对话工作台

Agent 对话页（/agent）是 StoryCode 的核心工作台，每个会话一个标签页，支持多会话并行。

5.1 输入栏与消息

底部输入栏集成了丰富的输入能力：

消息流中，Agent 回复支持流式渲染与思考过程展示；用户消息与 AI 消息均可复制、朗读；选中文字可触发快捷操作。回复底部提供「知识溯源」「复制链接」等操作。

5.2 工具调用与审批

• 工具调用卡片：每次工具调用以可展开卡片展示，包含参数、执行结果、日志与详情视图，构成完整的调用时间线。
• 待审批条：需要确认的工具调用会在输入栏上方显示待审批条，并标明触发审批的原因（权限规则、执行策略、受保护路径、安全检测等），可批准或拒绝；部分审批可选择「始终允许」持久化授权。系统通知支持点击跳转到待审批会话。
• 表单请求：当工具或扩展需要补充信息（如密钥、参数）时，会以表单弹窗请求输入。
• 本轮变更卡片：每轮对话产生的文件变更以 diff 卡片展示，可直接预览文件；可在历史会话中回滚/重做某一轮（见第 7 章）。
• MCP UI：支持 MCP UI 扩展在对话中渲染交互式界面（沙箱隔离渲染）。

5.3 工具访问模式

工具访问模式决定 Agent 调用工具时的审批行为，可在输入栏底部的模式菜单中随时切换，也可在「设置 → Agent → 模式」中设置：

子代理还支持 inherit（继承父会话模式）、always_ask（每次都询问）与 never_allow（一律禁止）三种取值，可在子代理定义或派发时按任务指定。

工具级权限规则（白名单/黑名单）在「设置 → Agent → 模式」中，点击「手动」选项右侧的配置按钮进行管理，详见第 18 章。

5.4 语音输入与朗读

• 语音听写：输入栏麦克风按钮开始听写，实时显示波形。支持云端 ASR 与本地 ASR（Whisper / Qwen3），在「设置 → 语音」中切换引擎、选择语言、下载模型。
• 消息朗读（TTS）：AI 回复可朗读，支持 Kokoro / Qwen3 本地 TTS 引擎，底部播放条控制播放。可通过录制参考音频进行声音克隆。

5.5 会话内搜索

在会话页内按 Ctrl/⌘+F 打开会话内查找，Ctrl/⌘+G 查找下一个，Ctrl/⌘+Shift+G 查找上一个，Ctrl/⌘+E 使用选中文本查找。

5.6 子代理派发

在输入栏输入 @，从候选列表中选择子代理（Subagent），即可将任务交给预定义的子代理执行：

• 选择后会打开编辑弹窗，可在派发前编辑指令与参数并确认；派发过程与结果以卡片展示在对话流中。
• 可为每次派发指定最大轮数、超时、工具允许/禁止清单、模型覆盖、后台运行与独立工作区隔离。
• 子代理的创建与管理见 12.4 节。

5.7 工作模式与能力预设

• 工作模式：预设的「模型 + 扩展 + 提示词 + 工具策略」组合，可在首页与会话中切换；在「设置 → Agent → 工作模式」中自定义。
• 能力预设：工具中心提供按能力分组的工具批量启停，一键配置会话可用工具集。
• 工具中心：位于首页，浏览全部可用工具（含扩展提供的工具），查看每个工具的详情与会话运行时工具策略摘要。

6. 模型配置

6.1 云端模型供应商

StoryCode 通过统一接口支持 30+ 云端 LLM 供应商，在「设置 → 模型 → 配置提供商」中添加与配置。每个供应商通常需要 API Key（默认存入系统钥匙串），部分支持自定义 Base URL 与模型列表。

配置完成后，可在「设置 → 模型 → 切换模型」或输入栏底部的模型菜单中按任务切换模型。「设置 → 模型 → 推理设置」用于为支持的模型设置思考模式（默认 / 开启 / 关闭）与推理强度（默认 / 最小 / 低 / 中 / 高 / 超高，可用档位取决于模型）。

6.2 本地模型服务

StoryCode 内置基于 llama.cpp 的本地推理服务（/local-model 页），无需联网即可运行开源大模型：

• 模型管理：浏览/下载/删除 GGUF 模型（含多模态 mmproj 辅助文件），支持断点续传；下载前自动估算模型与显存/内存的适配度。
• 运行时管理：自动检测硬件并选择后端（CUDA / Metal / Vulkan / CPU），支持运行时版本更新与旧版本清理。
• 服务控制：启动/停止本地推理服务器，查看并发槽位（slots）与推理速度；侧边栏底部有常驻状态指示灯与快捷操作。
• 推荐模型一键安装：根据机器硬件画像推荐合适模型，引导式下载安装。
• 外部访问：可将本地服务开放到局域网，提供 OpenAI 兼容端点与访问密钥，供其他设备/应用调用。

本地语言模型的推理后端等选项在「设置 → 模型 → 本地推理」中配置。本地推理还支持图像生成模型与视频生成模型（见 14.2），相关模型卡与运行时在「设置 → 图像与视频」中管理。

6.3 Lead / Worker 双模型

在对话输入栏底部的模型菜单中可开启 Lead / Worker 双模型：会话开始时由能力更强的 Lead 模型处理前若干轮（默认 3 轮），之后切换到更快/更便宜的 Worker 模型（即当前选中的模型）继续工作；如果 Worker 连续失败达到阈值（默认 2 次），会自动回退到 Lead 模型处理若干轮（默认 2 轮）后再交还 Worker。

可配置项包括：Lead 供应商与模型、Lead 轮数、失败阈值、回退轮数。例如可配置「云端 Claude 作 Lead + 本地模型作 Worker」的混合方案，在成本与质量间取得平衡。

7. 历史会话

历史会话页（/sessions）管理所有过往的 Agent 会话：

• 会话列表：浏览、搜索全部历史会话，显示会话标题、时间、工作区等信息。
• 恢复会话：一键恢复到 Agent 页继续对话，会话上下文完整保留。
• 只读回看：查看会话的完整消息记录与当时的运行时策略卡（工具权限、模式等）。
• 回合快照：查看会话每一轮的文件变更快照，可将某一轮的改动回滚，或对已回滚的轮次重做。
• 导出与删除：会话条目支持导出与删除。
• 会话洞察：会话使用统计与洞察。
• 频道会话绑定：管理 IM 频道（如微信、飞书）与会话之间的绑定关系——通过 IM 发起的对话会绑定到指定会话，便于跨端延续上下文（见第 16 章）。

8. Story 记忆库

Story 是 StoryCode 的项目记忆体系——将会话中沉淀的重要信息（决策、检查点、总结、笔记）保存为结构化文档，供后续会话自动召回，让 Agent「记住」项目历史。

8.1 功能界面（/stories）

• 列表页：按作用域筛选（我的 / 自动 / 星标 / 回收站）、按工作区筛选、全文搜索、标签筛选、时间线视图。
• 编辑器页：阅读视图与结构化视图双模式、模板选择器、版本历史与差异对比、关联关系管理（关联文件、Git 提交等）。

8.2 典型用法

• 从对话归档：在 Agent 会话中将消息「另存为 Story」或通过归档对话框批量沉淀会话结果。
• 自动召回：开启输入栏的「Story 记忆开关」后，Agent 在新任务中会自动搜索相关 Story 作为上下文（按主题关键词与文件路径匹配）。
• 星标与版本：重要 Story 可星标置顶；每次编辑产生版本快照，可对比差异与回溯。

9. 知识库

知识库（/knowledge）是你的私有文档检索中心，支持全文检索 + 向量语义检索双引擎，供你手动查阅，也供 Agent 通过知识库工具自动引用。

9.1 知识库管理

• 创建知识库：选择文件/目录进行索引，索引进度以后台任务运行并可回看；支持重建索引（可取消）。
• 内容摄入：支持导入文件、抓取 URL 网页、从剪贴板导入、直接手写 Markdown 条目、将 AI 回答一键归档入库。
• 目录监听：开启后自动监视目录变化并增量更新索引。
• 管理操作：重命名、删除、在系统文件管理器中打开库路径；每个库显示索引状态徽章与监听状态。

9.2 语义搜索

右侧搜索面板支持自然语言语义检索（基于本地嵌入模型），面板显示嵌入模型状态。嵌入模型随应用内置，无需额外配置即可使用；「设置 → 高级/开发 → 向量检索」中可管理嵌入相关选项。

10. 工作区与文件浏览

工作区页（/workspace）是项目文件的中心，切换标签后会保留编辑器状态，回来时无需重新打开文件。

10.1 文件浏览

• 文件树 + 列表/网格双模式：左侧文件树导航，右侧列表或网格视图，支持工具栏与状态栏。
• 搜索：文件名搜索（支持取消）；Ctrl/⌘+P 快速打开。
• 检查器面板：显示选中文件的详细属性；符号链接有特殊标识。

10.2 预览与编辑

10.3 文件操作

支持新建/重命名/复制/移动/删除（移入回收站）、在系统文件管理器中打开、目录选择对话框等。文件树快捷键：方向键导航、Enter 打开、Delete 删除、Ctrl/⌘+A 全选、Ctrl/⌘+C 复制、Esc 取消。

11. Git 版本控制

Git 面板（/git）提供完整的图形化 Git 操作，支持多仓库管理：

Git 快捷键：Ctrl/⌘+Enter 提交、Ctrl/⌘+Shift+S 暂存选中、Ctrl/⌘+Shift+U 取消暂存、Ctrl/⌘+Shift+D 丢弃更改。

12. 自动化体系

StoryCode 提供五层自动化能力：工作流 → 定时任务 → 技能 → 子代理 → 插件包，可组合使用。

12.1 工作流（Workflows）

工作流是可复用的任务模板，用 YAML/JSON 定义，在 /workflows 页管理。

工作流文件格式

version: "1.0"
title: "代码审查"
description: "对当前分支的变更进行全面代码审查"
instructions: "你是一名资深代码审查专家..."   # 系统提示词
prompt: "请审查 {{branch}} 分支的所有变更"      # 初始用户消息，支持 {{参数}} 替换
parameters:                            # 可配置输入参数
  - key: branch
    input_type: string                 # string / number / boolean / date / file / select
    requirement: required              # required / optional / user_prompt
    description: "要审查的分支名"
    default: "main"                    # 可选；file 类型不允许设置默认值
extensions: []                         # 需要启用的 MCP 扩展
settings:                              # 模型/供应商覆盖（均可选）
  agent_provider: "anthropic"
  agent_model: "<模型名>"
  temperature: 0.2
response:                              # 可选：要求以 JSON Schema 约束的结构化结果输出
  json_schema: {}
sub_workflows: []                      # 嵌套子工作流
activities: []                         # 加载时显示的活动标签
retry: {}                              # 重试配置
tags: ["review"]
category: "质量"

界面操作

• 创建/编辑：可视化编辑器——核心字段、指令编辑器、参数 JSON Schema 编辑器、子工作流编辑器、扩展编辑器。
• 从会话创建：把一次成功的 Agent 会话直接转为工作流，固化最佳实践。
• 运行：填写参数后启动新会话执行。
• 版本历史：查看工作流的历史版本。
• 导入：从 YAML/JSON 文件导入工作流。

12.2 定时任务（Schedules）

定时任务让工作流按 cron 计划自动运行（入口已并入 /workflows 页的调度面板）：

• Cron 表达式：6 字段格式（秒 分 时 日 月 星期），例如 0 30 9 * * * 表示每天 09:30 执行；界面提供可视化的时间选择器，并将表达式转为可读文字展示。
• 执行规则：按本机时区触发；秒字段必须是 0–59 的单个值（即最小间隔为 1 分钟）；若上一次执行尚未结束，本次触发会被跳过。
• 任务管理：创建/编辑/暂停/恢复/删除，立即运行，终止运行中的任务。
• 运行历史：查看每次执行的会话记录与详情。
• 通知投递：任务完成后可将结果通知投递到 IM 频道（配合第 16 章的渠道配置），详情页可编辑通知目标并查看投递记录。

12.3 技能（Skills）

技能是 Markdown 格式的可复用指令包（带 YAML frontmatter 元数据），教 Agent 掌握特定技能（如「生成周报」「操作某个内部系统」）。

• 管理界面（/skills）：技能列表 + 详情 + 编辑器（模板区与校验面板）、导入技能、依赖问题提示。
• 创建方式：从零编写、从模板创建、导入现有技能文件。
• 作用域：支持全局与工作区级技能；Agent 在匹配场景下自动加载技能指令。

12.4 子代理（Subagents）

子代理是预定义角色的独立 Agent，拥有自己的指令、工具集与运行时配置，可被主会话派发任务。

• 管理界面（/subagents）：左侧列表（全局/工作区作用域徽章、搜索）+ 右侧详情（用法片段、运行时配置、指令、扩展/技能/标签、允许与禁止工具清单、YAML 预览）。
• 创建方式：新建、克隆、三步模板向导、YAML 导入。
• 历史快照：每次修改产生快照，支持回滚。
• 导出/导入：以 YAML 格式分享子代理定义。

12.5 插件（Plugins）

插件是能力组合包——把技能、工作流、斜杠命令、子代理、工作模式、策略、知识库打包在一起，一键安装。插件管理页为 /plugins（侧边栏「插件」）。

• 安装：从本地目录安装，安装前可校验与预览（dry-run）。
• 诊断与修复：诊断插件问题、预览修复计划、应用修复（含知识库重建）。
• 状态管理：就绪状态徽章、依赖扩展指引、缺失密钥配置面板、Setup 工作流引导。
• 启用范围：按工作区启用/禁用插件。
• 更新与卸载：更新计划预览、卸载预览与确认。

13. 扩展（MCP）管理

扩展基于 MCP（Model Context Protocol），为 Agent 接入外部工具与数据源。扩展管理页（/extensions）提供：

• 扩展列表：查看所有已安装扩展及启用状态；支持会话级运行时启用/禁用（不影响全局配置）。
• 添加扩展：支持多种类型——本地命令（stdio）、远程服务（SSE / Streamable HTTP）、内置扩展（builtin，如 Developer、Memory、Computer Use、Knowledge 等）。
• 扩展配置：编辑环境变量、请求头、超时、描述等字段。
• 分组加载：批量启用时显示分组加载进度提示。

工作流与插件也可以声明依赖的扩展，运行时自动按需启用。

14. 媒体中心

媒体中心（/media）集成了五大媒体工具，生成的文件统一保存在工作区 .storycode/media/ 目录下。

14.1 录音与转写（/media/audio）

• 录音：麦克风或系统音频录制，支持暂停/恢复、输入设备选择、实时电平表与波形显示。
• 转写：对录音或已有音频文件进行语音转文字，支持本地 ASR（Whisper / Qwen3）与云端识别；转写结果以卡片展示。
• 播放：内置预览播放器，支持音频规格与波形数据查看。

14.2 图像与视频生成（/media/image）

• 生成器：输入提示词，设置尺寸、种子、数量，提交生成任务。
• 模型档案：支持本地图像/视频模型与云端媒体供应商，均在「设置 → 图像与视频」中配置。
• 任务追踪：任务状态卡 + 系统通知；结果画廊支持图片预览、视频播放；历史面板可回看过往任务。
• 视频生成：需要提供首帧图片（可先生成一张图作为首帧）。
• 支持拖拽/粘贴图片作为输入。

14.3 截图与拍照（/media/screenshots）

• 全屏截图、指定窗口截图（窗口选择对话框）、区域截图（独立框选窗口）。
• 摄像头拍照保存。
• 截图可直接复制到剪贴板；截图文件列表与预览。
• 应用内区域截图：在 StoryCode 窗口中按 Ctrl/⌘+Shift+X 直接框选截图（焦点在输入框内时不生效），完成后跳转到截图页查看。
• 系统级全局快捷键：「屏幕截图」与「窗口截图」两个快捷键由操作系统注册，应用不在前台也可唤起，默认未设置，可在「设置 → 系统 → 截图设置」中自定义；同一处还可设置图片格式、画质、延时、预览与剪贴板行为。

14.4 屏幕录制（/media/screen-recording）

• 录制源：整个显示器、指定窗口、或框选区域；支持摄像头画中画。
• 控制：开始/暂停/恢复/停止；录制中关闭标签会被拦截提醒。
• 高级设置：音频源选择（麦克风/系统音频/无声）、音画偏移校准、画质设置。
• 录制完成后可直接进入媒体编辑器剪辑；录制文件列表管理。

14.5 媒体编辑器（/media/editor）

时间线视频编辑器，用于录屏与视频素材的后期处理：

• 时间线剪辑：裁剪、缩放建议、光标跟随与热点缩放区域。
• 检查器：调整选中片段属性；裁剪覆盖层可视化框选。
• 工程管理：自动保存与崩溃恢复（恢复草稿）。
• 导出：基于 FFmpeg 的导出任务（转码/压缩）。

15. 开发者工具

15.1 内嵌终端（/devtools/terminal）

• 基于 xterm 的完整 PTY 终端，支持多面板分屏（拖拽到分屏区域）。
• 自动检测可用 Shell（PowerShell、CMD、bash 等）。
• 终端录制与回放：录制终端会话（cast 格式），可回放与导出。
• 快捷键：Ctrl+F 终端内搜索、Ctrl+L 清屏、Ctrl+Shift+C/V 复制粘贴。

15.2 SSH 与 SFTP（/devtools/ssh）

• 连接档案：SSH 配置档案管理（基础/高级表单），支持从 ~/.ssh/config 导入（预览后应用）；主机密钥（known_hosts）确认与管理。
• 密钥管理：生成/查看/删除 SSH 密钥；SSH Agent 集成（密钥列表、添加/移除）；密码与密钥通过保险库（Vault）加密存储，主密码解锁后使用。
• SSH 终端：交互式远程终端，支持自动重连。
• SFTP 文件传输：远程目录浏览、上传/下载（文件/目录/批量）、目录同步；传输任务支持取消/暂停/恢复。
• 端口隧道：端口转发规则的增删改查、启动/停止、开机自动启动。

15.3 数据库工具（/devtools/database）

统一管理 SQLite / PostgreSQL / MySQL 三类数据库：

• 连接管理：连接配置创建与测试；SQLite 支持新建数据库文件；支持通过 SSH 隧道连接远程库（预览测试）；密码会话级暂存。
• 数据浏览：表列表侧边栏、表结构查看、数据行浏览、单元格内容查看对话框。
• 数据操作：行插入/更新/删除、建表、增/改/删列。
• SQL 控制台：自定义 SQL 查询与执行，自动分类读/写/DDL；可取消正在运行的 SQL。
• AI 辅助：AI 辅助生成 SQL（自动携带 schema 摘要上下文）与 AI 解释 SQL 弹窗。
• 导入导出：表导出（CSV/JSON/SQL）、整库 dump、dump 导入恢复。

15.4 远程 Agent（/devtools/remote-agents）

将 StoryCode Agent 部署到远程服务器，通过 SSH 运维，在本地界面使用远程算力：

远程操作均有审计日志记录（可查询），远程 API 访问策略可精细控制。

16. IM 频道集成

StoryCode 支持将 Agent 接入主流即时通讯软件，让你在聊天窗口中远程使用 Agent——发消息即发起/延续会话，任务结果回推到 IM。在「设置 → 远程通道」中配置：

• 会话绑定：IM 对话与 Agent 会话的绑定关系在「历史会话」页管理（见第 7 章）。
• 定时任务通知：频道同时作为定时任务结果的通知投递目标（见 12.2）。

17. 设置中心详解

设置中心（/settings，支持 ?section=&subsection= 深链定位，顶部提供设置搜索）按侧边分区组织，顺序如下：

其他设置入口

• CLI 工具：「设置 → 系统」中一键安装/卸载 storycode-cli 命令行工具并加入 PATH，便于在系统终端中使用 StoryCode Agent。
• LSP 语言服务器：位于「设置 → 高级/开发 → 开发工具」，为代码编辑器提供悬停信息与自动补全；可检测、安装、卸载各语言服务器，支持自定义服务器路径。
• 单实例：重复启动应用时会聚焦已有窗口并处理命令行参数。

18. 安全、沙箱与权限

18.0 工具审查流水线（为什么「自动」模式下仍会弹审批）

除「仅聊天」模式外，Agent 的每一次工具调用都会依次经过六层审查，任一层给出「拒绝」即拒绝，任一层给出「需确认」即弹出审批：

18.1 沙箱执行

Agent 执行的 shell 命令与文件写入可运行在沙箱中（macOS Seatbelt、Windows 增强沙箱、Linux 沙箱或外部隔离运行时），限制其文件系统与网络访问范围，保护工作区外的数据。Windows 增强沙箱启用时会引导完成工作区保护设置；沙箱开关与策略在「设置 → 安全 → Shell 沙箱」中管理。

18.2 命令执行策略（execpolicy）

execpolicy 是 shell 命令的规则引擎，每条规则给出 allow（允许）/ prompt（需确认）/ forbidden（拒绝）三种决策之一。「设置 → 安全 → Exec policy 规则」提供规则编辑器，内置默认规则与内容校验。

• 规则文件：全局 ~/.storycode/config/execpolicy/*.rules（首次启动自动生成 default.rules）；工作区 <工作区>/.storycode/execpolicy/*.rules。
• 规则语法：prefix_rule(pattern = ["git", ["pull", "fetch"]], decision = "allow")，列表中的子列表表示「任选其一」；省略 decision 时按 prompt 处理。注意关键字是 forbidden，写成 deny 会报解析错误。
• 优先级：命令在工作区内时优先使用工作区规则；在工作区外时全局与工作区规则同时生效，多条命中取最严（forbidden > prompt > allow）。
• 在「自动」模式下，prompt 规则会升级为拒绝，保证无人值守任务的安全。

18.3 工具权限规则

在「设置 → Agent → 模式」中点击「手动」右侧的配置按钮，可管理工具级白名单/黑名单：手动模式下先匹配用户规则，未匹配的调用才需要人工确认。审批时选择「始终允许」也会写入相应规则。

18.4 受保护路径

• 读取工作区 .git 元数据直接放行；写/删/执行 .git（包括 git reset --hard、git clean、git config 写操作等）以及读写全局 ~/.storycode 始终需要确认，且不能设为「始终允许」。
• 工作区 .storycode 下的缓存、临时、媒体等运行时目录允许 Agent 读写；安全策略文件本身（execpolicy 规则、权限规则等）不可被授权修改，防止 Agent 自我提权。
• 可授权的项选择「始终允许」后记录在 <工作区>/.storycode/permissions/protected-paths.yaml。

18.5 审批审计日志

每次审批的发起与最终结果都会逐行追加记录到 ~/.storycode/state/audit/tool-approvals.jsonl，便于事后追溯 Agent 做过哪些需要确认的操作。日志已脱敏：只记录工具名、审批理由分类与你的决定，不记录工具参数和理由原文。

18.6 密钥与凭据安全

• 系统钥匙串：模型供应商 API Key 等敏感配置默认存入系统钥匙串（Keychain / Credential Manager）；可在「设置 → 系统 → 使用系统 Keyring」中关闭，关闭后改为存入本地 ~/.storycode/config/secrets.yaml（可减少系统弹窗，但安全性较低）。
• 保险库（Vault）：SSH 密码、远程 Agent 令牌等以主密码加密存储；侧边栏底部显示锁定状态，支持修改/重置主密码与自动锁定。
• 数据库密码：会话级暂存，可随时「遗忘」。

18.7 界面安全

• WebView 配置了严格的 CSP（内容安全策略）与导航白名单，拦截非授权页面跳转。
• MCP UI 内容在沙箱 iframe 中渲染，通过桥接与宿主安全交互。
• 远程 Agent 具备操作审计日志与 API 访问策略。

19. 键盘快捷键大全

按 Ctrl/⌘+/ 或直接按 ? 可随时打开应用内的快捷键帮助对话框（会按当前页面上下文推荐相关快捷键；? 在输入框内不生效）。

19.1 全局

19.2 会话内搜索

19.3 Agent 输入框

19.4 终端

19.5 Git 面板

19.6 工作区文件树与其他

20. 附录

20.1 本地语音 ASR / TTS 配置

本地语音识别与合成也可通过配置项手动指定（高级用法：可写入 ~/.storycode/config/config.yaml 或以同名环境变量提供；一般用户在「设置 → 语音」中图形化配置即可）：

20.2 数据存储位置

20.3 常见问题

Q1：启动后一直要求配置模型供应商？

这是正常现象——模型配置是进入主界面的前置条件。按向导选择云端供应商（填 API Key）或本地模型（下载推荐模型）即可；之后可随时在「设置 → 模型」中修改。

Q2：本地模型下载慢或失败？

下载支持断点续传，可在下载管理器中恢复；也可在「设置 → 高级/开发 → 网络代理」配置代理。磁盘空间不足时，请先清理旧模型或运行时版本（模型页提供清理入口）。

Q3：Agent 执行命令被拦截或反复要求确认？

先看待审批条上显示的原因，再对应处理：

• 权限规则：手动模式下未匹配规则的调用需要确认，可在「设置 → Agent → 模式 → 手动」的配置按钮中添加规则，或审批时选「始终允许」。
• 执行策略：命中 prompt 规则会要求确认；自动模式下 prompt 规则会直接拒绝。可在「设置 → 安全 → Exec policy 规则」中调整。
• 受保护路径 / 安全检测：写 .git、访问全局 ~/.storycode 等操作在任何模式下都需要确认（见 18.0、18.4），这是预期行为。

Q4：macOS 上录屏/麦克风没有画面或声音？

需要在「系统设置 → 隐私与安全性 → 屏幕录制/麦克风」中授权 StoryCode；应用内的媒体权限面板可检查状态并跳转设置。

Q5：视频导出失败提示 FFmpeg？

媒体处理依赖 FFmpeg。按媒体中心内的安装引导安装，或在设置中指定自定义 FFmpeg 路径后刷新状态。

Q6：如何让 Agent 记住项目背景？

三种方式：① 会话中将结论「另存为 Story」，后续会话自动召回；② 把项目文档加入知识库，Agent 可语义检索引用；③ 在「设置 → Agent → Agent 提示」中固化项目级指令。

Q7：如何反馈问题？

菜单「帮助 → 报告问题」会打开 storycode.cc/issues；内置「帮助中心」（/help 页）提供可全文搜索的使用文档。