# Motux Build 使用手册

Motux Build 把产品澄清、开发标准、质量检查和协作经验交给编程 Agent 使用。你仍在原来的编程工具里提出任务；这份手册帮助你选对入口、说清需求，并判断每一步是否完成。

功能核对：2026-09-13。Core 1.0.98 · Manager 0.1.29 · Brief 0.1.10 · joint-delivery 0.1.0。底座代码能力自 Plugin 1.0.40 提供；具体安装版本以官网清单为准。

在线阅读：https://motux.app/motux-build/manual/index.html

这份手册以普通使用者为主；示例默认交给 Agent，不代表存在 motux 全局 CLI。示例为演示场景。

## 目录

- 安装与第一次使用：认识产品的四个部分、安装到 Codex 用户范围、为项目启用或停用插件、只在当前项目安装、检查安装与加载状态、单独使用 Motux Brief
- 已有项目与多个工具：接入已有项目、融合规则与项目例外、接入其他编程 Agent、后续 Agent 策略与入口维护
- 需求梳理与产品决策：澄清目标与收敛 MVP、全面产品问卷、聚焦决策表单、保存、继续填写与落地决策
- 开发、测试与交付：新产品工程初始化、技术选型与架构边界、界面、交互与前端实现、API、数据、权限与服务集成、按风险选择测试与回归、代码审查与独立 QA、Git、版本与交付说明
- 任务推进与经验复用：按任务读取需要的标准、并行开发与集中验收、项目记忆、检查点与交接、复盘与经验回流
- 独立能力模块：检查与安装独立模块、启用、固定版本与停用、单独更新与回退模块、处理中断与锁冲突、联合开发统筹模块
- 第三方 Skill 管理：推荐、跳过与抑制推荐、安装已选择的 Skill、检查、更新和移除 Skill
- 更新、体检与恢复：只读检查更新、更新或修复本机插件、一次完成合格的项目补丁更新、按组件计划更新、体检、修复判断与项目回退、旧布局与早期 Motux Dev
- 附录与问题排查：自然语言与命令名称、文件归属与术语、常见问题的最短处理路径

## 安装与第一次使用

先选择安装范围，再确认当前项目实际使用哪一份 Build。

### 认识产品的四个部分

分清标准、管理工具、表单和独立模块各自负责什么。

#### 能帮你完成什么

Core 是产品、工程和协作标准及任务路由；Manager 管理安装、规则接入、校验、更新和回退；Brief 生成本地需求决策表单；独立能力模块补充特定工作方法。Codex Plugin 把前三者打包为一个入口，joint-delivery 等模块另行安装。标准帮助 Agent 做判断，不能保证模型每次正确，也不会替你购买服务、创建账号或自动部署。

#### 使用前

你已经有可以读写项目文件的编程 Agent。使用它的模型、权限和工具仍由原宿主提供。

#### 怎么使用

1. 先选安装范围：多个 Codex 项目共享插件，或只在一个项目保存完整组件。
2. 安装后明确当前项目是否启用，检查安装来源和版本。
3. 在任务中说出目标、限制和验收方式；需要专门功能时，直接提出本手册中的请求。

#### 试着这样对 Agent 说

```text
请解释当前项目使用的 Motux Build 来源和版本，并告诉我产品澄清、开发实现、模块管理分别该怎样开始。先只读检查。
```

#### 如何判断完成

- 得到明确的安装来源、可用组件及下一步入口。
- 知道“开发指导流程”由 Agent 执行，“管理操作”需要对应的 Manager 能力。

#### 适用边界

- Build 不是托管开发平台，也不是自带业务系统的脚手架。
- 本手册中的示例是演示任务，不是已经完成的客户案例。

### 安装到 Codex 用户范围

一份插件供多个 Codex 项目按需使用。

#### 能帮你完成什么

适合主要使用 Codex、希望统一维护 Build 的用户。插件中保留只读运行文件，每个项目保留自己的选择、文档和任务记录。以后更新这份插件，全局启用的项目在新任务中使用新版。

#### 使用前

本机已安装支持 Plugin 的 Codex，并允许安装插件。下载需要网络；安装先校验公开清单中的版本、大小和 SHA-256。

#### 怎么使用

1. 在 Codex 中提交下面的请求，明确选择用户级范围。
2. Agent 核验来源，使用固定的 motux marketplace 安装 motux-build@motux。
3. 首次安装时查看启动 Hook 的准确内容，在 Codex 中决定是否信任；随后新开任务并为项目选择使用方式。

#### 试着这样对 Agent 说

```text
请按 https://motux.app/motux-build/instructions/install-motux-build.md 安装 Motux Build。我选择 Codex 用户级范围。校验正式包后安装 motux-build@motux，并说明启动 Hook 和验证结果。
```

#### 如何判断完成

- Codex 插件列表中出现一份已安装、已启用的 motux-build@motux。
- Agent 报告实际版本；新任务能发现 motux-build Skill。

#### 适用边界

- 插件安装不会自动把所有项目设为启用。
- 未信任 Hook 时仍可显式调用 motux-build，但不会自动询问新项目。
- 用户级插件仅面向 Codex；多种 Agent 共用同一项目时选择项目内安装。

### 为项目启用或停用插件

决定当前项目使用用户级 Build，或暂时停用。

#### 能帮你完成什么

首次打开尚未选择的项目时，你可以使用已安装插件、安装完整项目副本，或禁用 Build。选择使用插件只记录项目的最小配置；选择禁用会停止自动加载，并保留已有项目资料。

#### 使用前

已安装 Codex 用户级插件；当前项目没有优先级更高的项目内 Build 安装或配置冲突。

#### 怎么使用

1. 打开目标项目，明确说“在这个项目使用已安装的 Motux Build 插件”。
2. 让 Agent 确认分类为 user；之后在新任务中通过同一插件使用规则。
3. 如需暂停，明确请求只停用当前项目；恢复时再选择使用插件。

#### 试着这样对 Agent 说

```text
在当前项目使用已安装的 Motux Build 用户级插件。请先检查是否存在项目内安装或冲突，确认可用后记录这个项目的选择。
```

#### 如何判断完成

- 当前项目记录 user 选择；不会复制整套 Core、Manager 或 Brief。
- 停用后项目选择为 disabled，已有文档继续保留。

#### 适用边界

- 已有项目内安装始终优先，不能用一个启用请求自动迁移或覆盖。
- conflict 状态需要先体检；不要手动改配置假装已完成迁移。

### 只在当前项目安装

获得完整、可锁定版本的项目内 Build。

#### 能帮你完成什么

适合需要逐项目控制版本、保留自包含组件，或让多个编程 Agent 使用共同规则的项目。组件保存在项目的 .motux 中，由清单锁定文件和版本。确定为空的新项目可走快速接入；已有代码的项目会先进行只读盘点和接入计划。

#### 使用前

已确认项目根目录和当前使用的 Agent。安装时需要取得并校验完整发行包。

#### 怎么使用

1. 在目标项目发出只安装到项目的请求。
2. 空项目由固定 Runner 安装组件及当前 Agent 的一个入口；已有项目先看接入计划。
3. 确认需要写入的入口与规则处理后执行；新开任务，再检查当前 Agent 是否真正加载。

#### 试着这样对 Agent 说

```text
开始在当前项目使用 Motux Build。我选择完整项目内安装。请按 https://motux.app/motux-build/instructions/install-motux-build.md 先判断项目状态，只配置我当前使用的 Agent。
```

#### 如何判断完成

- 项目具有受管理的 Manager、Core、Brief 和精确版本锁。
- 安装结果说明已配置的 Agent、延期的 Agent，以及是否需要重新打开任务。

#### 适用边界

- 快速安装不会自动完成产品设计、工程业务代码或所有 Agent 的配置。
- 自包含规则不等于模型、依赖下载和外部服务都可以离线。

### 检查安装与加载状态

区分已经放入文件和实际开始使用。

#### 能帮你完成什么

状态检查可以解释当前使用用户插件还是项目安装、组件版本是否完整、入口是否可达，以及为什么安装后行为没有变化。项目内安装还会区分待激活、已激活、陈旧和阻断。

#### 使用前

在你想使用 Build 的那个项目中检查，而不是在另一个目录里推测结果。

#### 怎么使用

1. 请求只读检查安装来源、版本与加载状态。
2. 若为 installed-pending-activation，按提示重开任务或工作区，再核验入口。
3. 若为 stale 或 blocked，先阅读原因和修复计划，不反复重装。

#### 试着这样对 Agent 说

```text
请只读检查 Motux Build 的安装来源、组件完整性和当前 Agent 的加载状态。若尚未生效，说明具体原因和最小下一步。
```

#### 如何判断完成

- user/local/disabled/undecided/conflict 等来源判断有明确说明。
- 项目桥接状态为 active，或明确指出 pending、stale、blocked 的原因。

#### 适用边界

- 用户插件的发现结果与项目内 adapter doctor 是不同检查。
- 新安装或更新不代表当前已打开的任务自动刷新。

### 单独使用 Motux Brief

只需要需求表单时，不必接入完整 Build。

#### 能帮你完成什么

Brief 可以作为独立 Skill 使用，帮助你在一个本地表单中回答产品问题。它不负责完整的工程标准、项目桥接或 Build 组件更新；已经使用完整 Build 的用户通常无需再安装一份。

#### 使用前

编程 Agent 能使用 Skill；环境可运行 Brief 随包提供的 Python 生成脚本，并有浏览器可打开表单。

#### 怎么使用

1. 使用官网安装工作台的“Motux Brief”入口，取得当前正式包的准确校验信息。
2. 要求只安装 Brief，并明确目标项目及已有规则。
3. 安装后发出产品澄清请求，填写并保存生成的表单。

#### 试着这样对 Agent 说

```text
我只需要 Motux Brief。请使用官网 https://motux.app/motux-build/ 的 Brief 独立安装说明，校验当前包后安装，不接入完整 Motux Build。
```

#### 如何判断完成

- Agent 可以生成本地 Brief 问卷和可填写表单。
- 项目不会因此获得完整 Build 接入或工程初始化。

#### 适用边界

- 具体安装位置遵循 Agent 的 Skill 机制；不要把示例路径当作跨工具通用入口。

## 已有项目与多个工具

把现有规则接入同一套工作方式，并保留项目自己的决定。

### 接入已有项目

先盘点已有代码、约定和入口，再确定接入范围。

#### 能帮你完成什么

已有项目可能已包含 AGENTS.md、CLAUDE.md、Cursor 规则和成熟工程约定。Manager 先识别这些事实，区分安装组件、建立入口和融合规则，避免把新项目模板直接覆盖到正在运行的项目。

#### 使用前

当前目录是正确项目根；保留已有改动。接入请求不自动授权业务重构、部署或迁移数据。

#### 怎么使用

1. 请 Agent 只读检查当前安装状态、规则位置和 Git 改动。
2. 阅读接入计划：组件路径、入口改动、规则冲突、验证和恢复方法。
3. 集中确认需要的写入与冲突决定，再执行并检查加载结果。

#### 试着这样对 Agent 说

```text
请为这个已有项目接入 Motux Build。先盘点已有 Agent 规则和未提交改动，给出接入与融合计划；保留项目现有业务架构。
```

#### 如何判断完成

- 有可审阅的接入计划，现有规则被明确保留、融合或记录为冲突。
- 完成后入口、组件和项目选择有独立验证结果。

#### 适用边界

- 遇到未知 .motux、外来命名空间或修改过的受管理文件会停止相应写入。
- 安装完成不代表规则冲突已经解决。

### 融合规则与项目例外

保留已有约定，同时让通用标准可以继续升级。

#### 能帮你完成什么

Agent 将规则分为兼容、互补、冲突和项目特有内容，集中展示需要决定的部分。项目例外放在 overrides，冲突的处理理由单独记录；之后 Core 更新只复查受到改变影响的决定。

#### 使用前

已有项目使用完整项目内安装，并准备好能公开给当前 Agent 读取的规则资料。

#### 怎么使用

1. 要求盘点规则，不复制或读取凭据及私有资料。
2. 对实质冲突选择保留项目约定、采用通用标准或做明确例外。
3. 确认后保存 PROJECT_RULES、CONFLICT_DECISIONS 和 adoption 状态，再验证入口。

#### 试着这样对 Agent 说

```text
项目规定所有日期存 UTC，界面按用户时区显示。请把它作为项目规则保留，检查与 Motux Build 的冲突，并集中给我需要决定的选项。
```

#### 如何判断完成

- 项目例外与通用组件分开保存。
- 重要冲突有选择、原因和影响范围，后续 Agent 可以继续读取。

#### 适用边界

- 不要直接编辑 managed/core 中的文件来保存项目偏好。
- 历史 adoption 状态格式升级需要单独预览，不能随组件更新静默改写。

### 接入其他编程 Agent

让同一个项目中的不同工具读取同一份标准。

#### 能帮你完成什么

完整项目内安装支持为 Codex、Claude、Cursor、VS Code / GitHub Copilot、Trae、CodeBuddy、Qoder、Devin 和 Windsurf 规划对应入口。入口是很小的桥接文件，标准、版本和项目记忆仍只有一份。Qoder CN 只识别既有 .lingma/rules 并提供冲突检查和人工说明，不自动生成未经验证的格式。

#### 使用前

使用完整项目内安装；确认当前实际使用的工具。用户级 Codex Plugin 不承担其他 Agent 的项目桥接。

#### 怎么使用

1. 点名要接入的 Agent，先查看 adapter status 和拟写文件。
2. 确认该 Agent 的计划与精确入口改动；存在旧规则时先处理冲突。
3. 应用后重开目标工具的任务，运行 adapter doctor 验证。

#### 试着这样对 Agent 说

```text
这个项目已有 Motux Build，现在我要使用 Cursor。请只为 Cursor 规划接入，保留其他 Agent 的配置；先展示入口文件及验证方法。
```

#### 如何判断完成

- 只添加或复用被选择工具的入口，没有复制整套 Core。
- 结果说明入口路径、规则优先级和重载要求。

#### 适用边界

- 工具支持是已提供的桥接合同，不是所有工具所有版本都已自动激活。
- 不要为“以后也许会用”一次性写入所有工具目录。

### 后续 Agent 策略与入口维护

选择何时配置新工具，并检查或移除旧入口。

#### 能帮你完成什么

完整接入可以选择发现新 Agent 后先出计划、仅保留通用桥接，或在严格条件下自动创建空的独立原生入口。入口体检会发现内容修改和目标不可达；移除只处理完整的 Motux 自有入口或明确批准的标记块。

#### 使用前

已有项目桥接和适配器记录。自动创建策略需要明确选择；新项目快速接入默认只配置当前 Agent。

#### 怎么使用

1. 请求展示当前未来 Agent 策略和已登记的入口。
2. 一般选择 plan-on-discovery；需要自动空入口时查看适用工具和限制再确认。
3. 维护时先体检，移除时点名工具并确认是否有共用入口。

#### 试着这样对 Agent 说

```text
检查项目的 Motux Agent 入口和后续接入策略。新工具先生成计划；如果移除 Cursor 的入口会影响其他工具，请先说明。
```

#### 如何判断完成

- 得到现有、缺失、被修改或共用的入口清单。
- 确认的移除不会删掉其他 Agent 仍在使用的共同桥接。

#### 适用边界

- safe-auto-empty-native 仅适用于受支持的独立空目标，不适用于根文件、Copilot 既有指令或 Qoder CN。
- 发现已修改文件时先保留，不能用“修复”覆盖用户内容。

## 需求梳理与产品决策

从想法到明确的第一版，使用 Brief 一次处理相关问题。

### 澄清目标与收敛 MVP

决定第一版必须做什么，以及暂时不做什么。

#### 能帮你完成什么

Agent 先确认主要用户、真实问题和可观察结果，再梳理最短完整业务流程。收敛不是只删除功能：必要的失败提示、权限、数据完整性与恢复也属于可用的第一版。你会得到范围及重新考虑延期需求的条件。

#### 使用前

提供现有想法、用户反馈或已确认约束；没有成熟 PRD 也可以开始。

#### 怎么使用

1. 描述谁在什么场景遇到问题，避免只列页面名称。
2. 让 Agent 给选项、取舍和推荐，集中确认高影响决定。
3. 确认第一版流程、验收标准、非目标和后续进入条件，再推进实现。

#### 试着这样对 Agent 说

```text
我想做一个内部报修工具。先帮我确定主要使用者、一次报修到确认修复的最小流程和第一版范围；把可以延期的功能与重新纳入条件写清楚。
```

#### 如何判断完成

- 清楚的用户任务、MVP 范围和验收条件。
- PRD、用户路径或开放问题记录只更新已确认部分。

#### 适用边界

- 产品探索可以全面，第一版实现不因此包含所有被讨论功能。
- 没有解决互相矛盾的目标时，先确认分歧再继续。

### 全面产品问卷

把新产品的大量相关问题整理成分组表单。

#### 能帮你完成什么

Motux Brief 根据当前项目资料动态设计问题，不套固定问卷。适用于新产品、重大重新定位或需求尚不清楚的阶段，通常 20–60 题、4–10 个主题，复杂情况最多 100 题。每题说明为什么现在要问、选项差异及推荐理由。

#### 使用前

让 Agent 读取已有产品资料和先前 Brief，避免重复询问已确认事实。生成器需要 Python，填写需要浏览器。

#### 怎么使用

1. 说明希望全面梳理的产品，并请求 comprehensive 模式。
2. Agent 生成 question-set 和本地 motux-brief-form.html。
3. 逐主题填写，可选预设项或“其他”；没答完也能保存进度。

#### 试着这样对 Agent 说

```text
请为这个内部报修产品生成全面的 Motux Brief。先读已有资料，按用户、核心流程、权限、通知、异常和上线范围分组，解释各选项的取舍。
```

#### 如何判断完成

- 本地可填写表单，而不是长串逐条聊天提问。
- 每题有原因、2–4 个具体选项、推荐和自定义答案入口。

#### 适用边界

- 推荐不会预先替你选中；未填写的题目不能当作已同意。
- 不要把密码、客户数据或服务器凭据写进答案。

### 聚焦决策表单

只解决当前阶段的一组关键选择。

#### 能帮你完成什么

产品方向已确定，但某个模块仍有几个相互关联的取舍时，Brief 使用 focused 模式，常见为 3–10 题。它帮助你一次看完成本、体验、依赖和后续影响，不为小改动生成大问卷。

#### 使用前

提供已确认决定和这次需要解决的边界；简单确定性实现一般无需表单。

#### 怎么使用

1. 明确当前阶段，例如通知渠道或界面导航。
2. 要求保留已确认产品范围，只问会影响本阶段的选择。
3. 保存为新的主题 JSON，确认决定后推进对应模块。

#### 试着这样对 Agent 说

```text
报修流程已经确定。请做一份聚焦 Brief，只比较第一版通知采用站内消息、邮件还是二者组合，考虑用户体验、成本和失败处理。
```

#### 如何判断完成

- 问题数量与当前决策规模相称。
- 已有答案和早期决定不会被新问卷默认覆盖。

#### 适用边界

- 如果你明确要求全面探索，已有文档不意味着必须缩成 focused。

### 保存、继续填写与落地决策

让表单答案成为项目中可读取的决定记录。

#### 能帮你完成什么

表单的“保存到项目”允许你在浏览器中选择一次项目根目录，然后写入页面显示的 JSON 位置。不支持目录写入的浏览器可以下载 JSON，再放到指定位置。Agent 读取完成状态和自定义答案后，检查冲突，再更新受影响的产品文档。

#### 使用前

已生成当前表单。首次 Brief 使用未占用的 motux-brief.json；后续阶段使用新的主题文件名。

#### 怎么使用

1. 填写后点击保存到项目，在系统目录选择器里核对目标。
2. 若使用下载方式，将 JSON 放到页面指定位置，再告诉 Agent 已保存。
3. 让 Agent 读取 status、completion、answers，补齐剩余问题并确认冲突；之后更新 PRD、流程或计划。

#### 试着这样对 Agent 说

```text
我已保存 docs/product/motux-brief-notifications.json。请读取答案，保留已确认决定，指出未完成或互相矛盾之处；确认后只更新受影响的通知方案。
```

#### 如何判断完成

- JSON 标明完成或进行中；自定义答案优先于预设推荐。
- 相关文档可追溯到本次决定，旧阶段记录得到保留。

#### 适用边界

- 新生成的表单不会自动载入旧答案；首次保存遇到同名文件会要求单独确认覆盖。
- 浏览器页面不能自行得知系统目录的完整路径，请以目录选择器为准。

## 开发、测试与交付

把标准用在真实任务上，知道 Agent 应当产出什么证据。

### 新产品工程初始化

在确认产品方向后建立可运行的工程起点。

#### 能帮你完成什么

Core 指导 Agent 建立最小产品资料、技术决策、工程骨架、质量工具和版本记录，并验证最短用户流程。它是开发流程，不是安装插件时自动生成某种固定业务项目。

#### 使用前

产品目标和第一版范围已有确认；关键架构、第三方服务和成本取舍已说明。

#### 怎么使用

1. 先确认产品资料和首个可验证用户流程。
2. 讨论必要的技术选择，再建立与流程有关的工程结构。
3. 运行基本启动、构建或测试，报告已完成部分与尚未接入的真实服务。

#### 试着这样对 Agent 说

```text
按已确认的报修 MVP 初始化工程。先列出必要技术选择，再实现能提交并查看一条报修记录的最小流程，给出运行与验证步骤。
```

#### 如何判断完成

- 可运行的工程骨架和最小演示流程。
- 必要的 README、质量入口、版本和变更记录。

#### 适用边界

- 示例数据要标明；服务未接通时不能把占位界面当成真实完成。

### 技术选型与架构边界

围绕当前需要做取舍，不为假设中的未来堆叠架构。

#### 能帮你完成什么

Agent 从既有项目模式、当前规模和真实约束出发，解释候选技术的收益、代价与迁移成本。架构标准帮助明确模块职责、数据归属、API、错误处理和配置边界。

#### 使用前

提供已有技术栈、部署约束、团队习惯和不能改变的接口。

#### 怎么使用

1. 让 Agent 先读现有结构，列出真正影响结果的选项。
2. 确认高成本或难逆转的决定，再写入技术决策记录。
3. 实现时检查新增抽象是否有当前需求、既有惯例或第二个真实用例。

#### 试着这样对 Agent 说

```text
这个项目已有 PostgreSQL 和后端服务。请评估报修通知如何接入，比较复用现有任务机制与新增队列的代价，推荐满足第一版需求的做法。
```

#### 如何判断完成

- 有依据的选择及明确模块、数据和失败边界。
- 需要保留的决定写进架构说明或技术决策记录。

#### 适用边界

- 默认建议不能替代具体项目事实；外部服务费用和账户授权由用户决定。

### 界面、交互与前端实现

从用户操作流程到完整状态和真实浏览器验证。

#### 能帮你完成什么

前端标准覆盖信息层级、导航、组件、表单、文案、响应式、键盘可用性和数据状态。Agent 应解释用户看到什么、能做什么、操作结果在哪里，而不仅给出一张成功状态截图。

#### 使用前

明确主要用户、设备和任务。已有网站应先复用它的组件和视觉规则。

#### 怎么使用

1. 确认关键页面和用户任务，必要时先展示可体验的方案。
2. 实现加载、空数据、错误、权限拒绝和成功反馈。
3. 在真实浏览器检查桌面/手机、键盘焦点、表单及长文本。

#### 试着这样对 Agent 说

```text
实现报修列表和详情页，沿用现有界面风格。覆盖空列表、加载失败、重复提交和无权限状态，并在桌面与手机上验证。
```

#### 如何判断完成

- 可操作的界面与明确的状态反馈。
- 浏览器验证结果及仍未覆盖的设备或场景。

#### 适用边界

- Build 不自带通用视觉设计 SaaS；专用 Skill 需要按实际缺口另行选择。

### API、数据、权限与服务集成

把成功路径与失败、重试和权限一起设计。

#### 能帮你完成什么

后端标准指导接口输入输出、数据库与迁移、认证授权、后台任务、第三方集成和日志。目标是让接口行为可验证、数据归属清楚，失败后能解释和恢复。

#### 使用前

提供现有 API 和业务规则；测试需要的账号与权限通过项目既有安全渠道处理。

#### 怎么使用

1. 确认接口合同、角色权限、幂等与数据约束。
2. 用最小可验证实现接通流程，覆盖依赖失败和重复请求。
3. 验证成功、拒绝、超时与恢复，并说明迁移及上线边界。

#### 试着这样对 Agent 说

```text
为报修审批设计接口。员工只能查看自己的记录，管理员可以审批；请验证越权访问、重复审批和通知服务超时后的处理。
```

#### 如何判断完成

- 接口和权限行为有直接测试证据。
- 后台任务失败、重试和日志范围有说明。

#### 适用边界

- 生产数据迁移、凭据变更和部署不是普通开发请求的隐含结果。

### 按风险选择测试与回归

用测试证明功能目标，控制无关测试成本。

#### 能帮你完成什么

Agent 根据影响范围选择开发保障等级和验证深度。低风险文案与样式改动不用自动升级为大型 QA 项目；权限、数据和并发问题需要更强证据。先做聚焦验证，相关实现冻结后再做必要的完整回归。

#### 使用前

说明目标行为、改变的范围，以及无法运行的环境或依赖。

#### 怎么使用

1. 定义可观察完成条件，并选择真正证明它的验证。
2. 执行相关单元、集成或浏览器测试，检查失败场景。
3. 汇报通过项、未运行项和剩余风险；代码改变后只重跑受影响检查。

#### 试着这样对 Agent 说

```text
请验证报修审批功能。重点证明权限隔离、重复请求不会重复处理、失败后可恢复；列明实际执行和未执行的测试。
```

#### 如何判断完成

- 测试对应实际目标，而不是仅重复实现中的判断。
- 测试通过与尚未覆盖的风险分开说明。

#### 适用边界

- 测试失败不能通过降低断言或删除场景来掩盖。
- 未运行的生产验证不能写成已经通过。

### 代码审查与独立 QA

让已冻结的改动接受另一轮有范围的检查。

#### 能帮你完成什么

审查关注可复现缺陷、用户影响、无关改动和未经证据支持的复杂度。复杂任务需要时安排独立 QA，主 Agent 验证发现、处理范围内问题，并复验修复，而不是原样转发审查意见。

#### 使用前

给出审查目标、候选改动和验证记录。独立 Agent 是否可用取决于宿主工具。

#### 怎么使用

1. 明确“只审查”还是允许修复，以及这次不检查的范围。
2. 候选实现和相关测试完成后提交给审查者。
3. 按严重性处理可复现发现，保留未解决问题与限制。

#### 试着这样对 Agent 说

```text
请只审查本次报修权限改动，不修改代码。按严重程度列出可复现问题、受影响场景和定位；没有发现问题时说明检查范围及剩余风险。
```

#### 如何判断完成

- 有位置和复现场景的发现，或有边界的未发现问题结论。
- 修复任务有对应的直接验证结果。

#### 适用边界

- 独立审查不是无限安全认证，理论上可想象的风险不能自动扩大已确认范围。

### Git、版本与交付说明

让改动可以追溯、审阅和回退。

#### 能帮你完成什么

标准指导 Agent 先看已有改动，按职责提交，维护功能版本和 Change Log，写清 PR 的问题、结果、验证和风险。每段 diff 应能解释与任务目标的关系。

#### 使用前

项目使用 Git；若仓库有自己的版本约定，先遵循项目约定。

#### 怎么使用

1. 修改前确认分支和未提交内容。
2. 完成相关验证后审查 diff，仅提交本次已授权的文件。
3. 为功能变化维护版本记录，发布前提供准确升级和回退说明。

#### 试着这样对 Agent 说

```text
请整理本次报修功能的提交和 PR 说明：先说明用户行为变化，再写验证与限制；不要混入我尚未提交的其他改动。
```

#### 如何判断完成

- 范围清楚的提交与可审阅的变更说明。
- 版本、发布产物和源代码之间可以追溯。

#### 适用边界

- 本地提交不等于 GitHub 发布，GitHub 发布也不等于服务器部署。
- 远端推送、正式发布、标签和部署遵循当前任务的具体授权。

## 任务推进与经验复用

在多阶段工作中保留决定、分配职责，并按需读取标准。

### 按任务读取需要的标准

简单任务保持轻量，复杂工作分阶段推进。

#### 能帮你完成什么

Core 先区分讨论、产品澄清、新项目初始化、小改动、功能实现、复杂交付和审查，再选择当前阶段需要的标准。架构、前端、后端、规则融合、Agent 接入和 Skill 推荐按需补充。

#### 使用前

明确本次是讨论、实现还是审查，以及哪些事情暂时不要执行。

#### 怎么使用

1. 用自然语言描述实际意图，不必自己记住 Profile 名称。
2. 只讨论时明确说明；从讨论进入开发时确认新的目标。
3. 复杂任务按当前阶段加载内容，遇到范围变化重新说明。

#### 试着这样对 Agent 说

```text
这次先讨论报修通知方案，不写代码、不安装工具。比较体验和维护成本，并指出需要我决定的事项。
```

#### 如何判断完成

- 讨论不创建执行状态或直接实施。
- 普通任务不会每次读取全部 Core；必要决定和交接才记录状态。

#### 适用边界

- 选择性加载降低无关上下文，但不承诺固定 Token 节省比例。
- 标准路由不能代替模型判断与用户授权。

### 并行开发与集中验收

在宿主支持时让多个 Agent 按明确边界合作。

#### 能帮你完成什么

复杂任务先划分工作单元、依赖、验收条件和写入范围，再把独立部分交给合适的 Agent。主 Agent 负责合同、集成与最终判断。成本和并发上限可以在任务中明确，简单问题不必使用多代理。

#### 使用前

任务确实有可以独立推进的部分；宿主提供子代理能力，并已得到所需并行授权。

#### 怎么使用

1. 确定共同完成定义、责任人和不能同时修改的文件。
2. 指定模型或成本要求、并发上限与各自交付物。
3. 子任务完成后先做集成验证，再按需要做独立 QA 和最终回归。

#### 试着这样对 Agent 说

```text
这个功能分为 API 和前端两部分。若当前工具支持子代理，请用合适模型并行实现，最多两个子代理，先固定接口，由主 Agent 统一验收合并。
```

#### 如何判断完成

- 每个任务有输入、输出、负责人和验收依据。
- 最终结果包含跨模块验证，而不仅是各代理“完成”的汇报。

#### 适用边界

- Build 提供协作标准，不另建常驻代理服务或自动购买模型。
- 并行授权不自动包含发布、服务器操作或数据删除。

### 项目记忆、检查点与交接

换任务或换 Agent 后仍能继续已确认的工作。

#### 能帮你完成什么

重要产品决定、阶段进度、阻塞和验证证据保存在项目资料中。需要状态的任务使用经过校验的摘要，记录已加载规则和下一步，不把整段聊天原文复制为项目记忆。

#### 使用前

已有明确任务和项目资料位置；普通问答和孤立小改动通常不需要新的状态文件。

#### 怎么使用

1. 在重要阶段请 Agent 记录已确认决定、完成项、阻塞和下一步。
2. 换任务时让新 Agent 读取这些资料并核对当前代码事实。
3. 恢复时引用已确认计划，只有新事实使其失效才调整相应范围。

#### 试着这样对 Agent 说

```text
请为当前报修项目整理交接：目标、已经确认的决定、真实完成项、未解决问题、验证结果和下一步。不要把猜测或聊天原文当作事实。
```

#### 如何判断完成

- 后续 Agent 能定位当前阶段和应继续的工作。
- 状态不包含凭据、私有内容或未确认决定。

#### 适用边界

- 记录不会让新模型自动拥有上一任务的全部上下文；恢复仍需核对资料和代码。

### 复盘与经验回流

把反复出现的问题整理为可复用规则或模块。

#### 能帮你完成什么

项目特有决定留在项目中；确实可复用的经验先总结问题、适用条件、步骤和验证方法，再经过审阅进入通用标准或独立模块。模块化让内容后续可以独立维护，而不是每次改动整个基础插件。

#### 使用前

已有真实案例或反复出现的工作模式；经验资料不能包含凭据和客户私密信息。

#### 怎么使用

1. 用复盘模板记录最慢环节、判断失误和有效验证。
2. 区分项目例外与适用于多个项目的规则。
3. 需要独立能力时按模块协议提出内容、阶段、版本和测试，不直接修改已安装缓存。

#### 试着这样对 Agent 说

```text
请复盘这次跨项目通知联调，提炼适用条件、常见失败、验证办法和可复用模板。先区分项目特有规则与可以做成独立模块的经验。
```

#### 如何判断完成

- 可以审阅的经验候选及适用范围。
- 通用标准或模块的更改有对应版本与验证。

#### 适用边界

- 把文档写出来并不等于已经成为可安装模块；仍需声明、打包、校验和发布。

## 独立能力模块

按需安装工作方法，在兼容范围内单独更新。

首模块下载：https://motux.app/motux-build/capabilities/artifacts/joint-delivery/0.1.0/74cc7fe23150a9adf2839861dce7637963120b62d17101cd6c2f1ab37ab36a75.json

joint-delivery 0.1.0：10,032 字节；SHA-256：74cc7fe23150a9adf2839861dce7637963120b62d17101cd6c2f1ab37ab36a75。指定精确校验值导入；签名模块网络目录尚未上线。

### 检查与安装独立模块

增加一份经过校验的工作方法。

#### 能帮你完成什么

模块有自己的 ID、版本、内容校验值和基础组件要求。首次使用模块机制需要 Core 1.0.98 / Manager 0.1.29 或兼容新版；之后兼容的模块内容可以单独安装或更新。模块只有声明式 Markdown、JSON、TXT 资源，不运行安装脚本或 Hook。

#### 使用前

项目已明确采用有效的 user 或完整 local 安装；Node 已可用。disabled、undecided、conflict 不直接进入安装。

#### 怎么使用

1. 点名模块、版本和来源，让 Manager 先 check；本地审阅包必须提供完整 SHA-256。
2. 确认安装范围：local 保存在项目内，user 存储供用户级项目选择。
3. 校验大小、身份、资源和兼容性通过后安装；安装完成再决定是否在项目启用。

#### 试着这样对 Agent 说

```text
请检查 joint-delivery 0.1.0 的已发布模块包是否与当前 Build 兼容。先说明安装范围、来源和 SHA-256，确认具体包后再安装。
```

#### 如何判断完成

- 安装得到不可变的模块内容身份和状态。
- 其他模块、基础插件和项目文档不会因这次安装被替换。

#### 适用边界

- 当前公开首模块使用下载后指定精确 SHA-256 的导入方式。
- 签名网络模块目录尚未上线；未签名 candidate 不能作为可信安装目录。

### 启用、固定版本与停用

决定哪个项目实际使用已安装模块。

#### 能帮你完成什么

模块安装与项目选择分开。follow 会在后续新任务中使用存储的当前版本；固定版本会同时指定版本与 SHA-256。停用仅改变当前项目选择，保留模块包和已经生成的计划、验收资料。

#### 使用前

模块已经安装并校验通过，当前项目采用有效安装范围。

#### 怎么使用

1. 确认要启用的模块及当前版本。
2. 选择跟随更新或固定精确版本，再写入当前项目选择。
3. 让 Manager resolve 验证；不需要时明确停用该项目的模块。

#### 试着这样对 Agent 说

```text
在当前项目启用已经安装的 joint-delivery。先显示版本和校验值，我希望固定这一个版本；不要替其他项目启用。
```

#### 如何判断完成

- CAPABILITIES.json 只改变被选择模块的记录。
- 已安装但未启用的模块不会被 Core 当作当前任务输入。

#### 适用边界

- 已开始的任务保留自己的模块内容身份，不因 follow 更新在中途换成新内容。
- 禁用后旧任务不能继续解析这个已被禁用的模块，需明确恢复选择。

### 单独更新与回退模块

更新所选内容，保留其他模块和已有任务。

#### 能帮你完成什么

Manager 为每个模块保留不可变内容、current 和 previous 记录。升级只替换选中模块的当前身份；旧任务仍可以核验自己保存的版本。回退交换该模块 current/previous，并保留两份内容。

#### 使用前

模块已安装；要更新的包有明确身份且与当前底座兼容；回退需要有效 previous。

#### 怎么使用

1. 先 inspect/check，查看当前、目标和完整性。
2. 明确只更新这个模块，验证后再应用。
3. 出现问题时请求回退并检查项目是否固定版本；必要时单独调整项目选择。

#### 试着这样对 Agent 说

```text
检查 joint-delivery 的已安装版本和我提供的新包。若兼容，请只更新这个模块，保留其他模块和已有任务的版本；完成后说明回退入口。
```

#### 如何判断完成

- 只有该模块记录变化，基础 Plugin 无需因为兼容内容更新而重新安装。
- 可以查看升级前后身份，并说明固定选择是否仍指向旧版。

#### 适用边界

- 回退存储不会偷偷改写项目的固定版本选择。
- 资源被修改、缺失或兼容性不满足时会阻断更新。

### 处理中断与锁冲突

在不猜测原始状态的前提下恢复模块事务。

#### 能帮你完成什么

普通 recover 根据记录验证旧状态或新状态，完成可以明确判断的中断事务。锁被活跃进程持有时等待或停止；异常锁维护需要先停止所有相关写入者，核对准确所有者，再执行明确的离线操作。

#### 使用前

存在真实中断或锁错误。保留原始状态和错误信息，不先删除目录。

#### 怎么使用

1. 让 Agent 只读 inspect 和 locks，定位模块、事务和锁。
2. 有完整且可验证的事务记录时，按 Manager recover 处理。
3. 所有者缺失、记录损坏或状态模糊时，停止写入并人工检查；仅在明确离线维护条件后使用 recover-locks。

#### 试着这样对 Agent 说

```text
模块更新中断了。请先只读检查事务和锁，说明是否仍有写入者。不要直接删锁或模块目录，只对可以验证的中断事务提出恢复步骤。
```

#### 如何判断完成

- 得到可恢复、仍在使用或需要人工检查的明确判断。
- 恢复完成后重新核验内容和状态。

#### 适用边界

- 不承诺任意崩溃点都自动恢复；不支持跨主机共享文件系统锁。

### 联合开发统筹模块

把多个项目连成一个可联合验收的业务流程。

#### 能帮你完成什么

joint-delivery 0.1.0 是首个独立模块。prepare 负责共同目标、项目边界、事实归属、接口和依赖；coordinate 负责拆任务、交接和变更影响；verify 负责按版本组合验证整条链路。它提供指南与模板，不连接仓库或自动替你调度其他项目。

#### 使用前

已安装并在当前统筹项目启用 joint-delivery；知道涉及的项目、共同目标和资料归属。

#### 怎么使用

1. 准备：列出各项目负责的事实、接口版本、共同样例、依赖与验收负责人，形成联合计划。
2. 协调：给提供者和消费者明确任务合同、完成证据及交接；接口变化时列出受影响项目。
3. 联合验收：固定参与版本，从头走成功、拒绝、重复请求、超时和恢复，记录真实证据。

#### 试着这样对 Agent 说

```text
使用 joint-delivery 的 prepare 阶段。我们的申请系统、审批系统、展示系统要完成同一条流程，请整理共同目标、事实归属、接口样例、依赖和联合验收计划。
```

#### 如何判断完成

- joint-plan、task-handoff、joint-acceptance 模板帮助记录计划、交接和验收。
- 例如审批成功但展示仍是旧状态，应判定联合验收未通过。

#### 适用边界

- 示例是“申请 → 审批 → 展示”，不是已部署的示范系统。
- 三个项目各自测试通过，不能代替端到端联合验证。
- 后续明确需要 coordinate 或 verify 时才加载该阶段。

## 第三方 Skill 管理

在明确能力缺口时推荐工具，并按选择安装和维护。

### 推荐、跳过与抑制推荐

让专用工具在有帮助时出现。

#### 能帮你完成什么

Skill Advisor 使用受审核的签名 Skill 目录，在当前任务确实缺少专用能力时匹配兼容工具。Agent 解释理由、来源、用途、权限和代价，用户可以安装、跳过或抑制某项推荐。无需每次任务都检查目录。

#### 使用前

存在相关能力缺口；目录可用且仍在有效期，当前 Agent 有受支持的安装方法。

#### 怎么使用

1. 描述具体任务，要求先比较当前工具与候选 Skill。
2. 查看一个最相关推荐的来源、作用、风险和替代方案。
3. 选择安装、跳过，或说明在当前范围内不要再推荐，并由 Agent 解释记录方式。

#### 试着这样对 Agent 说

```text
现在需要检查前端表单的手机体验。请判断现有能力是否足够，只在有明显收益时推荐一个兼容、受审核的 Skill，先说明收益与代价。
```

#### 如何判断完成

- 有理由的建议或“无需新增工具”的结论。
- 拒绝或抑制后按相应范围减少重复打扰。

#### 适用边界

- motux-reviewed 表示指定安装边界经过审阅，不是全面安全审计或质量保证。
- Skill 目录与独立能力模块目录不同，不能互换签名和安装包。

### 安装已选择的 Skill

校验固定来源后复制明确的 Skill 内容。

#### 能帮你完成什么

Manager 核验目录签名、有效期、版本回退保护、固定源归档和文件审查清单，再把声明的 Skill 复制到允许位置。当前受支持的安装路径是 Codex 项目级 .agents/skills/<skill-id>，不等于在所有宿主上自动安装。

#### 使用前

你已选择目录中 active、兼容且受审核的具体条目，并明确 Agent、项目和安装范围。

#### 怎么使用

1. 让 Agent 展示准确条目、固定来源、权限和目标路径。
2. 确认该安装后执行验证与复制，不运行第三方安装器。
3. 检查 Skill 的记录和发现情况，按宿主要求重开任务。

#### 试着这样对 Agent 说

```text
我选择刚才推荐的 Skill。请先列出准确目录条目、固定版本、权限和当前项目安装路径，校验后只安装这个 Skill。
```

#### 如何判断完成

- 声明文件被锁定记录，后续状态检查可判断是否修改。
- 安装结果说明是否还需要重新打开任务。

#### 适用边界

- 未经认证、过期、校验不符或不兼容的来源不安装。
- 不会自动执行第三方脚本、启用 Hooks 或覆盖用户现有规则。

### 检查、更新和移除 Skill

保留修改痕迹，按精确内容管理已安装工具。

#### 能帮你完成什么

Skill status 核对锁定身份、实际文件和发现情况；更新验证目标条目与现有内容；移除只处理已记录且完整的安装。文件被修改或状态不完整时，先说明冲突和恢复办法。

#### 使用前

这个 Skill 由 Manager 管理，保留安装记录；明确本次是只读、更新还是移除。

#### 怎么使用

1. 先只读检查来源、版本、完整性及项目状态。
2. 更新时明确目标和差异，验证后应用。
3. 移除时点名 Skill，确认范围；保留项目产物和不是它拥有的文件。

#### 试着这样对 Agent 说

```text
请检查本项目由 Motux Manager 安装的 Skill。先报告版本和完整性，不更新；若存在本地修改，说明如何保留后再维护。
```

#### 如何判断完成

- 每个受管理 Skill 的身份与差异清楚。
- 失败和中断由对应事务记录处理，而非盲目重装。

#### 适用边界

- 不扫描或接管所有第三方插件，也不把用户自行安装的 Skill 当成可直接删除的受管理内容。

## 更新、体检与恢复

根据安装范围更新正确的一份 Build。

### 只读检查更新

先看哪些版本可用，再决定是否应用。

#### 能帮你完成什么

检查公开稳定清单、比较当前和目标版本、查看兼容性及变更说明。项目安装还需要识别规则融合状态和入口是否修改。只读检查不会创建更新计划、替换组件或安装模块。

#### 使用前

先确认当前使用用户插件还是项目内安装；检查最新公开清单需要网络。

#### 怎么使用

1. 在目标项目明确说“只检查，不更新”。
2. 查看安装来源、候选版本、兼容性和阻断原因。
3. 选定更新路径后再提出对应的更新请求。

#### 试着这样对 Agent 说

```text
只检查 Motux Build 更新，不安装。请报告当前来源、组件版本、可用版本和兼容性；如需要先处理项目规则或入口冲突，请说明。
```

#### 如何判断完成

- 明确的版本对比和是否可更新的判断。
- 没有因检查而修改项目或插件。

#### 适用边界

- 没有网络时不能把缓存清单冒充最新版本。

### 更新或修复本机插件

让共享 Codex 插件使用已验证的正式版本。

#### 能帮你完成什么

用户级更新替换同一个 marketplace 的当前 Plugin 源，并由 Codex 重装同一 selector；新任务使用新缓存。修复针对准确的既有源和缓存，不迁移任何项目。项目中的最小选择不记录 Plugin 版本。

#### 使用前

已安装 motux-build@motux，且明确要求用户级更新或修复。

#### 怎么使用

1. 请求比较公开 Plugin 版本和本机实际安装。
2. 验证包后更新现有源；比较新旧 Hook，变化时需要重新审查。
3. 确认列表中的 installed/enabled 版本，新开任务核验发现。

#### 试着这样对 Agent 说

```text
请更新本机用户级 Motux Build 插件到正式稳定版。校验包和现有安装源，保留同一 motux-build@motux 身份，完成后验证新版发现。
```

#### 如何判断完成

- 本机只有同一份配置身份指向当前正式 Plugin。
- 相同且完整版本为无需更新；Hook 不变时复用既有信任决定。

#### 适用边界

- 项目内安装不随用户插件更新。
- 没有后台自动更新器或用户级全局版本回退入口；旧任务可能仍保留已加载版本。

### 一次完成合格的项目补丁更新

所有固定条件满足时，用短指令完成更新。

#### 能帮你完成什么

对于支持 safe update 的完整项目安装，“更新 Motux Build”授权一次稳定补丁尝试。Manager 核验组件完整性、最终兼容组合、规则和入口边界，先验证全部候选再应用；不满足任一门槛时保持零写入并说明原因。

#### 使用前

完整 schema-2 项目安装，Manager 至少 0.1.25，受管理文件未改动，目标为允许的同一 major/minor 补丁，且没有迁移或未解决规则冲突。

#### 怎么使用

1. 先确认当前项目确实使用项目内 Build。
2. 明确请求安全更新；Agent 通过固定 preflight 确定范围。
3. 全部通过后更新被选组件，必要时先完成 Manager 交接，再验证并记录。

#### 试着这样对 Agent 说

```text
更新当前项目内的 Motux Build，按 safe update 固定策略尝试稳定补丁。若不满足条件，保持零写入并说明需要改走哪条流程。
```

#### 如何判断完成

- 成功时得到组件前后版本、验证和可追溯记录。
- 阻断时说明原因，并提供只读检查或普通更新计划入口。

#### 适用边界

- 不包括主/次版本升级、布局迁移、桥接改写、业务代码、额外 Agent 或新产品。
- Manager 0.1.24 及更早版本需先走普通受控更新。

### 按组件计划更新

处理需要明确选择和预览的项目更新。

#### 能帮你完成什么

普通更新分为 check、plan 和 apply。计划列出组件、版本、文件范围、完整性、受影响规则、验证与回退；用户确认后才应用。Core 变化时按已采用版本进行增量规则复查。

#### 使用前

项目内安装可被 Manager 识别；你知道想更新的组件或愿意先只读检查。

#### 怎么使用

1. 先检查，再生成组件明确的更新计划。
2. 解决受影响的规则冲突和授权范围；必要时只更新可独立处理的 Manager 或 Brief。
3. 确认具体计划后 apply，体检并维护对应更新记录。

#### 试着这样对 Agent 说

```text
请为当前项目生成普通 Motux 更新计划，分别列出 Manager、Core、Brief 的目标版本、影响文件、项目规则冲突、验证和回退。先不应用。
```

#### 如何判断完成

- 可审阅的更新计划与明确的确认对象。
- 业务文件、项目 overrides 和未选入口保持由各自流程维护。

#### 适用边界

- 计划不是已经应用；不能跳过受管理文件被修改或 Core 规则冲突。

### 体检、修复判断与项目回退

在出现异常时先定位，再选择恢复方式。

#### 能帮你完成什么

doctor 检查命名空间、配置、锁、组件文件、产品入口和已记录桥接。它报告问题与修复计划，不能把读状态当作修复授权。项目更新回退优先撤销独立 Motux 更新提交；无 Git 时只按以前记录的已校验产物恢复。

#### 使用前

尽量保留错误、当前文件和更新记录；不要先删 .motux 再尝试。

#### 怎么使用

1. 请求只读体检，区分完整性问题、入口问题和业务问题。
2. 查看准确恢复范围；有本地修改时先决定如何保留。
3. 明确确认修复或回退后执行，再复验组件与加载状态。

#### 试着这样对 Agent 说

```text
更新后 Agent 找不到 Build。请先运行只读体检，区分组件损坏与入口未加载；给出最小修复或回退方案，不要先删除安装目录。
```

#### 如何判断完成

- 明确问题归属以及需要重开任务、修复入口或回退的理由。
- 恢复后既核验文件，也核验当前 Agent 的入口。

#### 适用边界

- Build 体检不是对业务系统、服务器或账户的全面健康检查。
- 插件修复、项目组件回退和独立模块回退是不同操作。

### 旧布局与早期 Motux Dev

按实际历史版本选择专门的迁移路径。

#### 能帮你完成什么

Manager 对可识别旧布局先生成迁移计划，而不是直接替换组件。更早的 Motux Dev 使用独立支持包，先核验完整版本指纹，再形成绑定目标的计划和恢复方案；普通安装与安全更新不自动进入它。

#### 使用前

项目确实安装了可验证的旧版本，而不仅是出现名称类似的目录。

#### 怎么使用

1. 先只读识别现有安装，不复制新规则到旧目录。
2. 根据结果使用普通旧布局迁移或官网“早期版本支持”说明。
3. 审阅具体计划，单独确认后迁移，并核验新状态与保留的恢复材料。

#### 试着这样对 Agent 说

```text
这个项目可能使用早期 Motux Dev。请先只读识别，若普通 Manager 不支持，指向官网的独立支持流程，不自动迁移或删除旧内容。
```

#### 如何判断完成

- 明确是受支持旧布局、早期 Dev，还是未知/外来状态。
- 支持路径与普通更新清楚分开。

#### 适用边界

- 名称相似不构成版本证明；未知 .motux 冲突不能强行升级。

## 附录与问题排查

需要时再查术语、目录和故障处理。

### 自然语言与命令名称

把示例交给 Agent，不必安装一个 motux 全局 CLI。

#### 能帮你完成什么

本手册的大多数“命令”是 Manager 工作流名称，由 Agent 从当前安装的 Skill 中执行。onboard、doctor、adapter plan、skill install 并不意味着终端存在同名全局可执行程序。少数确定性工具，例如模块管理器，才有明确的 Node 入口。

#### 使用前

在目标项目中操作，并让 Agent 解析当前有效安装来源。

#### 怎么使用

1. 日常使用优先复制对应功能的自然语言示例。
2. 让 Agent 根据 user/local 分类解析 family root，不手写某个旧缓存版本。
3. 需要终端细节时，要求给出当前机器核验过的完整路径及参数。

#### 试着这样对 Agent 说

```text
请将“只读检查当前模块”转换为这台机器可执行的准确命令，先确认 family root、Node 和项目范围，不要猜测插件缓存路径。
```

#### 如何判断完成

- 项目模式的模块工具位于 .motux/manager/runtime/capability-manager.mjs；用户模式由已安装 Plugin/runtime/manager 提供。
- 模块操作包括 inspect、check、install、update、enable、disable、rollback、resolve、recover、locks、recover-locks。

#### 适用边界

- 示例中的文件位置和模块来源需要核实，不能把工作流名称直接当 shell 命令运行。

### 文件归属与术语

知道资料存在哪里，什么不该直接改。

#### 能帮你完成什么

用户模式：只读规则在 Codex 插件，项目的 .motux/motux.json 保存选择；独立模块用户存储在用户主目录的 .motux/capabilities。项目模式：Manager、锁及 Core/Brief managed 内容在项目 .motux；项目例外在 overrides。Brief 与产品、交接文档仍属于当前项目。

#### 使用前

先确认 user/local 分类。family root 表示当前有效的组件根，不能固定为所有机器上的某个路径。

#### 怎么使用

1. 用状态检查获得当前来源和实际位置。
2. 项目偏好写入项目规则，通用经验以源代码变更或独立模块维护。
3. 遇到错误先检查锁和证据，不直接编辑 managed、不可变模块包或 Plugin 缓存。

#### 试着这样对 Agent 说

```text
请说明当前项目的产品文档、项目覆盖规则、Build 组件、模块包分别保存在哪里，只列归属和用途，不读取私有资料。
```

#### 如何判断完成

- Core：通用标准；Manager：生命周期管理；Brief：本地决策表单。
- Profile：任务类型；Hook：宿主启动事件处理；SHA-256：精确文件内容校验值。
- 安装：文件已取得；启用：项目已选择；激活/发现：当前宿主可以实际加载。

#### 适用边界

- 校验值证明内容是否相同，不单独证明来源可信；来源信任与内容校验都要处理。

### 常见问题的最短处理路径

从现象出发，避免反复重装。

#### 能帮你完成什么

安装后没生效：先检查来源和发现，再新开任务。更新提示 blocked：看修改、兼容性或未确认决定。模块“装了没反应”：检查项目启用和当前阶段请求。Brief 保存不了：用下载方式并放到页面指定路径。目录不可用：保留任务继续用已有能力，不跳过认证。

#### 使用前

保留错误类别、涉及操作与非敏感版本信息。不要发送密钥或完整私有配置。

#### 怎么使用

1. 明确刚执行的是安装、启用、更新还是只读检查。
2. 先检查与该操作直接相关的状态，避免扫描整机项目。
3. 按结果选择重新打开任务、补全选择、预览修复或停止并人工处理。

#### 试着这样对 Agent 说

```text
我已经安装 joint-delivery，但本项目没有使用它。请只检查项目是否启用、版本是否兼容、当前任务是否选择了正确阶段，不重新安装底座。
```

#### 如何判断完成

- 问题被定位到来源、状态、兼容性、授权或宿主发现中的具体一项。
- 下一步有明确目标和停止条件。

#### 适用边界

- 没有通用“删除所有锁/缓存再试”的恢复方法。
- 功能自动生效仍受宿主能力、权限和当前项目规则约束。