墨寒桌面語音互動虛擬助理／墨寒桌面语音互动虚拟助手／MoHan Desktop Assistant／墨寒デスクトップアシスタント

繁體中文

繁體中文 · 簡體中文 · English · 日本語

墨寒是重視安全、隱私與角色連續感的 Windows 語音互動桌面助理。

[下載 Windows 安裝程式](https://github.com/flameblade-studio/MoHan-PC-Desktop-Assistant/releases) · [快速開始](QUICKSTART.md) · [跨平台能力矩陣](docs/CROSS-PLATFORM.md)

軟體作者：CHOU MING HUA · Windows 10/11 完整版 · macOS／Linux 功能受限 Preview
最新正式版本： v4.6.0（2026-08-29）。實際產物仍須通過本版最終發布門檻；已發布程式以 Releases 為準；下列主線更新另標示待發布狀態。

這是什麼

墨寒是重視安全、隱私與角色連續感的 Windows 語音互動桌面助理。她以透明 2.5D 角色、自然語音、由使用者控制的本機長期記憶、待辦與工作工具陪伴日常；角色設定是來自北宋、附生於赤焰劍中的千年女劍魂。

畫面與功能一覽

觀看實際展示。設定與主要畫面：首次設定、語音模式、表情、待辦與靈感、長期記憶、安全權限。

• V5 二代素體提供全身 24 角度、半身表情、眨眼、說話嘴型與 50 Hz 嘴型同步。
• 外袍、髮型、髮飾與妝容採可拆卸外觀圖層；主線藍白漢服的 24 視角鞋子已統一為白底藍花繡花平底鞋，妝容提供素顏、淡妝、經典與華麗四級。
• 文字、Realtime、Windows 本機女聲、OpenAI TTS 與 Azure Speech 選用路徑。
• 對話、可編輯記憶、待辦、靈感、工作計時、提醒與可攜設定檔。
• 工具執行需經權限、風險分級、確認、稽核與緊急停止。
• Google 已完成實連線驗證；Microsoft、GitHub、Home Assistant 仍是實驗性 Preview。
• 多感官視覺、手勢、遠端存取與雲端連接器預設關閉並可個別撤銷。

四語支援範圍

繁體中文、簡體中文、英文與日文均提供首次設定、對話、語音、權限、基本設定、工作模式與提醒。進階頁面仍可能留有繁體中文；Azure Speech（預覽）的實際語音、區域、額度與費用以使用者自己的服務帳號為準。

三專案與角色包

墨寒保留既有名稱、網址、版本與使用者，定位為可直接安裝的產品。MIT 授權的 炎劍鑄魂 Soulforge Engine 負責通用互動與執行機制，主線已完成引擎對墨寒產品殼的依賴拆分；MIT 授權的 炎劍畫譜 Flameblade Huapu 負責角色素材清冊、核准與匯出。角色的人設、台詞、聲音與外觀由角色包提供。

• 墨寒角色包：千年女劍魂墨寒的人設、台詞、聲音與外觀資料，使用 mohan-pack-v* 標籤。
• 林可芸角色包：墨寒的今生，是稱呼使用者「劍主」的現代女性，使用 lin-keyun-pack-v* 標籤。

兩個角色包都在本專案的 Releases 獨立提供，需另外下載，不隨安裝檔附帶。下載不需金鑰，安裝前會核對大小、SHA-256、manifest 與逐檔內容。

截至 2026-10-21，最新已發布角色包為墨寒 1.0.6、林可芸 1.0.4 與素體包 mohan-body-v2 1.0.0；待發布版本為墨寒 1.0.7。角色包版號與程式版號分開，主線更新將隨後續發布提供。

主線已合併、待發布的更新

炎劍鑄魂引擎已支援角色包依附指定素體包：素體提供身形、眨眼與嘴型，角色包提供髮型、服裝與妝容；缺少相符素體時會清楚提示。每個角度可安排不同圖層前後順序，並用素體隱藏遮罩移除衣髮下多出的底圖；臉部核心以柔邊線性混合保留表情與嘴型，讓臉與角色外觀自然銜接。作者規格與建置驗證見 素體包與角色圖層。素體包另行下載（#296）與墨寒官方長髮造型仍在開發中。

• 正面 13 組表情包含說話與眨眼狀態；妝容四級層次更清楚，眼妝、腮紅、唇妝可各自調整濃淡。
• 雲裳閣可拖曳或用方向鍵環視 24 角度，Home 回正面；換裝與調妝保留目前角度。
• 控制中心字級放大，桌面狀態卡可收合並記住偏好；外部主題也會套用至選取狀態。
• 午餐與晚餐提醒各自保存送達、回應與延後狀態；四語自然語言任務判斷已修正，撤銷資料夾或 OAuth 授權會立即阻止舊工作繼續使用權限。

墨寒的傲嬌工程小劇場 / MoHan's Tsundere Developer Theatre

六張半身表情皆為二代素體、官方藍白漢服與內建原妝經正式執行期路徑合成的固定素材。

「妾在等你的 Star，也順道確認軍心。」	「這段邏輯尚可。若再補上測試，妾便勉強准它入主分支。」	「你願意送來 PR？妾、妾只是替主上記下功勞。」
「未經測試便想合併？手伸出來。妾只敲一下。」	「全數綠燈……做得好。別誤會，妾只是尊重好工程。」	「Bug 可以明日再查。你若累倒，誰來陪妾守著赤焰劍？」

策士審查 確認程式是否配得上主分支。

被稱讚時 做得尚可，別一直盯著妾看。

危險操作 未經確認，先過妾這一劍。

收到軍糧 妾會記下這份心意。

安裝與更新

1. 從 GitHub Releases 下載以 Windows-x64-Setup.exe 結尾的安裝程式；進階使用者也可選完整的 Windows-x64.zip 或 MSI。
2. 安裝前核對 SHA256SUMS 與 GitHub Artifact Attestation。來源、檔名與雜湊一致時再繼續，並保持整體安全防護開啟。
3. 啟動安裝程式，或完整解壓 ZIP 並保持 EXE、內部資料夾與 assets 在同一目錄；更新會完整保留本機個人資料。
4. 內建更新器先用內嵌公鑰驗證更新清單的 Ed25519 分離 .sig 簽章，再核對宣告大小與 SHA-256；下載檔只在簽章、大小及雜湊全部驗證通過後啟動。

macOS／Linux Preview 目前提供限定功能，平台商店簽章與公證狀態依各 Release 標示；只從本專案 Release 取得並完成上述來源驗證。詳見 Preview 套件說明。

第一次使用要做的三件事

1. 在首次設定精靈確認介面語言、助理名稱、主上稱呼、組織、工作類型與喚醒詞；既有設定會完整保留。
2. 先試 Windows 本機女聲；需要雲端 AI 時，再到設定輸入自己持有的 OpenAI API 金鑰。ChatGPT 訂閱不包含 API 額度。
3. 檢查麥克風、通知與工具權限，只開啟真正需要的連接器；先記住緊急停止鍵 Esc 與「墨寒，停手」。

雲端連接器設定

Google OAuth

使用 Gmail、Google Calendar 與 Google Drive 前，請先完成：

1. 在自己的 Google Cloud 專案啟用 Gmail API、Google Calendar API 與 Google Drive API。
2. 設定 OAuth 同意畫面；若應用程式仍在測試模式，將自己的 Google 帳號加入測試使用者。
3. 建立「桌面應用程式」OAuth Client ID。
4. 開啟墨寒「設定」頁的「旗艦控制中心」→「雲端連接器」，選擇 Google（Gmail／Calendar／Drive），填入「OAuth Client ID」；只有供應商提供「OAuth Client Secret」時才填入。
5. 在「授權範圍」保留以下預設 scopes，按「開啟瀏覽器安全連線」完成瀏覽器授權，再按「測試選取服務」。

程式預設請求以下 Google scopes：

openid
email
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/drive.metadata.readonly

公開 OAuth 應用程式若使用敏感 scopes，可能需要 Google 額外驗證；每位使用者也可建立自己的 Desktop OAuth 應用程式。

Microsoft、GitHub 與 Home Assistant

• Microsoft 預設 scopes：openid、offline_access、User.Read、Mail.ReadWrite、Mail.Send、Calendars.ReadWrite、Files.ReadWrite。
• GitHub 預設 scopes：read:user、repo。
• Home Assistant：先在自己的 Home Assistant 個人檔案建立 Long-Lived Access Token；在墨寒「設定」頁的「旗艦控制中心」→「智慧家庭」勾選「啟用 Home Assistant 整合」，填入「Home Assistant 位址」與「長期存取權杖」，確認「驗證 HTTPS 憑證」後按「保存設定」，再用「測試連線」或「讀取裝置」確認。

這三項是架構與安全邊界已完成的 Preview 整合，下一驗證階段涵蓋真實環境端到端流程。初次使用請選擇測試帳號與低風險設備；遠端連線的支援範圍是 Home Assistant Cloud、Tailscale 或其他具身分驗證的加密私人網路。

隱私與本機優先

• Windows 的對話、記憶、待辦、設定、工作紀錄、權限與稽核預設存於 %LOCALAPPDATA%\YanJianStudio\MoHan；備份位於其 backups 子目錄，可攜資料使用單一 .mohan-profile。
• 只有使用者啟用相關功能時，完成該次要求所需的文字、音訊或工具規劃才會送往 OpenAI；OAuth 服務只收到使用者同意的 API 要求，Home Assistant 收到本機裝置要求。
• API 金鑰與 OAuth／Home Assistant Token 以 Windows DPAPI 分離保存，只存於各自的 DPAPI 檔案；SQLite、原始碼、日誌、一般可攜檔與 ChatGPT 帳號歷史均在助理資料範圍之外。
• 相機、遠端存取與雲端連接器由使用者主動啟用；原始相機影格保持即時暫存並於處理後釋放，權限與服務檢查通過的路徑才會啟動。

多感官視覺由使用者主動啟用。使用者在控制中心明確啟用並保存全體設定後，該選擇構成持續授權，直到主動關閉；此授權持續適用於後續影格。畫面持續顯示授權狀態，可立即撤銷，並可設成本上限與終止進行中的分析。本機 OpenCV 負責持續偵測，只有低頻或事件觸發才將暫時影像送往 GPT-5.6；原圖保持即時暫存並於處理後釋放，日誌只記錄已移除 Base64 的內容，網路由使用者設定啟用。相機、模型、網路、額度及辨識皆可用時該路徑才啟動，其餘功能維持運作。完整邊界見 隱私說明 與 安全政策。

DLC 與外觀自訂

.mohan-outfit 是角色外觀容器，可含衣裝、髮型、頭飾、妝容與配件；妝容專用包仍是同一格式。.mohan-theme 只改控制台色彩、字型、圓角與可選背景，不改角色外觀。兩者都是單一、自包含、免解壓檔案，安裝前會完整驗證且不執行其中的程式碼。

安裝、選用外觀與妝容

1. 下載 .mohan-outfit，並保持副檔名與封裝完整。
2. 開啟控制中心「雲裳閣」，按「匯入服裝套件」並選檔；衣裝包與妝容包共用此入口、驗證、清單與移除流程。
3. 從套件或完整造型清單選取後按「套用選取服裝」；主線妝容選單提供素顏、淡妝、標準妝、華麗妝與已安裝款式，再用 0–100% 滑桿調整整體及眼妝、腮紅、唇妝濃度。
4. 要撤銷自訂外觀，按「還原內建服裝」；妝容改選內建原妝或素顏。內建藍白漢服與內建妝容固定保留，且同 id 套件沿用內建版本。

安裝與還原主題

1. 下載 .mohan-theme，並保持封裝完整。
2. 在「設定」→「控制台佈景主題」按「上傳單一檔案」，選取主題後從清單預覽。
3. 按右下「保存設定」正式套用；選擇「取消」即可回到原主題。「還原主題」可預覽內建主題，再保存完成還原。

容量、數量與相容性

• 單一外觀包最多 1 GiB，解壓後總量最多 2 GiB、最多 2,048 個成員；每個成員最多 128 MiB，圖片任一邊最多 4,096 px。
• 單一主題檔及解壓總量最多 16 MiB，每個成員最多 12 MiB，背景任一邊最多 4,096 px。
• 雲端自創服裝預設保留 16 包、總容量 6 GiB、修復待審隔離 5 件；前兩項可各調為 1–64。生成量以此上限為界，使用者匯入包會完整保留。
• 現行二代骨架只接受 mohan-body-v2。為 mohan-body-v1 三姿勢製作的一代包採用一代三姿勢契約；匯入與執行期只接受具備二代 31 個輪廓、錨點與遮蔽契約的套件；請以 tools/build_outfit_pack.py 對二代範本重建，或用「一鍵製衣」重新生成。
• 安裝採完整驗證後原子寫入；絕對路徑、跨目錄路徑、可執行程式、腳本、符號連結、加密成員、解壓炸彈與未宣告素材均位於套件接受範圍之外。

完整作者規格見 外觀包文件。

贊助者 DLC：赤焰劍光

取得、驗證與安裝

「赤焰劍光」是 Dashboard 的純裝飾性贊助者 DLC，不解鎖、限制或改變任何功能；墨寒的功能永遠免費。請在 Ko-fi 赤焰劍光頁面完成支持並下載 flame-sword-theme-dlc.zip。只解開這一層 ZIP，以 PowerShell 執行 (Get-FileHash .\flame-sword-theme.mohan-theme -Algorithm SHA256).Hash.ToLower()，並與隨附的 SHA256SUMS 比對；不要再解開 .mohan-theme。

開啟 Dashboard，依序前往「系統」→「設定」→「控制台佈景主題」，按「上傳單一檔案」並選取 flame-sword-theme.mohan-theme。上傳完成安裝，但不會自行啟用；在清單選取「赤焰劍光」即可「主題預覽」，按右下「保存設定」才會正式套用。按「取消（不要保存）」會回復先前已保存的主題。

若要切回預設，按「還原主題」預覽內建主題，再按「保存設定」。若要移除赤焰劍光，先切回其他主題並保存，重新選取赤焰劍光後按「移除外掛包」，再確認移除；內建主題與目前使用中或預覽中的主題都受到保護，不能直接刪除。

授權

付費代表贊助支持與搶先取得，不是排他散布權。由 CHOU MING HUA（炎劍文化工作室 Flameblade Studio）擁有的第一方 DLC 內容採 CC-BY-NC-ND-4.0：合法取得者可保留授權資訊與姓名標示，非商用原樣分享；不得商用或分享改作後內容，也不得暗示官方背書。建議標示：「赤焰劍光 © 2026 CHOU MING HUA（炎劍文化工作室 Flameblade Studio），CC BY-NC-ND 4.0」。第三方項目仍依各自條款；完整內容見 DLC-LICENSE.md 與主專案 ASSETS-LICENSE.md。

❤️⚔️ 支持墨寒：Ko-fi 贊助＆裝飾 DLC 下載

Ko-fi 贊助完全自願，不解鎖、不限制，也不改變任何功能。付費 DLC 是純裝飾的贊助謝禮，與角色包同採 CC BY-NC-ND 4.0，詳見上方赤焰劍光說明與 ASSETS-LICENSE.md。

支持墨寒 / Support MoHan：支持方式與授權

請使用儲存庫上方由 GitHub 顯示的 Sponsor 按鈕，或直接前往 Ko-fi，自由選擇單次或每月贊助；是否贊助不影響任何功能。企業導入、合作或顧問需求請透過 GitHub Issues 洽詢。

「妾才不是在等贊助……只是巡視軍糧。」

「若真願意相助，妾會記得的。」

「不許勉強，先顧好自己的荷包。」

• 作者：CHOU MING HUA；工作室官方英文名為 Flameblade Studio。
• 原始碼採 MIT License；墨寒與林可芸的角色內容（臉、名稱、人設、台詞與聲音）、內建外觀、妝容、含角色形象的應用程式圖示、docs/media/ 宣傳媒體，以及權利人發布的付費 DLC 均採 CC-BY-NC-ND-4.0，另有非商用粉絲作品許可，名稱與商標保留，不在 MIT 授權範圍。
• 素材生產工具與權重只接受 MIT、Apache 2.0、CC0、CC BY（及同級 BSD）白名單；字型是唯一例外：自 2026-09-02 起允許 SIL OFL 1.1，但僅限字型，不延伸至其他素材；角色資產另依 ASSETS-LICENSE 授權，產線純淨規則詳見 授權純淨承諾。
• 素材與第三方條款分別見 ASSETS-LICENSE 與 THIRD-PARTY-NOTICES。

本專案遵循炎劍開源軟體家族品質標準。

疑難排解

• Windows SmartScreen 或平台警告：先確認 GitHub Release 來源、SHA256SUMS 與 Artifact Attestation；並保持整體保護開啟。
• 對話連線檢查：確認自己的 OpenAI API 金鑰、Project 權限、額度與網路；API 呼叫使用獨立的 API 額度。
• 聲音輸出檢查：先切回 Windows 本機女聲；Azure Speech 需使用者自己的金鑰與相符區域。
• DLC 接受條件：確認檔案完整、大小、安全 manifest、四語名稱與 mohan-body-v2 相容性；一代包必須重建。
• Preview 整合檢查：先用非重要帳號、測試儲存庫與低風險設備；Microsoft、GitHub、Home Assistant 下一階段將完成各真實環境驗證。

一般問題請到 Issues，使用討論請到 Discussions，安全問題依 SECURITY 私下回報；規劃見 ROADMAP。

技術先行者：搶先採用 Python 3.15

墨寒在 Python 3.15 仍是候選版（3.15.0rc1）時就全面移轉，並大量採用 3.15 新增的延遲載入語法（PEP 810 lazy import），以寫法稽核工具把關整個程式庫。開發過程中，我們發現 3.15 的取樣分析工具在特定處理器上有高錯誤率，回報為 python/cpython#158552；Python 核心開發者據此修正，修正已收錄於 Python 3.15.0 正式版（python/cpython#158845）。墨寒現已執行於 3.15.0 正式版。為穩定起見，JIT 即時編譯預設關閉。

開發者入口

先讀 架構、測試說明、貢獻指南、外觀包規格 與 發布政策。Windows 安裝封裝版使用工作室維護的 Python 3.15 執行環境；原始碼與 CI 採 PEP 810 惰性匯入，文件維持四語同構。README 媒體請依 世代來源清單 維護。

py -3.15 -m ruff check .
py -3.15 tools/audit_python315_idioms.py
py -3.15 tools/check_four_language_docs.py
$env:QT_QPA_PLATFORM = "offscreen"
py -3.15 tests/run_all.py

Windows 正式封裝規格以 Rust 1.97.1、Maturin 1.14.1 與 PyO3 0.29.2 建置第一方原生模組；Rayon 1.12.0 只在至少 262,144 pixels 且有多執行緒時平行合成 RGBA。PyBackedBytes 避免額外輸入複製，但輸出仍建立新 bytes，效能聲明限於已量測的輸入零額外複製與既有純量／Rayon 路徑。SIMD 加速需先具備專用實作與量測證據。OpenAI Responses API 直接使用標準函式庫 HTTPS，執行期相依維持標準函式庫路徑。

简体中文

繁體中文 · 簡體中文 · English · 日本語

墨寒是一款重视安全、隐私与角色连续感的 Windows 语音交互桌面助手。

[下载 Windows 安装程序](https://github.com/flameblade-studio/MoHan-PC-Desktop-Assistant/releases) · [快速开始](QUICKSTART.md) · [跨平台能力矩阵](docs/CROSS-PLATFORM.md)

软件作者：CHOU MING HUA · Windows 10/11 完整版 · macOS／Linux 功能受限 Preview
最新正式版本： v4.6.0（2026-08-29）。实际产物仍须通过本版本最终发布关卡；已发布程序以 Releases 为准；下列主线更新另标明待发布状态。

这是什么

墨寒是一款重视安全、隐私与角色连续感的 Windows 语音交互桌面助手。她通过透明 2.5D 角色、自然语音、由用户控制的本地长期记忆、待办事项与工作工具陪伴日常；角色设定是来自北宋、寄居在赤焰剑中的千年女剑魂。

界面与功能一览

观看实际演示。设置与主要界面：首次设置、语音模式、表情、待办与灵感、长期记忆、安全权限。

• V5 二代素体提供全身 24 角度、半身表情、眨眼、说话口型与 50 Hz 口型同步。
• 外袍、发型、发饰与妆容采用可拆卸外观图层；主线蓝白汉服的 24 视角鞋子已统一为白底蓝花绣花平底鞋，妆容提供素颜、淡妆、经典与华丽四级。
• 文本、Realtime、Windows 本地女声、OpenAI TTS 与 Azure Speech 可选路径。
• 对话、可编辑记忆、待办事项、灵感、工作计时、提醒与便携配置文件。
• 工具执行必须经过权限、风险分级、确认、审计与紧急停止。
• Google 已完成真实连接验证；Microsoft、GitHub、Home Assistant 仍为实验性 Preview。
• 多感官视觉、手势、远程访问与云端连接器默认关闭并可单独撤销。

四语支持范围

繁体中文、简体中文、英文与日文均提供首次设置、对话、语音、权限、基本设置、工作模式与提醒。高级页面仍可能保留繁体中文；Azure Speech（预览）的实际语音、区域、配额与费用以用户自己的服务账号为准。

三项目与角色包

墨寒保留现有名称、网址、版本与用户，定位为可直接安装的产品。MIT 许可的 炎劍鑄魂 Soulforge Engine 负责通用互动与运行机制，主线已完成引擎对墨寒产品壳的依赖拆分；MIT 许可的 炎劍畫譜 Flameblade Huapu 负责角色素材清单、批准与导出。角色的人设、台词、声音与外观由角色包提供。

• 墨寒角色包：千年女剑魂墨寒的人设、台词、声音与外观数据，使用 mohan-pack-v* 标签。
• 林可芸角色包：墨寒的今生，是称呼用户“剑主”的现代女性，使用 lin-keyun-pack-v* 标签。

两个角色包都在本项目的 Releases 独立提供，需要另外下载，不随安装文件附带。下载无需密钥，安装前会核对大小、SHA-256、manifest 与逐文件内容。

截至 2026-10-21，最新已发布角色包为墨寒 1.0.6、林可芸 1.0.4 与素体包 mohan-body-v2 1.0.0；待发布版本为墨寒 1.0.7。角色包版本号与程序版本号分开，主线更新将在后续发布中提供。

主线已合并、待发布的更新

炎剑铸魂引擎已支持角色包依附指定素体包：素体提供体形、眨眼与口型，角色包提供发型、服装与妆容；缺少匹配素体时会明确提示。每个角度可安排不同图层前后顺序，并用素体隐藏遮罩移除衣发下多出的底图；脸部核心以柔边线性混合保留表情与口型，让脸与角色外观自然衔接。作者规范与构建验证见 素体包与角色图层。素体包另行下载（#296）与墨寒官方长发造型仍在开发中。

• 正面 13 组表情包含说话与眨眼状态；妆容四级层次更清楚，眼妆、腮红、唇妆可各自调整浓淡。
• 云裳阁可拖动或用方向键环视 24 角度，Home 回正面；换装与调妆保留当前角度。
• 控制中心字号放大，桌面状态卡可折叠并记住偏好；外部主题也会应用到选中状态。
• 午餐与晚餐提醒各自保存送达、回应与延后状态；四语自然语言任务判断已修正，撤销文件夹或 OAuth 授权会立即阻止旧任务继续使用权限。

墨寒的傲娇工程小剧场

六张半身表情均为二代素体、官方蓝白汉服与内置原妆经正式运行时路径合成的固定素材。

“妾才在等你的 Star，也顺道确认军心。”	“这段逻辑尚可。若再补上测试，妾便勉强准它进入主分支。”	“你愿意提交 PR？妾、妾只是替主上记下功劳。”
“未经测试便想合并？手伸出来。妾只敲一下。”	“全部绿灯……做得好。别误会，妾只是尊重好工程。”	“Bug 可以明天再查。你若累倒，谁来陪妾守着赤焰剑？”

谋士审查 确认程序是否配得上主分支。

被称赞时 做得尚可，别一直盯着妾看。

危险操作 未经确认，先过妾这一剑。

收到军粮 妾会记下这份心意。

安装与更新

1. 从 GitHub Releases 下载以 Windows-x64-Setup.exe 结尾的安装程序；高级用户也可选择完整的 Windows-x64.zip 或 MSI。
2. 安装前核对 SHA256SUMS 与 GitHub Artifact Attestation。来源、文件名与哈希一致时再继续，并保持整体安全防护开启。
3. 启动安装程序，或完整解压 ZIP 并保持 EXE、内部文件夹与 assets 在同一目录；更新不会删除本地个人数据。
4. 内置更新器先用内嵌公钥验证更新清单的 Ed25519 分离 .sig 签名，再核对声明大小与 SHA-256；签名、大小或哈希失败即拒绝启动下载文件。

macOS／Linux Preview 尚不等同于 Windows 完整版，且可能没有平台商店签名或公证；只从本项目 Release 获取并完成上述来源验证。详见 Preview 软件包说明。

第一次使用要做的三件事

1. 在首次设置向导确认界面语言、助手名称、对用户的称呼、组织、工作类型与唤醒词；现有设置不会被覆盖。
2. 先试听 Windows 本地女声；需要云端 AI 时，再到设置中输入自己持有的 OpenAI API 密钥。ChatGPT 订阅不包含 API 配额。
3. 检查麦克风、通知与工具权限，只开启真正需要的连接器；先记住紧急停止键 Esc 与“墨寒，停手”。

云端连接器设置

Google OAuth

使用 Gmail、Google Calendar 与 Google Drive 前，请先完成：

1. 在自己的 Google Cloud 项目启用 Gmail API、Google Calendar API 与 Google Drive API。
2. 设置 OAuth 同意屏幕；若应用程序仍处于测试模式，将自己的 Google 账号加入测试用户。
3. 创建“桌面应用程序”OAuth Client ID。
4. 打开墨寒“设置”页的“旗舰控制中心”→“云端连接器”，选择 Google（Gmail／Calendar／Drive），填写“OAuth Client ID”；仅在供应商提供“OAuth Client Secret”时填写。
5. 在“授权范围”保留以下默认 scopes，点击“打开浏览器安全连接”完成浏览器授权，再点击“测试选中服务”。

程序默认请求以下 Google scopes：

openid
email
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/drive.metadata.readonly

公开 OAuth 应用程序若使用敏感 scopes，可能需要 Google 额外验证；每位用户也可以创建自己的 Desktop OAuth 应用程序。

Microsoft、GitHub 与 Home Assistant

• Microsoft 默认 scopes：openid、offline_access、User.Read、Mail.ReadWrite、Mail.Send、Calendars.ReadWrite、Files.ReadWrite。
• GitHub 默认 scopes：read:user、repo。
• Home Assistant：先在自己的 Home Assistant 个人资料中创建 Long-Lived Access Token；在墨寒“设置”页的“旗舰控制中心”→“智能家居”勾选“启用 Home Assistant 集成”，填写“Home Assistant 地址”和“长期访问令牌”，确认“验证 HTTPS 证书”后点击“保存设置”，再用“测试连接”或“读取设备”确认。

这三项是架构与安全边界已完成的 Preview 集成，下一验证阶段涵盖真实环境端到端流程。初次使用请选择测试账号与低风险设备；远程连接的支持范围是 Home Assistant Cloud、Tailscale 或其他具有身份验证的加密私人网络。

隐私与本地优先

• Windows 的对话、记忆、待办事项、设置、工作记录、权限与审计默认存储在 %LOCALAPPDATA%\YanJianStudio\MoHan；备份位于其 backups 子目录，便携数据使用单一 .mohan-profile。
• 只有用户启用相关功能时，完成该次请求所需的文本、音频或工具规划才会发送到 OpenAI；OAuth 服务只收到用户同意的 API 请求，Home Assistant 收到本地设备请求。
• API 密钥与 OAuth／Home Assistant 令牌通过 Windows DPAPI 分开保存，不进入 SQLite、源代码、日志或普通便携文件；墨寒也不会自动获取 ChatGPT 账号历史。
• 摄像头、远程访问与云端连接器由用户主动启用；原始摄像头帧保持即时暂存并在处理后释放，权限与服务检查通过的路径才会启动。

多感官视觉由用户主动启用。用户在控制中心明确启用并全局保存后，该选择构成持续授权，直到用户主动关闭；此授权持续适用于后续帧。界面持续显示授权状态，可立即撤销，并可设置成本上限与终止进行中的分析。本地 OpenCV 负责持续检测，只有低频或事件触发才将临时图像发送到 GPT-5.6；原图保持即时暂存并在处理后释放，日志只记录已移除 Base64 的内容，网络由用户设置启用。摄像头、模型、网络、配额及识别均可用时该路径才启动，其余功能维持运行。完整边界见 隐私说明 与 安全政策。

DLC 与外观自定义

.mohan-outfit 是角色外观容器，可包含服装、发型、头饰、妆容与配件；妆容专用包仍使用同一格式。.mohan-theme 只修改控制台色彩、字体、圆角与可选背景，不修改角色外观。两者都是单一、自包含、无需解压的文件，安装前会完整验证且不执行其中的代码。

安装、选用外观与妆容

1. 下载 .mohan-outfit，并保持扩展名与封装完整。
2. 打开控制中心“云裳阁”，点击“导入服装套件”并选择文件；服装包与妆容包共用该入口、验证、列表与删除流程。
3. 从套件或完整造型列表选取后点击“应用所选服装”；主线妆容菜单提供素颜、淡妆、标准妆、华丽妆与已安装样式，再使用 0–100% 滑块调整整体及眼妆、腮红、唇妆浓度。
4. 要撤销自定义外观，点击“恢复内置服装”；妆容改选内置原妆或素颜。内置蓝白汉服与内置妆容固定保留，且同 id 套件沿用内置版本。

安装与恢复主题

1. 下载 .mohan-theme，并保持封装完整。
2. 在“设置”→“控制台主题”点击“上传单个文件”，选取主题后从列表预览。
3. 点击右下角“保存设置”正式应用；选择“取消”即可恢复原主题。“恢复主题”可预览内置主题，再保存以完成恢复。

容量、数量与兼容性

• 单个外观包最大 1 GiB，解压后总量最大 2 GiB、最多 2,048 个成员；每个成员最大 128 MiB，图片任一边最大 4,096 px。
• 单个主题文件及解压总量最大 16 MiB，每个成员最大 12 MiB，背景任一边最大 4,096 px。
• 云端自创服装默认保留 16 包、总容量 6 GiB、修复待审隔离 5 个；前两项可分别调整为 1–64。达到上限即停止生成，不会自动删除用户导入包。
• 当前二代骨架只接受 mohan-body-v2。为 mohan-body-v1 三姿势制作的一代包采用一代三姿势契约；导入与运行时只接受具备二代 31 个轮廓、锚点与遮挡契约的套件；请使用 tools/build_outfit_pack.py 按二代模板重建，或使用“一键制衣”重新生成。
• 安装在完整验证后进行原子写入；绝对路径、跨目录路径、可执行程序、脚本、符号链接、加密成员、解压炸弹与未声明素材一律拒绝。

完整作者规范见 外观包文档。

支持者 DLC：赤焰剑光

获取、验证与安装

“赤焰剑光”是 Dashboard 的纯装饰性支持者 DLC，不解锁、限制或改变任何功能；墨寒的功能永远免费。请在 Ko-fi 赤焰剑光页面完成支持并下载 flame-sword-theme-dlc.zip。只解压这一层 ZIP，使用 PowerShell 运行 (Get-FileHash .\flame-sword-theme.mohan-theme -Algorithm SHA256).Hash.ToLower()，并与随附的 SHA256SUMS 比对；请勿继续解压 .mohan-theme。

打开 Dashboard，依次前往“系统”→“设置”→“控制台主题”，点击“上传单个文件”并选择 flame-sword-theme.mohan-theme。上传会完成安装，但不会自行启用；在列表中选择“赤焰剑光”即可“主题预览”，点击右下角“保存设置”才会正式应用。点击“取消并保留已保存的值”会恢复此前保存的主题。

如需切回默认主题，点击“还原主题”预览内置主题，再点击“保存设置”。如需移除赤焰剑光，请先切换到其他主题并保存，重新选择赤焰剑光后点击“移除扩展包”，再确认移除；内置主题以及当前使用中或预览中的主题均受保护，不能直接删除。

许可

付费代表赞助支持与抢先获取，不是排他分发权。由 CHOU MING HUA（炎剑文化工作室 Flameblade Studio）拥有的第一方 DLC 内容采用 CC-BY-NC-ND-4.0：合法取得者可以保留许可信息与署名，非商业原样分享；不得商用或分享改作后的内容，也不得暗示官方背书。建议标注：“赤焰剑光 © 2026 CHOU MING HUA（炎剑文化工作室 Flameblade Studio），CC BY-NC-ND 4.0”。第三方项目仍按各自条款执行；完整内容见 DLC-LICENSE.md 与主项目 ASSETS-LICENSE.md。

❤️⚔️ 支持墨寒：Ko-fi 赞助＆装饰 DLC 下载

Ko-fi 赞助完全自愿，不解锁、不限制，也不改变任何功能。付费 DLC 是纯装饰的赞助谢礼，与角色包同样采用 CC BY-NC-ND 4.0，详见上方赤焰剑光说明与 ASSETS-LICENSE.md。

支持墨寒：支持方式与许可证

请使用仓库上方由 GitHub 显示的 Sponsor 按钮，或直接前往 Ko-fi，自由选择单次或每月赞助；是否赞助不影响任何功能。企业部署、合作或顾问需求请通过 GitHub Issues 咨询。

“妾才不是在等赞助……只是在巡视军粮。”

“若真愿意相助，妾会记得的。”

“不许勉强，先照顾好自己的钱包。”

• 作者：CHOU MING HUA；工作室官方英文名为 Flameblade Studio。
• 源代码采用 MIT License；墨寒与林可芸的角色内容（面容、名称、人设、台词与声音）、内置外观、妆容、含角色形象的应用程序图标、docs/media/ 宣传媒体，以及权利人发布的付费 DLC 均采用 CC-BY-NC-ND-4.0，另有非商业粉丝作品许可，名称与商标保留，不在 MIT 许可范围内。
• 素材生产工具与权重只接受 MIT、Apache 2.0、CC0、CC BY（及同等级 BSD）白名单；字体是唯一例外：自 2026-09-02 起允许 SIL OFL 1.1，但仅限字体，不延伸至其他素材；角色资产另依 ASSETS-LICENSE 许可，生产流程纯净规则详见 许可证纯净承诺。
• 素材与第三方条款分别见 ASSETS-LICENSE 与 THIRD-PARTY-NOTICES。

本项目遵循炎剑开源软件家族质量标准。

疑难解答

• Windows SmartScreen 或平台警告：先确认 GitHub Release 来源、SHA256SUMS 与 Artifact Attestation；并保持整体保护开启。
• 对话连接检查：确认自己的 OpenAI API 密钥、Project 权限、配额与网络；API 调用使用独立的 API 配额。
• 没有声音：先切回 Windows 本地女声；Azure Speech 需要用户自己的密钥与匹配区域。
• DLC 被拒绝：确认文件完整、大小、安全 manifest、四语名称与 mohan-body-v2 兼容性；一代包必须重建。
• Preview 集成检查：先使用非重要账号、测试仓库与低风险设备；Microsoft、GitHub、Home Assistant 下一阶段将完成各真实环境验证。

一般问题请到 Issues，使用讨论请到 Discussions，安全问题按 SECURITY 私下报告；规划见 ROADMAP。

技术先行者：抢先采用 Python 3.15

墨寒在 Python 3.15 仍是候选版（3.15.0rc1）时就全面迁移，并大量采用 3.15 新增的延迟加载语法（PEP 810 lazy import），以写法审计工具把关整个代码库。开发过程中，我们发现 3.15 的采样分析工具在特定处理器上错误率偏高，回报为 python/cpython#158552；Python 核心开发者据此修复，修复已收录于 Python 3.15.0 正式版（python/cpython#158845）。墨寒现已运行于 3.15.0 正式版。为稳定起见，JIT 即时编译默认关闭。

开发者入口

请先阅读 架构、测试说明、贡献指南、外观包规范 与 发布政策。Windows 安装包使用工作室维护的 Python 3.15 运行环境；源代码与 CI 采用 PEP 810 延迟导入，文档保持四语同构。README 媒体请按世代来源清单维护。

py -3.15 -m ruff check .
py -3.15 tools/audit_python315_idioms.py
py -3.15 tools/check_four_language_docs.py
$env:QT_QPA_PLATFORM = "offscreen"
py -3.15 tests/run_all.py

Windows 正式打包规范使用 Rust 1.97.1、Maturin 1.14.1 与 PyO3 0.29.2 构建第一方原生模块；Rayon 1.12.0 仅在至少 262,144 pixels 且有多线程时并行合成 RGBA。PyBackedBytes 避免额外输入复制，但输出仍创建新 bytes，性能声明限于已测量的输入零额外复制与现有标量／Rayon 路径。SIMD 加速需先具备专用实现与测量证据。OpenAI Responses API 直接使用标准库 HTTPS，运行时依赖限于标准库路径。

English

繁體中文 · 簡體中文 · English · 日本語

MoHan is a Windows voice-interactive desktop assistant built around safety, privacy, and character continuity.

[Download Windows installer](https://github.com/flameblade-studio/MoHan-PC-Desktop-Assistant/releases) · [Quick Start](QUICKSTART.md) · [Cross-platform capability matrix](docs/CROSS-PLATFORM.md)

Author: CHOU MING HUA · Windows 10/11 complete build · macOS/Linux limited Preview
Latest formal release: v4.6.0 (August 29, 2026). The actual artifacts must still pass this release's final publication gates; Releases lists published application builds; main-branch updates below are marked as awaiting release.

What this is

MoHan is a Windows voice-interactive desktop assistant built around safety, privacy, and character continuity. She combines a transparent 2.5D character, natural speech, user-controlled local long-term memory, tasks, and work tools; in her story, she is a thousand-year-old sword spirit from the Northern Song dynasty who dwells within the Crimson Flame Sword.

Screens and capabilities

Watch the live demonstration. Setup and main screens: first run, voice modes, expressions, tasks and ideas, long-term memory, and security permissions.

• The V5 generation-2 body provides 24 full-body angles, half-body expressions, blinking, speech mouth shapes, and 50 Hz lip sync.
• Robe, hairstyle, hairpiece, and makeup use detachable layers; on main, all 24 Blue-and-White Hanfu views use white flats with blue floral embroidery, with bare, light, classic, and glamorous makeup levels.
• Text, Realtime, Windows local female speech, OpenAI TTS, and optional Azure Speech paths.
• Conversations, editable memory, tasks, ideas, work timers, reminders, and a portable profile.
• Tool execution passes through permissions, risk levels, confirmation, auditing, and emergency stop.
• Google has completed live connection verification; Microsoft, GitHub, and Home Assistant remain experimental Preview integrations.
• Multisensory vision, gestures, remote access, and cloud connectors are off by default and separately revocable.

Four-language support scope

Traditional Chinese, Simplified Chinese, English, and Japanese cover first run, chat, voice, permissions, basic settings, work modes, and reminders. Some advanced pages may still contain Traditional Chinese; actual voices, regions, quotas, and costs for Azure Speech (Preview) depend on the user's own service account.

Three projects and character packs

MoHan retains its name, URL, versions, and users as the installable product. The MIT-licensed 炎劍鑄魂 Soulforge Engine provides general interaction and runtime mechanisms; main has completed the removal of engine dependencies on the MoHan product shell. The MIT-licensed 炎劍畫譜 Flameblade Huapu manages asset inventories, approvals, and exports. Character packs provide persona, dialogue, voice, and appearance.

• MoHan character pack: persona, dialogue, voice, and appearance data for the thousand-year-old sword spirit, published under mohan-pack-v* tags.
• Lin Keyun character pack: MoHan's present-day incarnation, a modern woman who addresses the user as “Swordmaster,” published under lin-keyun-pack-v* tags.

Both packs are separately available from this project's Releases and must be downloaded in addition to the installer. Downloads require no key; size, SHA-256, manifest, and every file are verified before installation.

As of October 21, 2026, the latest published packs are MoHan 1.0.6, Lin Keyun 1.0.4 and the mohan-body-v2 body pack 1.0.0; MoHan 1.0.7 awaits release. Pack and application versions are separate; main-branch updates will be delivered in subsequent releases.

Updates merged into main and awaiting release

Soulforge now supports character packs that depend on a specified body pack: the body supplies body shape, blinking, and mouth shapes, while the character pack supplies hair, clothing, and makeup. A missing matching body produces a clear error. Each view can define its own layer order and use a body hide mask to remove excess base pixels beneath hair and clothing. Soft-edged linear blending protects the face core's expressions and mouth shapes while joining it to the character's appearance. Author contracts and build validation are in Body packs and character layers. Separate body-pack downloads (#296) and MoHan's official long-hair style remain in development.

• Thirteen front expressions include speech and blink states; four makeup levels are more distinct, with separate eye, blush, and lip intensity controls.
• Drag or use arrow keys to rotate the Wardrobe Pavilion preview through 24 views; Home returns to the front. Outfit and makeup changes retain the current angle.
• The control center uses larger text, the desktop status card remembers its collapsed state, and external themes also color selected states.
• Lunch and dinner reminders store delivery, response, and postponement separately. Four-language task intent recognition is corrected; revoking folder or OAuth access immediately prevents stale work from continuing to use it.

MoHan's Tsundere Developer Theatre

These six half-body expressions are fixed assets composed through the formal runtime path from the generation-2 body, official Blue-and-White Hanfu, and built-in classic makeup.

“I was waiting for your Star and checking morale.”	“The logic is acceptable. Add tests, and I may permit it onto main.”	“You brought a PR? I-I am only recording your contribution.”
“Bring me a tested merge. Then you earn a gentle tap.”	“All green... well done. I merely respect sound engineering.”	“The bug can wait until tomorrow. Who guards the sword if you collapse?”

Strategist review Checking whether the code deserves main.

When praised Acceptable. Stop staring.

Dangerous action No confirmation? First pass my blade.

Provisions received I shall remember this kindness.

Install and update

1. Download the installer ending in Windows-x64-Setup.exe from GitHub Releases; advanced users may choose the complete Windows-x64.zip or MSI.
2. Before installation, verify SHA256SUMS and the GitHub Artifact Attestation. Stop if the source, filename, or digest differs; keep system-wide protection enabled.
3. Start the installer, or fully extract the ZIP and keep the EXE, internal folders, and assets together. Updating preserves local personal data.
4. The built-in updater first verifies the update manifest's detached Ed25519 .sig signature with its pinned public key, then checks declared size and SHA-256. The downloaded file starts only after its signature, size, and digest all validate.

The macOS/Linux Preview currently offers a limited feature set; each Release states its platform-store signing and notarization status. Obtain it only from this project's Release and complete the source checks above. See Preview packages.

Three things to do first

1. In the first-run wizard, review interface language, assistant name, the user's title, organization, work type, and wake word; existing settings are preserved.
2. Try a Windows local female voice first. When cloud AI is needed, enter a user-owned OpenAI API key in Settings. API usage has its own separately billed quota.
3. Review microphone, notification, and tool permissions and enable only the connectors you need. First learn the Esc emergency stop and the phrase “mohan stop.”

Cloud connector setup

Google OAuth

Before using Gmail, Google Calendar, and Google Drive, complete these steps:

1. In a user-owned Google Cloud project, enable the Gmail API, Google Calendar API, and Google Drive API.
2. Configure the OAuth consent screen; while the application is in testing, add the user's Google account as a test user.
3. Create an OAuth Client ID for a Desktop application.
4. Open MoHan Settings → Flagship control center → Cloud Connectors, select Google（Gmail／Calendar／Drive）, and enter the OAuth Client ID; enter the OAuth Client Secret only if the provider supplies one.
5. Keep the default scopes below in OAuth scopes, press Open secure browser connection, complete browser authorization, and then press Test selected service.

The application requests these Google scopes by default:

openid
email
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/drive.metadata.readonly

A public OAuth application using sensitive scopes may require additional Google verification; each user may instead create a personal Desktop OAuth application.

Microsoft, GitHub, and Home Assistant

• Microsoft defaults: openid, offline_access, User.Read, Mail.ReadWrite, Mail.Send, Calendars.ReadWrite, and Files.ReadWrite.
• GitHub defaults: read:user and repo.
• Home Assistant: first create a Long-Lived Access Token in the user's own Home Assistant profile; in MoHan Settings → Flagship control center → Smart Home, check Enable Home Assistant integration, enter the Home Assistant address and Long-lived access token, confirm Verify HTTPS certificate, press Save settings, then use Test connection or Load devices to confirm.

These three are Preview integrations with established architecture and safety boundaries; the next validation stage covers real-environment end-to-end flows. Begin with test accounts and low-risk devices; supported remote connectivity uses Home Assistant Cloud, Tailscale, or another authenticated encrypted private network.

Privacy and local-first behavior

• On Windows, conversations, memories, tasks, settings, work records, permissions, and audits stay by default in %LOCALAPPDATA%\YanJianStudio\MoHan; backups are in its backups subfolder, and portable data uses one .mohan-profile.
• Only when the user enables a relevant feature does the text, audio, or tool-planning context needed for that request go to OpenAI. OAuth services receive only user-consented API requests; Home Assistant receives local device requests.
• API keys and OAuth/Home Assistant tokens are stored separately with Windows DPAPI and remain in their separate DPAPI files. SQLite, source code, logs, ordinary portable files, and ChatGPT account history are outside the assistant's data scope.
• Camera, remote access, and cloud connectors are enabled explicitly by the user. Raw camera frames remain transient and are released after processing; each path activates only after permission and service checks pass.

Multisensory vision is enabled explicitly by the user. After the user explicitly enables it and confirms it by globally saving the settings, that choice is continuous authorization until the user turns it off; the authorization continues across subsequent frames. The authorization status stays visible, with immediate revocation, cost limits, and a way to cancel unfinished analysis. Local OpenCV handles ongoing sensing; only at low frequency or on an event trigger is a temporary image sent to GPT-5.6. Originals remain transient and are released after processing, logs contain content from which Base64 has been removed, and network access follows the user's setting. The path activates when camera, model, network, quota, and recognition are available; other features remain operational. Read Privacy and Security for the complete boundary.

DLC and appearance customization

.mohan-outfit is the character-appearance container and may include garments, hairstyles, headwear, makeup, and accessories; a makeup-only pack uses the same format. .mohan-theme changes only control-panel colors, font, corner radius, and an optional background, while preserving the character's appearance. Both are single, self-contained files that remain packaged for direct import, are fully validated before installation, and contain declarative assets only.

Install and select outfits or makeup

1. Download the .mohan-outfit; keep its filename and package intact.
2. Open the control center's Wardrobe Pavilion, press “Import outfit package,” and choose the file. Outfit and makeup packs share this entry point, validation, catalog, and removal flow.
3. Choose a package or complete look and press “Apply selected outfit.” On main, the makeup menu offers bare face, light, classic, glamorous, and installed styles; use the 0–100% sliders for overall, eye, blush, and lip intensity.
4. To undo appearance customization, press “Restore built-in outfit”; choose built-in classic makeup or bare face for makeup. The built-in Blue-and-White Hanfu and makeup remain fixed and take precedence by a package with the same id.

Install and restore themes

1. Download the .mohan-theme; keep the package intact.
2. In Settings → Dashboard theme, press “Upload one file,” choose the theme, and preview it from the list.
3. It takes effect only after “Save settings” at the lower right; cancel restores the previous theme. “Restore theme” previews the built-in theme, which is restored after saving.

Capacity, count, and compatibility

• One appearance pack is limited to 1 GiB, 2 GiB expanded, and 2,048 members; each member is limited to 128 MiB and each image edge to 4,096 px.
• One theme and its expanded contents are limited to 16 MiB; each member is limited to 12 MiB and each background edge to 4,096 px.
• Cloud-created outfits retain 16 packs, 6 GiB total, and 5 repair-review quarantine entries by default; the first two settings each allow 1–64. Generation stops at the limit and preserves every user-imported pack.
• The current generation-2 rig accepts only mohan-body-v2. A generation-1 pack for the three-pose mohan-body-v1 lacks the 31 silhouettes, anchors, and occlusion contract, so import and runtime both reject it. Rebuild against the generation-2 template with tools/build_outfit_pack.py, or regenerate it through one-click outfit creation.
• Installation is atomic after full validation. Absolute or traversing paths, executables, scripts, symlinks, encrypted members, decompression bombs, and undeclared assets are rejected.

See the outfit-pack documentation for the complete authoring contract.

Supporter DLC: Flame Sword Radiance

Download, verify, and install

“Flame Sword Radiance” is a purely cosmetic Dashboard DLC for supporters. It unlocks, restricts, or changes no feature; MoHan's functionality remains free forever. Support the project on the Ko-fi Flame Sword Radiance page and download flame-sword-theme-dlc.zip. Extract only this outer ZIP. In PowerShell, run (Get-FileHash .\flame-sword-theme.mohan-theme -Algorithm SHA256).Hash.ToLower() and compare it with the enclosed SHA256SUMS; do not unpack the .mohan-theme file.

Open the Dashboard and go to “System” → “Settings” → “Dashboard theme”. Select “Upload one file” and choose flame-sword-theme.mohan-theme. Uploading installs the theme but does not activate it. Select “Flame Sword Radiance” in the list for “Theme preview”, then select “Save settings” at the lower right to apply it. “Cancel and keep the saved values” restores the previously saved theme.

To return to the default, select “Restore theme” to preview the built-in theme, then select “Save settings”. To remove Flame Sword Radiance, first switch to another theme and save; select Flame Sword Radiance again, choose “Remove add-on”, and confirm. The built-in theme and any active or previewed theme are protected from direct removal.

License

Payment represents sponsorship and early access, not an exclusive distribution right. First-party DLC content owned by CHOU MING HUA (炎劍文化工作室 Flameblade Studio) uses CC-BY-NC-ND-4.0: lawful recipients may share it unchanged and non-commercially while preserving the license information and attribution. Commercial use and distribution of adapted material are not permitted, and official endorsement may not be implied. Suggested credit: “Flame Sword Radiance © 2026 CHOU MING HUA (炎劍文化工作室 Flameblade Studio), CC BY-NC-ND 4.0.” Third-party items remain under their own terms; see DLC-LICENSE.md and the main project's ASSETS-LICENSE.md for the complete notices.

❤️⚔️ Support MoHan: Ko-fi sponsorship & cosmetic DLC downloads

Ko-fi contributions are entirely voluntary: they unlock, restrict, and change no features. Paid DLC is a purely cosmetic thank-you for supporters and, like the character packs, uses CC BY-NC-ND 4.0; see the Flame Sword Radiance section above and ASSETS-LICENSE.md.

Support MoHan: support and licensing

Use the Sponsor button displayed by GitHub above this repository, or visit Ko-fi for an optional one-time or monthly contribution; contributing does not affect any feature. For enterprise adoption, partnerships, or consulting, contact Flameblade Studio through GitHub Issues.

“I welcome your support while inspecting provisions.”

“If you truly wish to help, I shall remember.”

“Care for your own purse first and support within your means.”

• Author: CHOU MING HUA; the studio's official English name is Flameblade Studio.
• Source code uses the MIT License. MoHan and Lin Keyun character content (faces, names, personas, dialogue, and voices), built-in appearances, makeup, application icons depicting a character, promotional media under docs/media/, and paid DLC published by the rights holder all use CC-BY-NC-ND-4.0. A separate non-commercial fan-work permission applies; names and trademarks are reserved, and these materials remain outside the MIT grant.
• Asset-production tools and weights admit only the MIT, Apache 2.0, CC0, CC BY (and equivalent BSD-class) allowlist. Fonts are the sole exception: since 2026-09-02, SIL OFL 1.1 is allowed for fonts only and applies exclusively to fonts. Character assets are licensed separately in ASSETS-LICENSE; see the License Purity Commitment for production-pipeline purity rules.
• Asset and third-party terms are in ASSETS-LICENSE and THIRD-PARTY-NOTICES.

This project follows the Flameblade Open Source Software Family Quality Standard.

Troubleshooting

• Windows SmartScreen or a platform warning: verify the GitHub Release source, SHA256SUMS, and Artifact Attestation first; keep system-wide protection enabled.
• Conversation connection check: check your OpenAI API key, Project permission, quota, and network. API calls use separate API quota.
• No sound: switch to a Windows local female voice first. Azure Speech requires the user's own key and matching region.
• DLC rejected: check file integrity, size, safe manifest, four-language names, and mohan-body-v2 compatibility. A generation-1 pack must be rebuilt.
• Preview integration check: begin with a non-critical account, test repository, or low-risk device. Microsoft, GitHub, and Home Assistant will complete each real-environment validation in the next stage.

Use Issues for ordinary problems, Discussions for usage, and SECURITY for private security reports; plans are in the ROADMAP.

Early adopter: Python 3.15 ahead of release

MoHan moved entirely to Python 3.15 while it was still a release candidate (3.15.0rc1) and adopted the new lazy-import syntax (PEP 810 lazy import) across the codebase, enforced by an idiom audit. Along the way we found a high error rate in 3.15's sampling profiler on certain processors and reported it as python/cpython#158552; the CPython core developers fixed it, and the fix ships in the Python 3.15.0 final release (python/cpython#158845). MoHan now runs on 3.15.0. For stability, the JIT is off by default.

Developer entry points

Start with Architecture, Testing, Contributing, the outfit-pack specification, and Publishing policy. The Windows installer uses the studio-maintained Python 3.15 runtime; source and CI use PEP 810 lazy imports, and documentation stays structurally complete in all four languages. Maintain README media through the generation provenance ledger.

py -3.15 -m ruff check .
py -3.15 tools/audit_python315_idioms.py
py -3.15 tools/check_four_language_docs.py
$env:QT_QPA_PLATFORM = "offscreen"
py -3.15 tests/run_all.py

The formal Windows packaging contract builds its first-party native module with Rust 1.97.1, Maturin 1.14.1, and PyO3 0.29.2. Rayon 1.12.0 parallelizes RGBA composition only at 262,144 pixels or above with multiple workers. PyBackedBytes avoids an extra input copy, while output creates new bytes; performance claims are limited to measured zero-extra-input-copy behavior and the implemented scalar/Rayon paths. SIMD acceleration requires a dedicated implementation and measurement evidence. The OpenAI Responses API uses standard-library HTTPS directly, keeping runtime dependencies on the standard-library path.

日本語

繁體中文 · 簡體中文 · English · 日本語

墨寒は、安全性、プライバシー、キャラクターの連続性を重視する Windows 音声対話型デスクトップアシスタントです。

[Windows インストーラーをダウンロード](https://github.com/flameblade-studio/MoHan-PC-Desktop-Assistant/releases) · [クイックスタート](QUICKSTART.md) · [クロスプラットフォーム機能表](docs/CROSS-PLATFORM.md)

作者：CHOU MING HUA · Windows 10/11 完全版 · macOS／Linux 機能限定 Preview
最新正式リリース： v4.6.0（2026 年 8 月 29 日）。実際の成果物は本版の最終公開ゲートに合格する必要があります。公開済みアプリは Releases で確認できます。以下の main ブランチの更新は、公開待ちとして区別しています。

これは何か

墨寒は、安全性、プライバシー、キャラクターの連続性を重視する Windows 音声対話型デスクトップアシスタントです。透明な 2.5D キャラクター、自然な音声、利用者が管理するローカル長期記憶、タスク、作業ツールを統合しています。物語上は北宋から来た、赤焰剣に宿る千年の女剣魂です。

画面と機能の一覧

実機デモを見る。設定と主な画面：初回設定、音声モード、表情、タスクとアイデア、長期記憶、安全権限。

• V5 第二世代素体は、全身 24 方向、半身表情、まばたき、発話時の口形、50 Hz リップシンクに対応します。
• 外衣、髪型、髪飾り、メイクは着脱可能なレイヤーです。main では藍白漢服の全 24 視点の靴を白地に青い花の刺繍があるフラットシューズに統一し、メイクは素顔・ナチュラル・クラシック・華やかの 4 段階を用意しています。
• テキスト、Realtime、Windows 本機女性音声、OpenAI TTS、任意の Azure Speech 経路。
• 会話、編集可能な記憶、タスク、アイデア、作業タイマー、リマインダー、可搬プロファイル。
• ツール実行は権限、危険度、確認、監査、緊急停止を通過します。
• Google は実接続検証済みです。Microsoft、GitHub、Home Assistant は実験的 Preview のままです。
• マルチセンサー視覚、ジェスチャー、遠隔アクセス、クラウド連携はユーザーが個別に有効化し、いつでも管理できます。

日本語の対応範囲

繁体字中国語、簡体字中国語、英語、日本語は、初回設定、会話、音声、権限、基本設定、作業モード、リマインダーに対応します。高度な画面には繁体字中国語が残る場合があります。Azure Speech（プレビュー）の実際の音声、リージョン、割り当て、費用は、利用者自身のサービスアカウントに依存します。

三つのプロジェクトとキャラクターパック

墨寒は、従来の名称、URL、バージョン、利用者を引き継ぐインストール可能な製品です。MIT ライセンスの 炎劍鑄魂 Soulforge Engine は汎用の対話・実行機構を担当し、main では墨寒の製品シェルへのエンジン依存の解消が完了しています。MIT ライセンスの 炎劍畫譜 Flameblade Huapu は素材目録・承認・書き出しを担当します。人物設定・台詞・音声・外観はキャラクターパックが提供します。

• 墨寒キャラクターパック：千年の女剣魂である墨寒の人物設定、台詞、音声、外観データを収録し、mohan-pack-v* タグで公開します。
• 林可芸キャラクターパック：墨寒の現世の姿にあたる現代女性で、利用者を「剣主」と呼びます。lin-keyun-pack-v* タグで公開します。

両パックは本プロジェクトの Releases から個別に取得します。インストーラーには同梱されないため、別途ダウンロードしてください。取得にキーは不要で、導入前にサイズ、SHA-256、manifest、全ファイルの内容を検証します。

2026 年 10 月 21 日時点の最新公開済みパックは墨寒 1.0.6、林可芸 1.0.4、素体パック mohan-body-v2 1.0.0 です。墨寒 1.0.7 は公開待ちです。パックとアプリのバージョンは別で、main の更新は今後のリリースで提供されます。

main に統合済み・公開待ちの更新

炎剣鋳魂エンジンは、指定した素体パックに依存するキャラクターパックに対応しました。素体が体形・まばたき・口形を、キャラクターパックが髪型・衣装・メイクを提供し、対応する素体が不足すると明確なエラーを表示します。視点ごとにレイヤーの前後関係を設定し、素体非表示マスクで髪や衣装の下に余分に残る素体部分を除去できます。顔の中心部分は境界をぼかした線形合成で表情と口形を保ち、キャラクターの外観へ自然につなぎます。作者向け仕様とビルド検証は 素体パックとキャラクターレイヤー を参照してください。素体パックの別途ダウンロード（#296）と墨寒の公式ロングヘアは開発中です。

• 正面 13 組の表情は発話・まばたき状態を含みます。4 段階のメイクの差が明確になり、アイメイク・チーク・リップの濃さを個別に調整できます。
• 雲裳閣のプレビューはドラッグまたは矢印キーで 24 方向に回転し、Home で正面に戻ります。衣装やメイクを変えても現在の角度を維持します。
• コントロールセンターの文字を拡大し、デスクトップ状態カードの折りたたみ設定を保存します。外部テーマの色は選択状態にも適用されます。
• 昼食・夕食の通知は送達・応答・延期を個別に保存します。四言語の自然言語によるタスク判定を修正し、フォルダーや OAuth の許可を取り消すと古い処理による権限の継続利用を直ちに止めます。

墨寒のツンデレ開発小劇場

六枚の半身表情は、第二世代素体、公式の藍白漢服、内蔵の基本メイクを正式な実行時経路で合成した固定素材です。

「Star を待ちながら、士気も確認していました。」	「このロジックは良いですね。テストを足せば main 入りを許しましょう。」	「PR を送るのですか？　功績を記録するだけです。」
「テストなしでマージ？　手を出しなさい。一度だけです。」	「すべて緑……よくできました。良い設計を尊重しただけです。」	「Bug は明日でも直せます。倒れたら誰が剣を守るのですか？」

策士の審査 main に入れる品質か確認します。

褒められた時 良い出来です。視線はほどほどに。

危険操作 未確認なら、この剣を越えてから。

兵糧を受領 この気持ちは覚えておきます。

インストールと更新

1. GitHub Releases から、末尾が Windows-x64-Setup.exe のインストーラーを取得します。上級者は完全な Windows-x64.zip または MSI も選べます。
2. インストール前に SHA256SUMS と GitHub Artifact Attestation を検証します。配布元、ファイル名、ハッシュが異なる場合は停止し、システム全体の保護を有効なまま維持してください。
3. インストーラーを起動するか、ZIP を完全展開して EXE、内部フォルダー、assets を同じ場所に保ちます。更新でローカル個人データは削除されません。
4. 内蔵アップデーターは、埋め込み公開鍵で更新マニフェストの Ed25519 分離 .sig 署名を検証し、次に宣言サイズと SHA-256 を照合します。ダウンロードしたファイルは、署名、サイズ、ハッシュがすべて検証された後に起動します。

macOS／Linux Preview は 現在は機能限定版で、プラットフォームストア署名と公証の状態は各 Release に明記します。本プロジェクトの Release だけから取得し、上記の配布元検証を完了してください。Preview パッケージ説明も参照してください。

最初に行う三つのこと

1. 初回設定で、画面言語、アシスタント名、利用者の呼び名、組織、作業内容、ウェイクワードを確認します。既存設定は上書きしません。
2. まず Windows 本機女性音声を試します。クラウド AI が必要な場合だけ、利用者自身の OpenAI API キーを設定に入力します。ChatGPT の契約に API 割り当ては含まれません。
3. マイク、通知、ツール権限を確認し、必要な連携だけを有効にします。先に Esc の緊急停止と「墨寒、止まって」を覚えてください。

クラウド連携の設定

Google OAuth

Gmail、Google Calendar、Google Drive を利用する前に、次を完了してください。

1. 利用者自身の Google Cloud プロジェクトで Gmail API、Google Calendar API、Google Drive API を有効にします。
2. OAuth 同意画面を設定します。アプリケーションがテスト中の間は、自分の Google アカウントをテストユーザーに追加します。
3. Desktop アプリケーション用の OAuth Client ID を作成します。
4. 墨寒の「設定」→「フラッグシップ操作センター」→「クラウド接続」を開き、Google（Gmail／Calendar／Drive）を選んで OAuth Client ID を入力します。OAuth Client Secret は、サービスから発行された場合だけ入力します。
5. 「認可スコープ」に以下の既定値を残し、「ブラウザーで安全に接続」を押してブラウザー認可を完了し、「選択したサービスをテスト」を押します。

アプリケーションが既定で要求する Google scopes：

openid
email
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/drive.metadata.readonly

機密 scopes を使う公開 OAuth アプリケーションは、Google の追加検証が必要になる場合があります。各利用者が個人用 Desktop OAuth アプリケーションを作ることもできます。

Microsoft、GitHub、Home Assistant

• Microsoft の既定 scopes：openid、offline_access、User.Read、Mail.ReadWrite、Mail.Send、Calendars.ReadWrite、Files.ReadWrite。
• GitHub の既定 scopes：read:user、repo。
• Home Assistant：まず自分の Home Assistant プロフィールで Long-Lived Access Token を作成します。墨寒の「設定」→「フラッグシップ操作センター」→「スマートホーム」で「Home Assistant 連携を有効化」をチェックし、「Home Assistant アドレス」と「長期アクセストークン」を入力します。「HTTPS 証明書を検証」を確認して「設定を保存」を押し、「接続をテスト」または「機器を読み取る」で確認します。

この三つはアーキテクチャと安全境界を実装済みの Preview 連携で、次の検証段階は実環境のエンドツーエンドフローです。テスト用アカウントと低リスク機器から始め、リモート接続はプライベートネットワークの範囲で使用してください。Home Assistant Cloud、Tailscale、または認証付き暗号化プライベートネットワークを利用してください。

プライバシーとローカル優先

• Windows では、会話、記憶、タスク、設定、作業記録、権限、監査を既定で %LOCALAPPDATA%\YanJianStudio\MoHan に保存します。バックアップは backups サブフォルダーにあり、可搬データには単一の .mohan-profile を使います。
• 利用者が関連機能を有効にした場合だけ、その要求に必要なテキスト、音声、ツール計画を OpenAI へ送ります。OAuth サービスは利用者が同意した API 要求だけを受け取り、Home Assistant はローカル機器要求を受け取ります。
• API キーと OAuth／Home Assistant トークンは Windows DPAPI で分離保存し、SQLite、ソースコード、ログ、通常の可搬ファイルは対象外で、機密は個別の DPAPI ファイルに限定されます。ChatGPT アカウント履歴もアシスタントのデータ範囲外です。
• カメラ、遠隔アクセス、クラウド連携はユーザーが明示的に有効化します。元のカメラフレームは一時的に処理後解放し、各経路は権限とサービスの検査通過後に有効化します。

マルチセンサー視覚はユーザーが明示的に有効化します。利用者がコントロールセンターで有効化して全体設定を保存すると、その許可は後続フレームにも継続して適用されます。許可状態は常に表示し、直ちに取り消せるほか、費用の上限を設定して進行中の解析を終了できます。端末内の OpenCV が継続検知を担当し、低頻度またはイベント発生時だけ一時画像を GPT-5.6 へ送ります。元画像は一時的に処理後解放し、ログは Base64 を除去した内容に限定し、ネットワークは利用者設定に従って有効化します。カメラ、モデル、ネットワーク、割り当て、認識が揃った場合に該当経路を有効化し、他の機能は継続して動作します。完全な境界は プライバシー と セキュリティ を参照してください。

DLC と外観のカスタマイズ

.mohan-outfit はキャラクター外観のコンテナーで、衣装、髪型、髪飾り、メイク、アクセサリーを収録できます。メイク専用パックも同じ形式です。.mohan-theme はコントロールパネルの色、フォント、角丸、任意の背景だけを変更し、キャラクター外観を維持します。どちらも単一で自己完結し、そのままインポートできます。導入前に全体を検証し、宣言型アセットだけを含みます。

衣装とメイクの導入・選択

1. .mohan-outfit をダウンロードし、拡張子を変えたり解凍したりしないでください。
2. コントロールセンターの「雲裳閣」を開き、「衣装パッケージをインポート」でファイルを選びます。衣装とメイクは同じ入口、検証、一覧、削除経路を使います。
3. パッケージまたは一式を選び、「選択した衣装を適用」を押します。main のメイクメニューは素顔・ナチュラル・クラシック・華やか・導入済みスタイルに対応し、0–100% スライダーで全体・アイメイク・チーク・リップの濃さを調整できます。
4. カスタム外観を取り消すには「内蔵衣装に戻す」を押し、メイクは内蔵の基本メイクまたはすっぴんを選びます。内蔵の藍白漢服とメイクは削除できず、同じ id のパッケージで置き換えられません。

テーマの導入と復元

1. .mohan-theme をダウンロードし、解凍しないでください。
2. 「設定」→「コントロールセンターのテーマ」で「ファイルを1つアップロード」を押し、テーマを選んで一覧からプレビューします。
3. 右下の「設定を保存」を押した時だけ反映され、取り消すと元のテーマへ戻ります。「テーマを元に戻す」で内蔵テーマをプレビューし、保存すると復元が完了します。

容量・数量・互換性

• 外観パック一件は最大 1 GiB、展開後最大 2 GiB、最大 2,048 メンバーです。各メンバーは最大 128 MiB、画像の各辺は最大 4,096 px です。
• テーマ一件と展開後の合計は最大 16 MiB、各メンバーは最大 12 MiB、背景の各辺は最大 4,096 px です。
• クラウド自作衣装は既定で 16 パック、合計 6 GiB、修復審査用隔離 5 件を保持します。前二項はそれぞれ 1–64 に設定できます。上限では生成を停止し、利用者がインポートしたパックを自動削除しません。
• 現行の第二世代 rig は mohan-body-v2 だけを受理します。三姿勢の mohan-body-v1 用第一世代パックには 31 silhouette、anchor、occlusion 契約を採用しています。インポート時と実行時は第二世代契約を満たすパックだけを受理します。tools/build_outfit_pack.py で第二世代テンプレートに対して再構築するか、「ワンクリック衣装生成」で作り直してください。
• 導入は完全検証後にアトミックに行います。絶対／横断パス、実行ファイル、スクリプト、シンボリックリンク、暗号化メンバー、解凍爆弾、宣言済み素材だけを受理します。

完全な制作契約は 外観パック文書 を参照してください。

支援者 DLC：赤焔剣光

入手、検証、インストール

「赤焔剣光」は支援者向けの純粋な装飾用 Dashboard DLC です。機能の解放、制限、変更には一切関係せず、墨寒の機能は今後もすべて無料です。Ko-fi の赤焔剣光ページで支援し、flame-sword-theme-dlc.zip をダウンロードしてください。この外側の ZIP だけを展開します。PowerShell で (Get-FileHash .\flame-sword-theme.mohan-theme -Algorithm SHA256).Hash.ToLower() を実行し、同梱の SHA256SUMS と照合してください。.mohan-theme 自体は展開しないでください。

Dashboard を開き、「システム」→「設定」→「コントロールセンターのテーマ」へ進み、「ファイルを1つアップロード」で flame-sword-theme.mohan-theme を選びます。アップロードによりインストールされますが、自動的には有効になりません。一覧で「赤焔剣光」を選ぶと「テーマプレビュー」になり、右下の「設定を保存」で正式に適用します。「保存済みの値を保ったまま取り消す」を選ぶと、以前に保存したテーマへ戻ります。

既定へ戻す場合は「テーマを元に戻す」で内蔵テーマをプレビューし、「設定を保存」を選びます。赤焔剣光を削除する場合は、先に別のテーマへ切り替えて保存してから、赤焔剣光を再び選び、「追加パッケージを削除」で確認します。内蔵テーマ、および使用中・プレビュー中のテーマは保護され、直接削除できません。

ライセンス

支払いは支援と先行入手を意味し、排他的な配布権ではありません。CHOU MING HUA（炎劍文化工作室 Flameblade Studio）が所有する第一者 DLC 内容には CC-BY-NC-ND-4.0 を適用します。適法な取得者はライセンス情報と表示を保持し、非営利かつ無改変で共有できます。商用利用および改変物の配布はできず、公式の推奨・承認を示唆してはなりません。推奨表示：「赤焔剣光 © 2026 CHOU MING HUA（炎劍文化工作室 Flameblade Studio）、CC BY-NC-ND 4.0」。第三者項目には各自の条項が適用されます。完全な通知は DLC-LICENSE.md と本体プロジェクトの ASSETS-LICENSE.md を参照してください。

❤️⚔️ 墨寒を支援：Ko-fi スポンサー＆装飾 DLC ダウンロード

Ko-fi での支援はあくまで任意であり、機能の解放、制限、変更には一切関係しません。有料 DLC は支援への純粋な装飾的お礼で、キャラクターパックと同じく CC BY-NC-ND 4.0 です。詳しくは上の赤焔剣光の説明と ASSETS-LICENSE.md をご覧ください。

墨寒を応援：支援方法とライセンス

このリポジトリ上部に GitHub が表示する Sponsor ボタンをご利用いただくか、Ko-fi で一度限りまたは毎月の支援を自由に選べます。支援の有無で機能が変わることはありません。企業導入、協業、コンサルティングのご相談は GitHub Issues からお寄せください。

「支援を待ってなどいません。兵糧を巡回しているだけです。」

「本当に助けてくださるなら、覚えておきます。」

「まず自分のお財布を守り、無理のない範囲で応援してください。」

• 作者：CHOU MING HUA。スタジオの正式な英語名は Flameblade Studio です。
• ソースコードには MIT License を適用します。墨寒と林可芸のキャラクター内容（顔、名称、人物設定、台詞、音声）、内蔵外観、メイク、キャラクター像を含むアプリケーションアイコン、docs/media/ の宣伝用メディア、権利者が公開する有料 DLC には CC-BY-NC-ND-4.0 を適用します。非営利ファン作品には別途の許可があり、名称と商標は留保され、これらの素材は MIT の許諾範囲外です。
• 素材生成の道具と重みは MIT、Apache 2.0、CC0、CC BY（および同等の BSD 系）ホワイトリストだけを受理します。フォントが唯一の例外で、2026-09-02 以降は SIL OFL 1.1 をフォントに限って認め、他の素材には拡張しません。キャラクター資産は ASSETS-LICENSE で別途許諾され、生成工程の純浄性規則は ライセンス純浄性の約束 に記載します。
• 素材と第三者条項は ASSETS-LICENSE と THIRD-PARTY-NOTICES に記載しています。

本プロジェクトは 炎剣オープンソース・ソフトウェア・ファミリー品質基準 に従います。

トラブルシューティング

• Windows SmartScreen またはプラットフォーム警告：GitHub Release の配布元、SHA256SUMS、Artifact Attestation を先に確認し、システム全体の保護を有効なまま維持してください。
• 会話が返らない：利用者自身の OpenAI API キー、Project 権限、割り当て、ネットワークを確認してください。ChatGPT 契約は API 割り当ての代わりになりません。
• 音が出ない：まず Windows 本機女性音声へ戻してください。Azure Speech には利用者自身のキーと対応リージョンが必要です。
• DLC の受理条件：ファイルの完全性、容量、安全な manifest、四言語名、mohan-body-v2 互換性を確認してください。第一世代パックは再構築が必要です。
• Preview 連携の確認：重要でないアカウント、テスト用リポジトリ、低リスク機器から始めてください。Microsoft、GitHub、Home Assistant は全実環境での検証は次の段階で完了します。

一般的な問題は Issues、利用相談は Discussions、セキュリティ問題は SECURITY から非公開で報告してください。計画は ROADMAP にあります。

技術の先駆け：Python 3.15 をいち早く採用

墨寒は Python 3.15 がまだリリース候補版（3.15.0rc1）だった段階で全面的に移行し、3.15 で追加された遅延インポート構文（PEP 810 の lazy import）をコードベース全体で採用して、書き方監査ツールで品質を守っています。開発中、3.15 のサンプリングプロファイラーが特定のプロセッサーで高いエラー率を示すことを見つけ、python/cpython#158552 として報告しました。CPython のコア開発者がこれを修正し、その修正は Python 3.15.0 正式版に収録されています（python/cpython#158845）。墨寒は現在 3.15.0 正式版で動作しています。安定性を優先し、JIT は既定で無効です。

開発者向け入口

最初に アーキテクチャ、テスト説明、貢献ガイド、外観パック仕様、公開方針 をお読みください。Windows インストーラーは、スタジオ管理の Python 3.15 実行環境を使用します。ソースと CI は PEP 810 遅延インポートを採用し、文書は四言語で同じ構造を維持します。README のメディアは世代プロヴェナンス台帳で管理してください。

py -3.15 -m ruff check .
py -3.15 tools/audit_python315_idioms.py
py -3.15 tools/check_four_language_docs.py
$env:QT_QPA_PLATFORM = "offscreen"
py -3.15 tests/run_all.py

Windows 正式パッケージ化の契約では、Rust 1.97.1、Maturin 1.14.1、PyO3 0.29.2 で第一者ネイティブモジュールを構築します。Rayon 1.12.0 は 262,144 pixels 以上かつ複数ワーカーがある場合だけ RGBA 合成を並列化します。PyBackedBytes は余分な入力コピーを避けますが、出力は新しい bytes を生成するため、性能表明は測定済みの入力ゼロ追加コピーと既存の scalar／Rayon 経路に限定します。SIMD 高速化には専用の実装と測定結果が必要です。OpenAI Responses API は標準ライブラリ HTTPS を直接使い、実行時依存は標準ライブラリ経路に限定します。