yi-ge · Oct 11, 2026 · Oct 11, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -13,7 +13,7 @@ PR 合并到 `main` 或推送到 `main` 后会自动部署。用户要求部署
 - 已有明确生效版本时保留真实版本号；无法确定生效版本时统一使用 `v10.0.178+`。不要把已明确的版本改成默认值，例如长期指令保留 `v10.0.179+`。
 - 提示框放在对应页面或章节的开头附近，注明具体功能范围。只约束某一功能时，不要写成整页功能都受该版本限制。提示框独立成块，不嵌入正文段落或其他提示框。
 - 两种语言原文都已有同一功能的版本约束时，标注的版本和功能范围应一致；不要仅为对齐格式而向原文无版本约束的译文新增标注。
-- 保留开发状态、安装包可用性、平台、权限和供应商授权等既有条件。生效版本标注不代表安装包已经公开发行，也不代表功能自动获得授权。
+- 生效版本直接说明用户需要的客户端版本。不要附加“开发分支已实现”“实际可用以安装包为准”“确认安装包包含该能力”等无法由普通用户判断的内部说明。保留确实影响使用的平台、权限和供应商授权条件，并写成用户能判断或操作的要求；尚未开放的功能直接说明暂不可用。
 - 更新日志、未实现的规划、操作系统或运行时要求、协议修订号、配置版本及示例内容版本保留各自的含义和编号，不改写成客户端生效版本。
 
 中文格式：
@@ -33,3 +33,10 @@ PR 合并到 `main` 或推送到 `main` 后会自动部署。用户要求部署
 ```
 
 README.md 的贡献说明维护同一规范，修改时保持两处一致。
+
+## 面向普通用户的写作规范
+
+- 优先说明功能能做什么、在哪里使用、需要什么条件、遇到问题怎么办。
+- 不把开发分支、代码合入、源码配置快照、内部发布门控、组件迁移计划等开发细节作为使用说明，也不要要求用户检查这些细节。
+- 将实现状态说明改成明确的生效版本、当前支持范围或可见的操作步骤；组件名称和技术细节仅在帮助用户配置、排查问题或理解权限与许可时保留。
+- 避免把写给文档作者的告诫放进用户正文。中英文按同一原则修订，保留真实的功能限制和授权条件。
diff --git a/README.md b/README.md
@@ -100,7 +100,7 @@ Follow the same convention as [AGENTS.md](./AGENTS.md) when writing or revising
 - Keep a documented introduction version. When the effective version is uncertain, use `v10.0.178+`. Do not replace a known version with the default; standing instructions retain `v10.0.179+`.
 - Place the callout near the beginning of the relevant page or section and name the affected feature. A constraint on one feature must not imply that every feature on the page requires that version. Keep the callout separate from prose paragraphs and other callouts.
 - When both locales already state a constraint for the same feature, their version and feature scope must agree. Do not add a constraint to a translation that had none merely to match formatting.
-- Preserve existing development status, installed-package availability, platform, permission, and provider eligibility conditions. An effective-version label does not prove public release or grant authorization.
+- State the client version the user needs directly. Omit internal caveats such as “implemented on the development branch,” “availability depends on the installed package,” or “confirm that the package includes this capability.” Preserve platform, permission, and provider eligibility conditions that affect use, expressed as requirements users can understand or check. For a feature that is not available, say so directly.
 - Release history, unimplemented plans, OS/runtime requirements, agreement revisions, configuration versions, and example content versions retain their own meaning and numbering.
 
 Use the following format, replacing the example version and feature name as appropriate:
@@ -117,6 +117,13 @@ Use the following format, replacing the example version and feature name as appr
 
 Keep this convention and AGENTS.md consistent when updating either file.
 
+### Writing for end users
+
+- Explain what a feature does, where to use it, what it requires, and how to resolve problems.
+- Keep development branches, merge status, source configuration snapshots, internal release gates, and component migration plans out of user instructions. Never ask users to check these details.
+- Replace implementation-status caveats with an effective version, current support scope, or visible steps. Keep component names and technical details when they help with configuration, troubleshooting, permissions, or licenses.
+- Keep advice for documentation authors out of user-facing prose. Apply this approach in both languages while preserving actual limitations and authorization conditions.
+
 ## License
 
 - Source code, theme customizations, and project configuration in this repository are licensed under the [MIT License](LICENSE).

diff --git a/docs/01-getting-started/01-system-requirements.md b/docs/01-getting-started/01-system-requirements.md
@@ -41,7 +41,7 @@ macOS 的 GUI 自动化当前由 HostAgent 承载。首次使用相关能力时
 | 磁盘空间 | 2GB | 20 GB 及以上 |
 
 :::info Windows 本机 GUI 自动化
-Windows 安装包已内置并默认启用 CUA Driver，本机 GUI 自动化不需要另装 HostAgent。这是 Windows HostAgent 完成前的过渡实现；macOS 当前仍使用 HostAgent，Windows、Linux 和其他平台的 HostAgent 仍在开发。详见 [GUI 桌面自动化](../02-user-guide/09-capabilities/05-computer-use.md)。
+Windows 安装包已内置并默认启用 CUA Driver，本机 GUI 自动化不需要另装 HostAgent。macOS 的 GUI 自动化使用 HostAgent，需要授予相应系统权限。详见 [GUI 桌面自动化](../02-user-guide/09-capabilities/05-computer-use.md)。
 :::
 
 ### Linux

diff --git a/docs/01-getting-started/02-installation/01-windows.md b/docs/01-getting-started/02-installation/01-windows.md
@@ -55,7 +55,7 @@ DesireCore 会在首次启动后，将推荐的 Python 和 Node.js 版本导入
 
 ### CUA Driver（GUI 自动化）
 
-CUA Driver 仅用于当前 Windows 电脑的 GUI 自动化，默认启用。它是 Windows HostAgent 完成前的过渡实现，让 Windows 用户先具备 GUI 操作能力。macOS 当前仍由 HostAgent 承载 GUI 操作，Windows、Linux 和其他平台的 HostAgent 仍在开发中。
+CUA Driver 默认启用，用于操作当前 Windows 电脑上的应用界面。你可以直接向智能体描述任务，例如“打开记事本并输入会议摘要”。
 
 :::note 磁盘占用与安全扫描
 这些归档和可执行程序会增加安装包与首次启动后的磁盘占用。安全软件也可能在首次解包或运行时再次扫描它们；请等待扫描完成，不要通过关闭系统防护来强行绕过告警。

diff --git a/docs/01-getting-started/02-installation/02-macos.md b/docs/01-getting-started/02-installation/02-macos.md
@@ -34,9 +34,9 @@ keywords: [macOS, 安装, DMG, Gatekeeper, Apple Silicon, Intel]
 
 ## GUI 自动化与 HostAgent
 
-macOS 版本当前由 **HostAgent** 承载本机 GUI 操作和相关设备能力。HostAgent 是现行执行组件，并未被 Windows 使用的 CUA Driver 取代。
+macOS 通过 **HostAgent** 操作本机应用界面。使用前请确认 HostAgent 已连接到 DesireCore。
 
-首次使用界面读取、点击、输入或截图等能力时，macOS 可能要求授予 **辅助功能**、**屏幕录制**等权限。请只按实际任务需要授权；如果权限变更后能力没有立即恢复，重新启动 HostAgent 或 DesireCore 后再试。Windows 暂时使用内置 CUA Driver，是 Windows HostAgent 完成前让用户先获得 GUI 能力的过渡方案。
+首次使用界面读取、点击、输入或截图等能力时，macOS 可能要求授予 **辅助功能**、**屏幕录制**等权限。请只按实际任务需要授权；如果权限变更后能力没有立即恢复，重新启动 HostAgent 或 DesireCore 后再试。
 
 ## 处理 Gatekeeper 提示
 

diff --git a/docs/02-user-guide/04-delegation/04-human-gate.md b/docs/02-user-guide/04-delegation/04-human-gate.md
@@ -65,7 +65,7 @@ keywords: [人闸门, Human Gate, 确认, 权限, 风险等级, 安全]
 智能体："好的，正在执行..."
 ```
 
-对于支持记忆的命令审批，还可选择 **“总是允许”**。当前实现会记住这一次完整命令的精确规则，不会自动扩大为“同一目录”或“同一可执行文件”的全部操作。
+对于支持记忆的命令审批，还可选择 **“总是允许”**。系统会记住这一次完整命令的精确规则，不会自动扩大为“同一目录”或“同一可执行文件”的全部操作。
 
 ### 拒绝
 

diff --git a/docs/02-user-guide/05-super-document/05-version-history.md b/docs/02-user-guide/05-super-document/05-version-history.md
@@ -17,7 +17,7 @@ keywords: [版本历史, 版本管理, 回溯, 版本对比, 回滚]
 - **操作人**：标记是智能体修改还是你手动编辑
 - **时间戳**：精确到分钟
 
-在当前实现中，版本历史基于文件的 Git 提交记录。每次智能体修改、手动编辑、导出前的重要保存点都会形成可追溯记录。
+每次智能体修改、手动编辑，以及导出前的重要保存点都会记录在版本历史中，方便你比较修改或恢复旧稿。
 
 超级文书可能按以下粒度展示版本：
 

diff --git a/docs/02-user-guide/06-agents/03-create-agent.md b/docs/02-user-guide/06-agents/03-create-agent.md
@@ -7,7 +7,7 @@ keywords: [创建智能体, 自定义 Agent, 对话创建, 模板]
 # 创建自定义智能体
 
 :::info 生效版本
-`v10.0.179+`（长期指令 `instructions.md`）。该能力已在开发分支实现，使用前请确认安装包包含该能力。
+`v10.0.179+`（长期指令 `instructions.md`）。
 :::
 
 当市场上没有满足你需求的智能体时，你可以创建一个完全自定义的智能体。DesireCore 提供两种创建方式。

diff --git a/docs/02-user-guide/06-agents/04-edit-persona.md b/docs/02-user-guide/06-agents/04-edit-persona.md
@@ -7,7 +7,7 @@ keywords: [人格设定, Persona, 角色定位, 性格特征, 智能体配置]
 # 编辑人格设定
 
 :::info 生效版本
-`v10.0.179+`（长期指令 `instructions.md`）。该能力已在开发分支实现，使用前请确认安装包包含该能力。
+`v10.0.179+`（长期指令 `instructions.md`）。
 :::
 
 人格设定（Persona）定义了智能体"是谁"——它的语气、风格、专业领域和行为方式。这不是一段人设文案，而是一份**可执行的行为规范**。

diff --git a/docs/02-user-guide/06-agents/05-edit-principles.md b/docs/02-user-guide/06-agents/05-edit-principles.md
@@ -7,7 +7,7 @@ keywords: [行为准则, Principles, L0, L1, L2, 安全规则, 优先级]
 # 编辑行为准则
 
 :::info 生效版本
-`v10.0.179+`（长期指令 `instructions.md`）。该能力已在开发分支实现，使用前请确认安装包包含该能力。
+`v10.0.179+`（长期指令 `instructions.md`）。
 :::
 
 行为准则（Principles）是智能体的"行为手册"——它规定了智能体必须遵守的规则、禁止触碰的红线，以及决策时的优先级排序。

diff --git a/docs/02-user-guide/06-agents/06-agent-files.md b/docs/02-user-guide/06-agents/06-agent-files.md
@@ -7,7 +7,7 @@ keywords: [AgentFS, 文件系统, 资源管理器, 智能体文件, 文件结构
 # 文件资源管理器
 
 :::info 生效版本
-`v10.0.179+`（长期指令 `instructions.md`）。该能力已在开发分支实现，使用前请确认安装包包含该能力。
+`v10.0.179+`（长期指令 `instructions.md`）。
 :::
 
 每个智能体的所有配置、记忆和技能都以文件的形式存储在 AgentFS（智能体文件系统）中。资源管理器让你可以直观地浏览和管理这些文件。

diff --git a/docs/02-user-guide/06-agents/09-clone-and-sync.md b/docs/02-user-guide/06-agents/09-clone-and-sync.md
@@ -7,7 +7,7 @@ keywords: [Clone, 克隆智能体, 同步, 冲突解决, Agent Git]
 # Clone 与同步
 
 :::info 生效版本
-`v10.0.179+`（长期指令 `instructions.md`）。该能力已在开发分支实现，使用前请确认安装包包含该能力。
+`v10.0.179+`（长期指令 `instructions.md`）。
 :::
 
 Clone 用于基于现有智能体创建一个新副本。它适合做实验、为不同项目准备变体，或把市场智能体调整成自己的版本。

diff --git a/docs/02-user-guide/06-agents/12-prompt-center.md b/docs/02-user-guide/06-agents/12-prompt-center.md
@@ -7,7 +7,7 @@ keywords: [提示词中心, 系统提示词, 全局提示词, 团队提示词, P
 # 提示词中心与内容归属
 
 :::info 生效版本
-`v10.0.179+`（长期指令 `instructions.md`）。该能力已在开发分支实现，使用前请确认安装包包含该能力。
+`v10.0.179+`（长期指令 `instructions.md`）。
 :::
 
 提示词中心把分散在用户、团队和智能体目录中的提示词来源放到同一个界面中管理。打开 **资源管理器 → 提示词中心**，左侧选择作用范围，右侧编辑内容或预览组合结果。
@@ -89,7 +89,7 @@ L0/L1/L2 表示加载粒度，不是权限或安全等级。分层文件没有
 | 预览中看到重复内容 | 同一要求写到了多个作用范围；保留在真正归属的位置 |
 | 团队提示词不生效 | 确认智能体已加入该团队；多团队时检查对应来源 |
 | 分层源码提示格式问题 | 检查标题是否严格为 `## L0`、`## L1`、`## L2`；长期指令无需这些标题 |
-| 找不到长期指令入口 | 升级至 `v10.0.179+`，并确认安装包包含长期指令能力 |
+| 找不到长期指令入口 | 在 **设置 → 关于** 中检查版本，升级至 `v10.0.179+` 后重试 |
 | 长期指令超出预算 | 精简正文，把详细步骤移到技能；它不会通过截断或 L2 隐藏来继续执行 |
 
 :::caution 提示词 ≠ 权限

diff --git a/docs/02-user-guide/09-capabilities/05-computer-use.md b/docs/02-user-guide/09-capabilities/05-computer-use.md
@@ -1,49 +1,39 @@
 ---
 title: GUI 桌面自动化
-description: 了解 DesireCore 如何在 macOS 上通过 HostAgent、在 Windows 上暂时通过内置 CUA Driver 操作本机图形界面。
+description: 了解 DesireCore 如何在 macOS 上通过 HostAgent、在 Windows 上通过内置 CUA Driver 操作本机图形界面。
 keywords: [Computer Use, CUA Driver, GUI, Windows, macOS, 桌面自动化, HostAgent]
 ---
 
 # GUI 桌面自动化
 
 ## 当前可用范围
 
-DesireCore 当前可以在 **macOS 和 Windows 本机**操作原生应用的图形界面，例如读取窗口与可访问性元素、点击控件、输入文字、发送按键以及获取界面状态。两个平台使用的执行载体不同：
+DesireCore 当前可以在 **macOS 和 Windows 本机**操作原生应用的图形界面，例如读取窗口与可访问性元素、点击控件、输入文字、发送按键以及获取界面状态。两个平台的使用要求不同：
 
-- **macOS**：HostAgent 是现行 GUI 操作载体，通过 macOS 原生系统能力执行操作。
-- **Windows**：在 Windows HostAgent 完成前，DesireCore 暂时使用内置 CUA Driver，让 Windows 用户可以先使用本机 GUI 自动化。
+- **macOS**：需要连接 HostAgent，并授予辅助功能、屏幕录制等任务所需权限。
+- **Windows**：使用内置 CUA Driver 操作本机应用界面，无需另外安装 HostAgent。
 
 Windows 安装包已内置并默认启用 [CUA Driver](https://github.com/trycua/cua)。正常情况下，Windows 用户不需要另行下载安装驱动或 HostAgent，直接向智能体描述任务即可。
 
-:::info 为什么 Windows 本机不需要 HostAgent？
-HostAgent 并未被 CUA Driver 取代：macOS 当前仍通过 HostAgent 承载 GUI 操作。只是 Windows 版 HostAgent 尚在开发，DesireCore 才暂时通过 CUA Driver MCP 子进程提供本机能力。待 Windows HostAgent 完成后，平台载体和能力边界可能继续调整。
-:::
-
 | 场景 | 当前状态 | 所需组件 |
 |------|---------|---------|
 | macOS 本机 GUI 自动化 | 已支持 | macOS HostAgent；需授予相应系统权限 |
-| Windows 本机 GUI 自动化 | 已支持（过渡实现） | DesireCore 内置 CUA Driver，零安装 |
-| Windows、Linux HostAgent | 开发中 | 后续原生 HostAgent 实现 |
-| 其他桌面系统与 Android、iOS、HarmonyOS HostAgent | 开发中 | 后续平台实现 |
+| Windows 本机 GUI 自动化 | 已支持 | DesireCore 内置 CUA Driver，零安装 |
+| Linux、其他桌面系统与 Android、iOS、HarmonyOS GUI 自动化 | 暂不支持 | — |
 
 ## 工作原理
 
-两个已支持平台的任务入口相同，但执行路径不同。
-
 ### macOS：HostAgent 路径
 
-1. 你在 DesireCore 中描述 GUI 操作任务。
-2. 智能体规划步骤，并通过设备能力链路调用 macOS HostAgent。
-3. HostAgent 使用 macOS 原生 Framework 和已授予的辅助功能、屏幕录制等权限执行操作。
-4. HostAgent 返回界面或执行结果，智能体据此继续任务并核对状态。
+1. 在 DesireCore 中描述要完成的任务。
+2. HostAgent 已连接并获得所需权限后，智能体读取界面，执行点击、输入或截图等操作。
+3. 智能体在每一步后检查界面，并向你报告结果；需要确认时会暂停等待。
 
-### Windows：CUA Driver 过渡路径
+### Windows：CUA Driver 路径
 
-1. 你在 DesireCore 中描述任务，例如“打开记事本并输入会议摘要”。
-2. 智能体规划步骤，并从系统 MCP 中选择 CUA Driver 提供的工具。
-3. DesireCore 在本机启动独立的 `cua-driver` 子进程，通过标准输入输出与其通信。
-4. CUA Driver 调用 Windows UI Automation、窗口和输入相关能力，返回窗口、元素或截图结果。
-5. 智能体根据结果继续操作并核对最终状态。
+1. 在 DesireCore 中描述任务，例如“打开记事本并输入会议摘要”。
+2. 智能体使用可用的桌面操作工具读取窗口、点击控件、输入文字或获取截图。
+3. 智能体在每一步后检查界面，确认操作结果。
 
 如果你的 `PATH` 中已有自行安装的 `cua-driver`，DesireCore 会优先使用它；否则回退到安装包内置版本。两者都不可用时，系统会跳过该能力，不会反复弹出连接错误。
 
@@ -102,7 +92,7 @@ GUI 自动化依赖目标平台提供的可访问性、窗口和输入能力，
 - 对业务关键流程先在测试账号或副本数据上验证。
 
 :::warning 第三方组件
-Windows 当前使用的 CUA Driver 是由其权利人提供、按其自身许可证分发的独立第三方程序，并非 DesireCore 自有组件或 HostAgent。它是 Windows HostAgent 完成前的过渡载体；其版本、兼容性和上游支持可能变化，具体以随软件提供的第三方声明及 [第三方软件与许可](../../05-more/10-third-party-software.md) 为准。
+Windows 当前使用的 CUA Driver 是由其权利人提供、按其自身许可证分发的独立第三方程序，并非 DesireCore 自有组件或 HostAgent。其版本、兼容性和上游支持可能变化，具体以随软件提供的第三方声明及 [第三方软件与许可](../../05-more/10-third-party-software.md) 为准。
 :::
 
 ## 下一步

diff --git a/docs/02-user-guide/09-capabilities/06-integrations-overview.md b/docs/02-user-guide/09-capabilities/06-integrations-overview.md
@@ -73,11 +73,11 @@ DesireCore 内置完整的邮件管理能力，支持 Gmail、Outlook 和 IMAP/S
 
 ## 桌面与移动设备
 
-当没有现成的 API 或工具可用时，DesireCore 可以通过 Computer Use 操作图形界面。目前 **macOS 由 HostAgent 承载 GUI 操作**；**Windows 暂时由内置并默认启用的 CUA Driver 承载**，让 Windows 用户在原生 HostAgent 完成前先具备本机能力。Windows、Linux、其他桌面系统及移动端 HostAgent 仍在开发。
+当没有现成的 API 或工具可用时，DesireCore 可以通过 Computer Use 操作本机图形界面。目前支持 **macOS 和 Windows**：macOS 需连接 HostAgent 并授予系统权限，Windows 已内置并启用 CUA Driver。
 
 - **macOS 桌面应用操控** — 由 HostAgent 通过 macOS 原生能力执行，需要相应系统权限
-- **Windows 桌面应用操控** — 由 CUA Driver 过渡实现，通过可访问性元素、鼠标和键盘操作当前电脑上的 GUI 应用
-- **Linux、其他桌面与移动设备** — 属于后续 HostAgent 平台路线，当前不应按已经可用理解
+- **Windows 桌面应用操控** — 通过内置 CUA Driver 操作当前电脑上的 GUI 应用
+- **Linux、其他桌面与移动设备** — 暂不支持 GUI 自动化
 - **屏幕感知** — 截屏、识别界面元素，理解当前画面内容
 
 Computer Use 适合没有开放 API、需要跨多个桌面应用完成的任务，但并非所有界面都能可靠操控。自绘控件、UAC 安全桌面、锁屏、管理员应用和受保护内容可能不可访问；发送、支付、删除、发布等外部副作用仍应由用户确认。