chore: 更新开发文档与重构追踪

- REFACTOR.md: 更新 check list 状态（multi-hop qa 已完成）
- agents-config/sandbox-architecture/skills-management: 适配命名变更
- roadmap: 更新进度记录

REFACTOR.md

@@ -24,9 +24,11 @@
 - [ ] 权限新增一个 guest 的预设字段，暂无任何权限
 - [ ] rename database table name, such as skills -> agent_skills, subagents -> agent_subagents, mcp, tool_call, 等等
 - [x] department 的 id 也不能使用那个索引的 id 来使用了，应该是一个独立的 dept_id，需要确认
-- [ ] allow user config skill
+- [ ] allow user config skill, and envs
+- [ ] add model retry times to agent context config
+- [ ] add user envs when load sandbox
 - [ ] Config spacy model 的 load
-- [ ] allow multi-hop qa generate
+- [x] allow multi-hop qa generate
 - [x] 在工作区的文件编辑的时候，保存和取消的按钮应该是悬浮在编辑框的右上角，而不是在 header 上面
 - [x] default enable all build in tools / kbs / skills / mcps / subagents
 - [x] 链接 Notion 和 feishu 目前来看，都是支持的

docs/agents/agents-config.md

@@ -221,9 +221,15 @@ config_json.context + runtime ids -> context_schema instance
 
 因此 Graph 不是和 Context 解耦的。相反，Graph 的构造本身就依赖 Context。
 
-### 4.4 中间件运行阶段
+### 4.4 Graph 构建与中间件运行阶段
 
-中间件通过 `request.runtime.context` 或 `runtime.context` 继续读取和修改 Context。
+`get_graph()` 创建 LangGraph 前会先调用 `prepare_agent_runtime_context`，用当前用户重新过滤资源字段，并派生运行时字段：
+
+- `_visible_knowledge_bases`：当前会话实际可查询的知识库对象
+- `_prompt_skills`：需要注入提示词的 Skill 闭包
+- `_readable_skills`：`/home/gem/skills` 和沙盒可读的 Skill 闭包
+
+中间件通过 `request.runtime.context` 或 `runtime.context` 继续读取这些结果。
 
 例如：
 
@@ -231,15 +237,14 @@ config_json.context + runtime ids -> context_schema instance
   - 读取 `model`、`system_prompt`、`tools`、`mcps`
   - 动态覆盖模型、系统提示词和工具列表
 - `SkillsMiddleware`
-  - 读取 `skills`
-  - 计算可见技能闭包
-  - 将 skills 提示段注入 `system_prompt`
-  - 在运行期回写 `_visible_skills`
+  - 读取 `_prompt_skills` 注入 skills 提示段
+  - 读取 `_readable_skills` 校验可激活 Skill
+  - 根据 `activated_skills` 按需挂载工具和 MCP 依赖
 - 文件系统与沙盒接入
   - 通过 `thread_id` 获取对应沙盒
-  - 通过 `skills` 决定 `/home/gem/skills` 的可见范围
+  - 通过 `_readable_skills` 决定 `/home/gem/skills` 的可读范围
 
-所以 Context 既是输入配置，也是中间件共享的运行时状态载体。
+所以 Context 既是输入配置，也是 Graph 创建前整理出的运行时资源上下文。
 
 ### 4.5 文件系统与 Viewer 阶段
 

docs/agents/sandbox-architecture.md

@@ -147,13 +147,13 @@ Yuxi 不会把整个容器文件系统都开放给 Agent 或 viewer。当前 vie
 
 `/home/gem/user-data` 是主要工作区。它允许模型和工具写入，但推荐语义并不相同。内置 prompt 中已经明确说明，`workspace` 应当放中间文件，`outputs` 应当放最终产物，`uploads` 是用户上传文件的位置。对于普通对话 Agent，文案甚至提示“非必要不要写 workspace，而优先写 outputs”。
 
-`/home/gem/skills` 是只读目录。它不是简单地把 `saves/skills` 整个暴露进去，而是先根据当前线程可见的 skill 列表，把这些技能从全局 skills 根目录同步复制到 `saves/threads/<thread_id>/skills`，再把这个线程目录只读挂进沙盒。这样做的结果是，不同线程看到的 skill 集可能不同，而且模型永远不能在运行时修改 skills 内容。
+`/home/gem/skills` 是只读目录。它不是简单地把 `saves/skills` 整个暴露进去，而是先根据当前线程的 `_readable_skills`，把这些技能从全局 skills 根目录同步复制到 `saves/threads/<thread_id>/skills`，再把这个线程目录只读挂进沙盒。这样做的结果是，不同线程看到的 skill 集可能不同，而且模型永远不能在运行时修改 skills 内容。
 
 知识库访问不属于沙盒文件系统暴露规则。当前 Agent 可见知识库仍由用户权限和 Agent 配置共同决定，但只通过 `query_kb`、`open_kb_document` 等工具访问，不提供沙盒目录投影。
 
 ## 十、skills、知识库、附件是怎么和沙盒结合的
 
-skills 的结合方式分成两层。第一层是提示词层，`SkillsMiddleware` 会把当前线程配置的 skill 列表和依赖闭包注入到系统提示里，让模型知道哪些 skill 存在、它们的入口文件一般在 `/home/gem/skills/<slug>/SKILL.md`。第二层是文件系统层，运行时会调用 `sync_thread_visible_skills`，把当前线程真正可见的 skill 目录复制到线程自己的 `saves/threads/<thread_id>/skills` 下，再由沙盒只读挂载到 `/home/gem/skills`。也就是说，skill 既是 prompt 中的能力说明，也是文件系统中的只读知识目录。
+skills 的结合方式分成两层。第一层是提示词层，`prepare_agent_runtime_context` 会先根据当前线程配置的 `context.skills` 展开依赖闭包，`SkillsMiddleware` 再把 `_prompt_skills` 注入到系统提示里，让模型知道哪些 skill 存在、它们的入口文件一般在 `/home/gem/skills/<slug>/SKILL.md`。第二层是文件系统层，运行时会调用 `sync_thread_readable_skills`，把 `_readable_skills` 对应的 skill 目录复制到线程自己的 `saves/threads/<thread_id>/skills` 下，再由沙盒只读挂载到 `/home/gem/skills`。也就是说，skill 既是 prompt 中的能力说明，也是文件系统中的只读知识目录。
 
 附件的结合方式更偏向“先落盘，再把路径告诉模型”。用户上传文件后，系统会先把原始文件写入 `saves/threads/<thread_id>/user-data/uploads`。如果该文件可以被解析，系统还会额外生成一个 Markdown 副本，写到 `saves/threads/<thread_id>/user-data/uploads/attachments/<name>.md`。随后，LangGraph state 中会维护一份 `uploads` 列表，`AttachmentMiddleware` 会把这些可读路径注入系统提示，告诉模型优先用 `read_file` 去读取这些路径。因此，附件并不是“作为消息大段内联塞给模型”，而是被转换成沙盒文件系统中的路径对象。
 

docs/agents/skills-management.md

@@ -160,11 +160,11 @@ Skills 之间可以建立依赖关系，形成一个松耦合的技能网络。
 **阶段一：会话启动**
 
 当 Agent 会话启动时，系统会：
-1. 读取 Agent 配置中的 `context.skills` 列表
-2. 递归展开 `skill_dependencies`，构建完整的可见技能集（`visible_skills`）
-3. 将可见技能列表注入到系统提示词中
+1. 在创建 Graph 前读取已过滤的 `context.skills` 列表
+2. 递归展开 `skill_dependencies`，派生 `_prompt_skills` 和 `_readable_skills`
+3. 将 `_prompt_skills` 对应的技能说明注入到系统提示词中
 
-这意味着：只要配置了某个 Skill，它的依赖 Skill 就会立即对 Agent 可见。
+这意味着：只要配置了某个 Skill，它的依赖 Skill 就会立即进入提示词和 `/home/gem/skills` 只读范围。
 
 **阶段二：技能激活**
 
@@ -191,8 +191,8 @@ Skills 之间可以建立依赖关系，形成一个松耦合的技能网络。
 - **pro-skill**：依赖 `advanced-skill`
 
 当在 Agent 配置中只选择 `pro-skill` 时：
-1. 启动阶段：`visible_skills` = [`pro-skill`, `advanced-skill`, `base-skill`]（自动展开依赖链）
-2. Agent 首次调用任何 skill 时：所有三个 Skill 都可见
+1. 启动阶段：`_readable_skills` = [`pro-skill`, `advanced-skill`, `base-skill`]（自动展开依赖链）
+2. Agent 首次调用任何 skill 时：所有三个 Skill 都可读
 3. 当 Agent 读取 `pro-skill/SKILL.md` 时：触发激活，工具和 MCP 依赖被加载
 
 ## 权限管理