# dsh-devforge 用户手册

## 1. 这是什么

天工造梦是一个运行在 DSH Web Host 内的双面插件：

- **Host 半边**：注册本机 API 路由、Agent 工具、模型服务、凭据引用、SQLite `store.db`、子代理和外部连接。
- **浏览器半边**：在 DSH 左侧「天工造梦」入口中提供配置面板、状态看板、项目/仓库工作台和主题设置。
- **统一生命周期**：所有路由、工具、事件监听、定时任务和 UI 挂载都绑定到插件生命周期；停用或更新时会清理旧注册。
- **本机优先**：密钥由 DSH Host 凭据服务管理，页面只提交或显示状态，不把明文密钥放进 DOM、URL、普通设置或日志。

截图说明：本文中的截图来自隔离暂存实例 `http://127.0.0.1:3081` 的真实页面。截图基线为已安装的 `v0.22.0`，当前源码版本为 `v0.23.0`；页面拓扑和主要功能一致，版本号以运行中的包为准。截图不会展示 API Key、Token 或 Secret。

## 2. 页面总览

天工造梦当前有 14 个顶层页签。首次打开默认进入「教程」；「皮肤」只有在宿主提供 Theme Runtime 时显示。

| 页签 | 入口 | 主要用途 |
| --- | --- | --- |
| 教程 | 左侧天工造梦 → 教程 | 首次配置、账号入口、功能目录、常用操作和安全排错 |
| Coding Plan | 顶部页签 | 管理智谱、MiniMax、火山方舟、硅基流动和 OpenAI 中转 |
| 记忆中枢 | 顶部页签 | 知识库、文档入库、混合检索测试、向量和精排设置 |
| 记忆工作台 | 顶部页签 | 长期记忆、用户身份卡、知识图谱、自动沉淀与主动注入 |
| 工作流 | 顶部页签 | 创建并运行可重复的 RAG 查询-生成流程 |
| MCP | 顶部页签 | 配置外部 MCP 服务器并把工具注册给模型 |
| 开发规范 | 顶部页签 | 浏览插件内置的版本化中文开发规范 |
| 浏览器 | 顶部页签 | 管理可见 Chrome、标签页和安全页面操作 |
| 远程运维 | 顶部页签 | 管理 SSH/WinRM 主机和发布目标 |
| 项目 | 顶部页签 | 登记项目、检测仓库、管理多机路径和产出公约 |
| 代码仓库 | 顶部页签 | CNB/GitHub 账号、仓库、本地 Git 和安全设置 |
| 飞书 | 顶部页签 | 飞书长连接、独立会话、允许用户和完成通知 |
| 插件更新 | 顶部页签 | 检查 dsh-devforge 与 DSH 本体更新 |
| 皮肤 | 顶部页签 | 主题、强调色、壁纸和全局外观 |

## 3. 教程页

![教程页](assets/screenshots/guide.png)

教程页本身是可操作的入口，不只是静态说明：

- **首次配置**：告诉用户如何打开面板、准备模型账号、保存并同步模型，以及推荐的配置顺序。
- **账号与密钥**：提供智谱、MiniMax、火山方舟、硅基流动、OpenAI 兼容中转、GitHub、CNB 和飞书的官方入口。
- **功能说明**：可按关键词搜索并展开功能条目；「打开」按钮切到对应顶层页签。
- **常用操作**：覆盖第一次聊天、让模型读懂项目、换电脑继续工作、把任务交给飞书四条路径。
- **安全与排错**：解释凭据保存、模型不出现、RAG 无结果、换电脑/升级和生产验证红线。

教程页的配置入口只负责导航，不复制其它页签的业务逻辑。

## 4. Coding Plan

![Coding Plan 总览](assets/screenshots/coding-plan.png)

Coding Plan 工作区左侧展示服务商状态和用量速览，右侧切换服务商与功能页。它不会把 API Key 回填到浏览器。

### 4.1 智谱 GLM

![智谱 GLM](assets/screenshots/coding-plan-zhipu.png)

- 保存主 Key 和附加 Key 槽位；当前实现支持主 Key 加 `_2` 到 `_6` 的容灾池。
- 自动补齐官方模型，支持手动从官方 `/v4/models` 拉取模型。
- 展示 5 小时/周额度、重置倒计时、模型调用统计和 MCP 工具用量。
- 智谱 MCP 工具包括联网搜索、网页读取、Zread 仓库结构和文件读取。
- 401、403、429 或额度耗尽时，官方调用按 Key 池顺序切换下一把 Key。

### 4.2 MiniMax

![MiniMax](assets/screenshots/coding-plan-minimax.png)

- 配置订阅 Key、同步文本模型和查看订阅用量。
- 提供联网搜索、图像理解、图像生成、语音合成和视频生成能力。
- 另有 MiniMax Hub 桌面 Gateway 通道：Hub 已登录时，可调用 Hub 的图像和 H3 视频生成，不把 Hub 会话复制进 DSH。
- 国内站点、国际站点和 Key 必须保持一致。

### 4.3 火山方舟

![火山方舟](assets/screenshots/coding-plan-ark.png)

- 使用 Plan Key 访问套餐模型和推理档位。
- 使用火山控制面 Access Key/Secret Key 查询 Agent Plan/Coding Plan 用量。
- 「使用配置」和「用量统计」分开，Plan Key 与 AK/SK 不混用。
- 额度看板提供 5 小时、周、月窗口和重置时间。

### 4.4 硅基流动

![硅基流动](assets/screenshots/coding-plan-siliconflow.png)

- 保存受管 API Key。
- 同步精选最新版模型目录，写入 DSH 模型路由。
- 为 RAG 提供 `BAAI/bge-m3` 向量模型，不依赖余额查询接口。

### 4.5 OpenAI 兼容中转

![OpenAI 兼容中转](assets/screenshots/coding-plan-openai.png)

- 支持多个端点，每个端点独立名称、Base URL、受管凭据引用和协议类型。
- 支持 OpenAI Responses 和 Anthropic Messages 兼容协议。
- 通过 `GET /v1/models` 发现模型，保存后注册到 DSH 模型路由。
- 每个模型可单独修改上下文窗口（tokens）；Anthropic Messages 端点还可修改输出上限，显式设置的容量不会被后续模型同步重置。
- 为端点选择生图模型后，Host 注册全局 `generate_image`，生成结果落盘到工作区并在聊天中预览。
- 旧版 `dsh-sub2api` 配置会迁移到当前端点模型，不读取或复制 Key 明文。

## 5. 记忆中枢（RAG）

![记忆中枢](assets/screenshots/rag.png)

记忆中枢负责把本地文档转换为可检索知识：

- 创建和管理知识库，支持文档状态、切块数量和来源查看。
- 解析 Markdown、PDF、DOCX 等文件，按标题层级切块，保留来源和行号信息。
- 使用中文全文检索与向量相似度混合排序；可配置 Top-K、向量权重和相关度阈值。
- 支持智谱、方舟、OpenAI 兼容、Ollama、硅基流动和自定义 OpenAI 兼容向量渠道。
- 支持智谱 Rerank；没有 Rerank 时可使用默认模型路由做 LLM 兜底评分。
- 更换 embedding 模型会提示重嵌，避免旧维度向量与新模型混用。
- Agent 可调用 `rag_search`；工作流可调用同一套 RAG 引擎。

项目知识索引会尊重 `.gitignore`，按修改时间和内容摘要做增量更新，避免每次重新扫描全部仓库。

## 6. 记忆工作台

![记忆工作台](assets/screenshots/memory.png)

记忆工作台管理内置长期记忆和会话记忆层：

- **用户身份卡**：保存称呼、身份、习惯和偏好，作为每轮系统提示的常驻上下文。
- **自动沉淀**：会话结束时从对话中提炼值得长期保留的信息；提炼结果只产生「候选」，经人工审核后才参与召回。
- **主动注入**：每轮开始检索与当前问题相关的记忆，只注入命中内容；词法与语义混合召回，嵌入服务故障时自动降级到词法通道。
- **项目作用域**：登记项目后，项目专属记忆只在同项目会话召回，跨项目互不可见；全局记忆始终可见。
- **内置长期记忆**：使用插件自己的 `store.db` 主存储，可手动新增、搜索和软归档；每条记忆带信任等级、作用域、证据与版本链。
- **记忆治理**：候选审核（批准/拒绝/冲突取代）、任务复盘、召回轨迹与质量反馈、归档恢复。正反馈只做质量统计，绝不自动改写记忆。
- **知识图谱**：根据记忆条目、关键词和分类现算节点与边，支持点选查看详情和过滤。
- **会话沉淀库**：查看最近自动产生的记忆原文和切块信息。
- **外部迁移/镜像**：支持 Mnemon/Hindsight 的幂等迁移与只读同步，迁移前不删除外部数据。
- **项目知识索引**：填写本机绝对路径，增量写入 RAG 知识库。

### 可信记忆模型（0.28.0）

记忆写入遵循「候选优先」纪律：

1. **模型提炼、外部导入只产生候选**（`memory.candidate`），候选永远不参与召回。
2. **激活只有两条路**：在记忆治理面板人工审核批准；或在对话里明确说「记住……」，由宿主回读原话验证后直接激活。
3. **正反馈只是影子数据**：对召回结果点「有用」只累计质量统计，不会自动提升信任、排序或常驻状态。
4. **错误记忆可隔离**：反馈「有错误/已过期」会把非钉选条目移出召回并等待人工处理；钉选条目任何自动化都不可触碰。
5. **冲突显式取代**：同一事实键出现新说法时，候选标记冲突，批准时必须明确选择取代哪条旧记忆，新旧版本链完整留痕（可追溯谁取代谁）。
6. **任务复盘**：每轮完成记录目标、结果、工具成败与教训，并校验「模型声明用了哪些记忆」是否与真实召回一致，防止复盘造假。

设置、计数和记忆条目跨重启保存在 `store.db`；向量属于派生数据，可按配置重新生成。

## 7. 工作流

![工作流](assets/screenshots/workflow.png)

工作流页把 RAG 和生成步骤组合成可重复执行的管线：

1. 查询改写（可选）。
2. 知识库检索。
3. 向量/关键词混合与精排。
4. 默认模型生成答案。
5. 自评检查和有限次数重试。

工作流定义、节点参数、最大 Token、Top-K、向量权重和自评重试开关都可保存。运行台展示答案、来源、步骤耗时和最近运行记录，便于比较参数调整前后的效果。

## 8. MCP 服务器

![MCP 服务器](assets/screenshots/mcp.png)

MCP 页管理两种外部服务器：

- **stdio**：本地命令、参数和环境变量，适合本机脚本或包管理器启动的 MCP Server。
- **Streamable HTTP**：远程 URL 和受管凭据引用，适合团队或局域网服务。

启用后，工具以 `mcp__<命名空间>__<工具名>` 注册到模型。Host 会负责连接、断开、重连和生命周期清理；调用错误原样返回可诊断信息。密钥只存受管凭据，不写入服务器 URL。

## 9. 开发规范

![开发规范](assets/screenshots/standards.png)

开发规范页读取插件内置的 `standards/` Markdown：

- `v1/common.zh.md`：职责边界、中文注释、可读性、复用、安全、日志、验证和版本管理。
- `v1/api.zh.md`：Api/Bll/Dal/Model/Utility 的单向分层。
- `v1/web-service.zh.md`：Web 服务结构、日志、健康检查和交付。
- `v1/frontend.zh.md`：页面层、API 客户端边界和前端可读性。

Agent 工具 `devforge_standards` 可以列出或读取规范；`devforge_jobs` 按模板创建独立服务生成子代理。生成任务的进度在 DSH 任务看板/会话任务入口查看。当前中心操作台没有单独的“任务/新建服务”页，服务生成由 Host 工具和任务面板承载。

## 10. 可见浏览器与平台运营

![浏览器](assets/screenshots/browser.png)

浏览器能力使用本机前台 Chrome 的持久用户档案，不开启隐形浏览器：

- `browser_status`：读取能力和当前页面状态，不返回 profile 路径。
- `browser_open`：打开新的独立标签页。
- `browser_tabs`：列出、新建、选择、关闭和清理标签页。
- `browser_snapshot`：获取无障碍快照，并绑定 `t<tab>g<generation>:<ref>` 作用域引用。
- `browser_click`/`browser_type`：只接受仍然属于对应标签页和快照代次的引用。
- `browser_upload`：在对应标签页内完成图片上传、校验和快照刷新。
- `browser_close`：停止本机托管浏览器并清理未完成浏览器任务。

闲鱼和小红书操作遵守更严格的确认边界：

- 读取闲鱼会话不会发送消息；打开未读会话会触发平台已读。
- `xianyu_reply` 必须绑定联系人和完整确认短语。
- `xianyu_publish` 必须使用「确认发布」，并核验最终商品详情页。
- `xiaohongshu_publish` 同样要求「确认发布」，封面必须是本机图片。

## 11. 抖音直播侧栏（独立控件）

![抖音直播侧栏](assets/screenshots/douyin-live-sidebar.png)

当宿主安装并启用 `dsh-better-sidebar` 时，天工造梦会注册一个独立的「抖音直播」单例侧栏标签；它不属于中心操作台的 14 个顶层页签：

- 输入直播间链接或房间号后连接/断开接收器。
- 自动跟随直播伴侣，显示未开播、直播中或状态未知。
- 打开/关闭进场和点赞语音播报。
- 按弹幕、礼物、点赞、进场、互动、系统、其他筛选消息，并按昵称或内容搜索。
- 自动滚动、清空列表；关闭或切换标签只暂停浏览器轮询，不会逆向断开 Host 连接。
- 从 DSH 会话中打开白名单抖音直播链接时，侧栏会自动接管链接并发起连接。

Host 持有连接和接收器进程，浏览器只读取快照和发起明确动作；网络错误、轮询超时和上游状态未知都会在侧栏中显示。

## 12. 远程运维

![远程运维](assets/screenshots/remote.png)

远程运维页维护 Linux/Unix 与 Windows 主机的脱敏摘要：

- SSH：密码、私钥或 Agent；命令执行、批量执行、PTY、SFTP 上传/下载、端口转发。
- WinRM：HTTP/HTTPS、密码认证；PowerShell、批量执行、文件传输、进程查询/终止、服务启停/重启和启动类型管理。
- 远程连接池和隧道归属插件生命周期，停止或更新会清理连接。
- 项目发布目标会复用远程引擎执行部署命令，并按退出码判断成功，不把未知状态报成成功。

## 13. 项目与产出公约

![项目管理](assets/screenshots/projects.png)

项目页把本机代码仓库与智能体工作上下文绑定：

- 手工登记项目名称、绝对路径、描述、GitHub/CNB 仓库、分支和 SSH/WinRM 发布目标。
- 扫描常用代码根，发现 Git 仓库后批量登记。
- 检测 `.git` 远端、当前分支、最近提交和 `package.json`/README 描述。
- 多机路径映射支持重定位和自动匹配，换电脑后可以恢复项目上下文。
- `devforge_project` 工具支持 list/resolve/detail。
- 产出公约把项目、临时文件、脚本、下载、备份、交付物、笔记放进固定类别目录；`devforge_workspace` 支持 locate/audit。
- 项目可配置一键发布命令，按目标逐台执行并返回结构化结果。

项目命中当前会话工作目录后，模型上下文会获得项目仓库、发布目标和路径失效提示。

## 14. CNB 与 GitHub 代码仓库

![CNB 账号](assets/screenshots/repos-cnb-accounts.png)

![GitHub 账号](assets/screenshots/repos-github-accounts.png)

「代码仓库」包含 CNB 和 GitHub 两个工作台。两者各自保存账号和安全设置，底层 Git 操作统一走临时认证头，不把 Token 写进远端 URL。

### CNB 子页

| 截图 | 子页 | 能力 |
| --- | --- | --- |
| ![CNB 仓库](assets/screenshots/repos-cnb-repos.png) | 仓库 | 按账号/关键词查询仓库，带入 Clone 参数 |
| ![CNB Git](assets/screenshots/repos-cnb-git.png) | 本地 Git | Status、Clone、Pull、Commit、Push |
| ![CNB 安全设置](assets/screenshots/repos-cnb-settings.png) | 安全设置 | API 地址、默认账号/目录/分支、自动拉取、Push 和 Force Push |
| ![CNB 备份](assets/screenshots/repos-cnb-backup.png) | 加密备份 | store.db + 飞书配置加密到 CNB 私密仓库，支持预览、恢复和跨机同步 |

CNB 只支持 HTTPS + 访问令牌，Git 用户名固定为 `cnb`；推送和强制推送默认关闭。

### GitHub 子页

| 截图 | 子页 | 能力 |
| --- | --- | --- |
| ![GitHub 仓库](assets/screenshots/repos-github-repos.png) | 仓库 | 查询账号可见仓库并准备 Clone |
| ![GitHub Git](assets/screenshots/repos-github-git.png) | 本地 Git | Status、Clone、Pull、Commit、Push |
| ![GitHub 安全设置](assets/screenshots/repos-github-settings.png) | 安全设置 | API 地址、默认账号/目录/分支、自动拉取、Push 和 Force Push |

### Git 工具安全

- `status` 读取分支和变更文件。
- `commit` 只创建本地提交，不隐式推送。
- `push` 需要在对应平台安全设置中显式开启；Force Push 还要单独开启。
- 本地仓库路径必须是绝对路径；Git 输出会脱敏 Token。

## 15. 飞书

![飞书配置](assets/screenshots/feishu.png)

飞书页把 DSH 接入企业自建应用长连接：

- 保存 App ID、App Secret、独立会话工作目录、允许的 open_id、群聊响应模式和 Agent 预设。
- 测试连接后再启用；页面只显示掩码，不回显 App Secret。
- 每个飞书用户/会话使用独立 DSH 会话，支持电脑端任务完成卡片通知。
- 暂存实例必须关闭飞书桥，避免与生产实例使用同一个 appId 的长连接发生事件分流。

## 16. 插件更新与 DSH 本体

![插件更新](assets/screenshots/plugin-update.png)

插件更新页并行检查两类版本：

- `dsh-devforge`：官网 `modagentai.com/downloads/index.json` 优先，GitHub 仓库兜底；官网 `.tgz` 下载会核对 `sha256`。
- DSH 本体：对比官方 `deepseek-ai/deepseek-harness` Tags，只给出复制升级命令，不替换正在运行的宿主进程。

安装/升级完成后：

1. 先查看版本和安装结果。
2. 对 Host 半边变更，按提示重启 DSH。
3. 重启是破坏性动作，必须由用户明确要求，生产不能由插件自动重启。

## 17. 皮肤与全局外观

![皮肤](assets/screenshots/skin.png)

皮肤页通过 DSH 官方 Theme Runtime 修改全局 GUI：

- 14 套内置主题，覆盖浅色、深色和多种强调色。
- 8 个强调色预设和自定义色。
- 本地图片、HTTP(S) 或 data URL 壁纸。
- 遮罩浓度、模糊半径和显示方式可调。
- 偏好写入浏览器 `localStorage`，跨刷新和重启恢复。
- 主题运行时不可用时，页签不会显示伪入口。

![Coding Plan 页面](assets/screenshots/coding-plan.png)

## 18. Agent 工具清单

工具由 Host 按能力开关注册；以下是主要工具族，实际可用列表会随配置和已安装插件动态注入。

| 工具族 | 代表工具 |
| --- | --- |
| 开发工厂 | `devforge_standards`、`devforge_jobs`、`devforge_restart` |
| 项目与目录 | `devforge_project`、`devforge_workspace` |
| GitHub | `github_auth_*`、`github_repo_list`、`github_clone`、`github_pull`、`github_status`、`github_commit`、`github_push` |
| CNB | `cnb_auth_*`、`cnb_repo_list`、`cnb_clone`、`cnb_pull`、`cnb_status`、`cnb_commit`、`cnb_push` |
| SSH | `ssh_list`、`ssh_exec`、`ssh_cluster`、`ssh_upload`、`ssh_download`、`ssh_tunnel` |
| WinRM | `winrm_list`、`winrm_exec`、`winrm_cluster`、`winrm_upload`、`winrm_download`、`winrm_process`、`winrm_service` |
| 浏览器 | `browser_status`、`browser_open`、`browser_tabs`、`browser_snapshot`、`browser_click`、`browser_type`、`browser_upload` |
| 平台运营 | `xianyu_messages_list`、`xianyu_conversation_read`、`xianyu_reply`、`xianyu_publish`、`xiaohongshu_publish` |
| RAG/工作流 | `rag_search`、`rag_run` |
| 备份 | `backup_status`、`backup_now` |
| 外部 MCP | `mcp__<server>__<tool>` 动态工具 |
| 智谱/MiniMax | 官方联网搜索、网页读取、Zread、图像理解、图像生成、语音合成和视频生成 |

工具描述会随插件启停、配置和市场安装状态动态更新；不要把一次会话看到的工具列表当成永久固定清单。

## 19. 数据与安全边界

- API 路由默认只接受本机 loopback 请求。
- 凭据通过 DSH credentials service 保存；列表接口只返回别名、用户名或掩码。
- Git Token 经临时 Header 注入，绝不写入 URL、远端配置和命令日志。
- CNB 备份采用 6 位密码加密，仓库内只放密文；恢复前提供文件和来源机器预览，覆盖前自动保留备份。
- 浏览器登录状态留在本机持久档案；插件不读取或输出 Cookie、密码和 Token。
- 插件代码拥有与 DSH Host 相同的本机权限；安装第三方插件前应审阅源码。市场收录不等于安全审计。
- 项目开发、构建、测试和部署必须走隔离 HOME 暂存实例；暂存端口固定 `3081`，生产端口为 `3080`。
- 暂存实例显式禁用桌面宠物和飞书桥；只有用户明确要求才可重启生产 DSH。

## 20. 进一步阅读

- [发布与开源指南](发布与开源指南.md)
- [CNB 代码托管对接说明](CNB代码托管对接说明.md)
- [火山方舟用量看板教程](火山方舟用量看板教程.md)
- [天工造梦 RAG 套件全流程](天工造梦RAG套件全流程.md)
- [智能体项目管理与产出公约](智能体项目管理与产出公约.md)
- [插件暂存环境测试约束](插件暂存环境测试约束.md)