wiki-writer

name	wiki-writer
description	编写、重写、审阅和中英同步 docs/wiki 下的 Jugg 用户文档。适用于实现原理、能力、使用指南、问题排查和参考页面，将源码、ai_knowledge、历史资料提炼为面向普通 Android 开发者的 Wiki 内容，以及以中文页面为唯一内容基准生成或更新严格镜像的英文页面。不要用于 docs/ai_knowledge 日常维护、任务方案、版本日志或 Jugg Wiki 之外的 Markdown。

Jugg Wiki 写作

编写能够说明真实工程问题、Jugg 方案选择和用户可见结果的 Wiki。优先建立简洁的因果链，不要罗列实现组件。

读取最小权威上下文

读取或编辑实现代码前，先遵守仓库 AGENTS.md 的强制工作流。

1. 当前会话尚未读取时，先读 docs/ai_knowledge/00_overview.md 和 docs/ai_knowledge/99_index.md。
2. 读取 docs/ai_knowledge/98_code_map.md，定位行为 owner。
3. 读取 docs/ai_knowledge/10_wiki_authoring.md 和 docs/ai_knowledge/10_wiki_architecture.md。
4. 读取目标页面及其目录层级中最近的 index.md。只有最近索引无法确定页面职责或导航上下文时，才继续读取更高层索引。
5. 同一主题存在同语言的 concept 或 capability 页面时一并读取。目标页面横跨多个独立主题时，分别读取每个主题的配对页面，并判断是否需要拆页。
6. 按 99_index.md 选择与当前主题直接相关的 docs/ai_knowledge 专题，禁止一次性加载整个知识库。

文章涉及产品行为、兼容差异或失败恢复时，必须核对当前实现，不能只依赖文档。代码调查只围绕行为 owner 和准备写入文章的事实展开。

中译英任务例外：中文 Wiki 是唯一内容基准，直接翻译目标中文页面，不重新读取专题文档或实现核对其中的产品事实。发现中文页面内部矛盾、链接失效或无法确定原意时，报告问题并停止扩大解释，不自行修正或补充事实。

使用历史资料

把历史文章、分享稿、演示文档和截图视为问题背景与设计过程的补充材料，使用前逐项核对：

• 当前实现是否仍采用相同方案。
• 支持范围和限制是否已经变化。
• 文中的“正在开发”“暂不支持”等状态是否过期。
• 性能数字是否有可复现的测试上下文。
• 故障现象和方案取舍是否仍能由当前事实支撑。

没有历史资料时，不要编造设计动机、备选方案或性能收益。优先从当前代码、专题文档、日志、稳定复现和已有用户现象中建立问题链。源码注释和实现约束可以说明当前机制为什么需要某个处理，但不能据此外推最初的决策过程、完整替代方案比较或历史收益。证据只能说明“当前怎么做”时，就不要补写未经证实的“当初为什么这样做”。

历史资料中经过当前实现核验、且对后续任务仍有长期价值的设计意图或失败模式，如果尚未记录在 docs/ai_knowledge，在交付结论中列为知识库同步候选。除非用户明确要求，不要在 Wiki 写作任务中自动扩大范围去维护 ai_knowledge。

判定页面职责

先根据读者问题确定页面类型：

页面类型	读者问题	内容重点
concepts	为什么需要这套机制，它怎样保持正确？	问题成因、朴素方案缺口、Jugg 机制、状态或数据流、取舍与边界
capabilities	我的修改是否支持，会看到什么结果？	支持范围、触发条件、用户可见结果、前置条件、回退和相关原理
guide	我现在应该怎么操作？	有顺序的操作、预期结果、决策点和安全恢复方式
troubleshooting	出现这个现象，下一步检查什么？	可观察现象、可能命中的边界、第一跳诊断和恢复入口
reference	稳定事实或契约是什么？	精确参数、状态、格式、约束和解释页面链接

不要让 capability 页面换一种说法重复 concept 页面。能力页只保留简短的“触发到结果”流程，机制细节链接到 concept 页面。

已有路由承担外部入口时，兼容入口必须同时存在中英文镜像；不得只为单一语言保留额外页面。

执行写前结构审计

编辑前用一至三句话或几个要点明确页面主线，仅供写作过程使用，并完成以下检查：

1. 页面类型与命名：确认读者是在理解机制、判断支持范围、执行操作还是排查现象。concepts 标题优先命名机制、状态模型或处理流程；谨慎使用“如何……”“什么时候……”“怎么办”等操作型标题。标题暗示用户采取行动时，重新判断页面是否应放在 guide 或 troubleshooting。改名必须同步检查 frontmatter、H1、目录文字、正文链接名称和首页 CTA。
2. 引言价值：concept 页前两段应让读者知道开发者做了什么修改、完整构建通常处理哪些工作、Jugg 为什么需要单独处理这项变化，以及本页解释什么用户可见结果。避免用连续的“不是、不会、并非、无需”建立主线；否定句只用于纠正常见误解。
3. 基础机制与 Jugg 差异：当 Jugg 绕过、替换或复用 Android 标准构建环节时，先用最少篇幅说明标准输入、处理工具和产物，再说明 Jugg 改变了哪一步。不能用“Jugg 不经过 X”作为叙事起点，除非正文已经解释正常情况下哪些内容会经过 X。先讲编译和打包机制，再讲最终如何部署或生效。
4. 复用边界：正文出现“复用、替代、绕过、接管”时，明确具体机制、原有行为 owner 和 Jugg 新增的职责。叙述主体变化后，不用“这套能力”“这条链路”等指代替代明确对象。
5. 拆页边界：主题相邻不等于属于同一页。比较行为 owner、复用产物、修改状态和处理结果：

判断项	需要确认什么
行为 owner	由编译、部署、设备恢复还是 Run 编排负责
复用产物	是否继续使用当前编译或部署产物
修改状态	改变传输条件、设备状态还是构建基线
处理结果	重试当前步骤、扩大恢复范围还是切换阶段

这些项目明显不同时，即使机制在同一条失败流程中连续出现，也应拆页。任一主题能独立形成“问题、机制、边界”论证时，不要用“回退”“鲁棒性”等抽象主题强行合并。

根据读者前置知识选择叙事起点：熟悉基础机制且存在真实故障时，可以从具体修改、遗漏状态和用户可见结果切入；缺少背景时，先建立标准工作模式。比较表和完整流程只在存在真实映射或多个依赖阶段时使用。

标题要直接描述内容。不要用“背景”“痛点”“核心解法”“方案价值”“边界与代价”等元结构标题代替具体问题。准备写入的主张无法由当前文档、代码、日志或稳定复现支撑时，不要扩大结论。

以下工程事实能够解释用户行为时，优先提炼为正文：

• 深度定制，例如隔离编译器运行环境、定制 aapt2 或自有 JVMTI Agent。
• 环境冲突，例如 Android Studio、JBR、AGP、设备或厂商系统差异。
• 时序与依赖冲突，例如生成源码、旧符号、Gradle 基线和运行时结构对齐。
• 失败收口，例如改变失败条件的有限重试和明确的 Gradle 回退。

不要把每个内部 workaround 都扩写成章节。它必须能够解释用户可见差异、容易误判的约束或真实的方案选择。

用证据和失败场景推动叙述

存在真实故障时，加入一个紧凑的失败链：

A 删除方法或修改字段类型
  -> 未修改的 B 没有参与编译
  -> 本轮局部编译成功
  -> APK 中仍保留旧调用
  -> 运行时出现 NoSuchMethodError 或 NoSuchFieldError

失败场景用于解释机制为什么存在。不要先虚构一个明显错误的实现，再用它证明 Jugg 更好。

不要把一个本来需要多个阶段协作的完整外部机制，拆成“只处理其中一步”的半成品流程，再用该半成品的失败建立论点。只有这种局部流程是真实实现选择、历史方案或稳定复现时，才将它作为失败案例。

解释重要选择时写清四件事：

• 更简单的方案会做什么。
• 它会产生什么可观察失败或成本。
• 当前 Jugg 方案为什么更适合实际环境。
• 什么条件会触发回退。

只有性能证据包含测量对象、代表性工程或输入规模、机器与环境、工具版本、采样方法和统计结果时，才能引用具体数字。多个 Wiki 页面重复同一个数字不算独立证据。缺少这些信息时，只说明减少或收窄了哪些工作，不写精确收益。

保持正式 Wiki 的用户视角

保留或补充有效 frontmatter，每页只保留一个 H1。修改已有页面时，默认保留 frontmatter.title 和 H1；只有用户明确要求改名，或标题与页面职责明显冲突并得到确认后才修改。

H1 与首个 H2 之间必须有独立入口段，优先补齐读者理解正文所缺少的信息。读者熟悉基础机制且页面围绕真实失败展开时，入口可以说明具体操作、用户可见结果和 Jugg 的处理方式；读者不熟悉基础机制时，先说明标准工作模式和 Jugg 改变的环节。具体失败可以随后展开，不强制占据开场。

正式页面可以使用普通 Android 开发者熟悉的概念，例如 Gradle、D8、DEX、aapt2、Manifest、JVMTI、classpath、NoSuchMethodError 和 minSdk。

不要暴露维护者视角：

• 源码路径、包名、内部类、方法、字段或行号。
• 不包含业务决策或状态变化的机械调用顺序。
• 测试 owner、数据库表名、临时目录和内部缓存实现名。
• 已经过期的“正在开发”或“暂不支持”状态。

把实现事实翻译为机制。例如：

• 较弱：“编译器隔离类创建一个 ClassLoader。”
• 更好：“IDE 与编译器可能包含包名相同但版本不同的实现，因此 Jugg 在隔离环境中加载编译器。”

表格只用于真实映射或比较，文本流程只用于存在多个依赖阶段的顺序。不要添加装饰性图示或重复总结。

事实稳定后再整理语言

使用直接、克制的技术语言，让具体事实承担论证。

• 删除宣传性表述、模糊的重要性宣告、填充连接词和泛化结论。
• 避免反复使用“不仅……而且……”“这不仅是……而是……”、三段式口号和大量粗体。
• 不写“确保正确性”，改为具体说明被保护的状态、产物或失败边界。
• 不写“可能有问题”，改为触发条件和用户可见结果。
• 描述能力边界时区分“不支持”“被忽略”和“失败后回退”。操作被忽略时，先写明本轮不会产生什么变化、旧状态是否继续存在或可访问，再把完整构建、重装等作为让目标变化真正生效的后续方式；不要只写“需要完整构建”，以免读者误以为当前操作会失败或立即回退。
• 出现“契约、保障、上下文、一致性、能力、链路”等抽象词时，检查它是否隐藏了可以直接说明的对象或结果；能写成方法签名、字段类型、继承结构、DEX 引用、Gradle 构建产物或运行时异常时，优先使用具体概念。这些词有明确技术含义时可以保留，不作为禁词。
• 一个段落只处理一个主要判断，在决策边界处分段。
• 与相邻 Wiki 页面保持术语一致。
• 不为了变化句式而替换已经准确、统一的技术术语。
• 不加入第一人称、幽默、情绪、个性化表达、题外内容或聊天回复痕迹。

本节是正式 Wiki 的完整语言门禁。默认不要加载通用文本润色 skill；只有用户明确要求时才额外使用，并以本 skill 的技术精度、正式语气和术语一致性要求为准。语言清理不得改变事实、适用条件、状态语义和用户可见结果。

执行中译英

中文页面是英文页面的唯一内容基准。英文页面必须保持相同的相对路径、页面类型、章节顺序、表格条目、提示块、代码块和相关页面结构；英文 nav/sidebar 必须镜像中文的层级与顺序。

• 使用美式英语和 sentence case 标题，以自然英文表达原意，不保留中文句式。
• 可以拆分长句、调整主被动和删除中文填充连接词，但不得增加、删除、重排或弱化事实与边界。
• title、description、H1 和导航文字翻译为英文；status、tags、visibility 保持一致。
• compile 用作动词，compilation 用作过程或机制；build 对应构建；fall back 用作动词，fallback 用作名词或定语。
• 统一使用 incremental compilation、incremental deployment、recompilation、self-healing、baseline、take effect 和 project information；“重编译”和次术语“扩散编译”都译为 recompilation。
• Jugg、Android Studio、Gradle、Kotlin、Java、APK、DEX、AAPT2、JVMTI、MCP、CLI、Apply Changes、Code Swap、Full Swap、Hot Reload 以及命令、参数、路径、配置值、日志关键词和实际 UI 文案保持原样。
• 站内链接改为对应英文镜像路径；外部链接和锚点语义保持不变。
• 英文不得独立增加产品事实。仅修正英文拼写、语法或自然度且不改变事实、结构、边界和链接时，可以只修改英文。
• 术语表是列结构例外：中文 zh/reference/glossary.md 使用“中文术语 / 英文术语 / 含义”三列，没有中文名称的术语写 -；英文 reference/glossary.md 只使用“Term / Meaning”两列，不反向加入中文。两页的术语条目、顺序和含义仍须对应。

控制范围和中英文同步

中文 /zh/ 与英文根路径必须严格镜像。除纯英文语言修正外，任何 Wiki 内容变更都按以下顺序执行：

1. 新增或修改中文页面，保持中文为内容基准。
2. 在同一任务中创建或更新相同相对路径的英文页面。
3. 新增、删除、移动或重命名页面时，同时更新中英文 nav/sidebar；不得保留单一语言独有页面。
4. 内容、结构、边界或链接发生变化时，中英文镜像必须出现在同一 diff 和同一 commit 中。

修改英文事实或结构时，先把变化落实到中文页面，再翻译回英文。只有英文拼写、语法或自然度修正可以单独提交，且不得触碰产品事实、章节结构、路由和链接。

除非需求要求修改，否则保留中英文共有路由、frontmatter.title、H1、既有产品术语和有效站内链接。兼容入口也必须建立中英文镜像。

用户只要求优化方案或审阅时，不修改文件。输出建议的页面主线、文章结构、应保留内容、应删除内容和验证需求，并单列默认保持不变的路由、标题、H1、产品术语和有效站内链接；确需调整时说明原因并等待确认。

验证交付结果

优化方案或只读审阅：

1. 检查引用的页面和实现路径真实存在。
2. 区分已验证事实、过时内容、缺少证据的主张和改写建议。
3. 报告语言镜像缺口和需要同步的事实。
4. 不为没有改动的 Markdown 执行 production build。
5. 不编辑、暂存或提交文件。

实际新写或改写页面：

1. 检查正式页面和 dev-only 页面在去掉 zh/ 前缀后具有完全相同的 Markdown 路径集合。
2. 除纯英文语言修正外，检查本次变更的每个中文页面和英文镜像都出现在 diff 中。
3. 运行 python3 .agents/skills/wiki-writer/scripts/validate_wiki.py --wiki-root docs/wiki，检查语言镜像、Markdown/HTML 相对链接和 sidebar 路由对应的源码页面。
4. 执行 git diff --check。
5. 在 docs/wiki 下执行不包含 dev-only 页面配置的 npm run build。
6. 路由未变化时，确认 docs/wiki/.vitepress/dist/ 下生成预期 HTML，并包含新标题或能够区分本次改动的章节。
7. 路由变化时执行提交前路由审计：
   • 使用 rg --hidden 扫描 docs/wiki 中的旧标题和旧 slug，包含 .vitepress/config.mts、首页、自定义卡片和 HTML 链接。
   • 用验证脚本的 --forbid-source-text、--expect-html-route 和 --expect-html-text ROUTE::TEXT 复核源码残留与新 HTML。
   • 未发布页面使用 --expect-removed-route 确认旧 HTML 不再生成；已发布页面使用 --expect-compatible-route 确认旧路由仍有分流页或兼容入口。
8. 复查最终 diff，排除无证据的行为主张、过时历史状态、concept/capability 重复、意外暴露的源码细节和英文残留中文正文。
9. 按仓库 commit 规范，只提交本次任务修改的文件。

纯文字改动不新增自动化测试。新写或重写页面使用 production Wiki build、链接检查、渲染产物检查和文档与代码对照作为验证证据；中译英使用中文镜像、语言镜像检查和相同构建验证作为证据，不重新核对实现。

质量门禁

完成前检查所有适用项：

• 页面无需依赖父页面也能独立阅读。
• 首屏已经补齐理解正文所需的场景或最小领域模型，并说明本页与 Jugg 的关系。
• 读者能够用页面建立的领域模型串联后续实现点，而不是只看到一组分别正确的局部事实。
• 每个主要章节回答读者问题，而不是只写实现组件名。
• 存在真实失败或明确成本时，核心机制页面给出具体案例。
• 文章解释当前方案为什么这样选择，不只描述执行步骤。
• 明确能力边界和回退行为。
• 新写或重写页面的产品行为与当前代码一致，历史资料已核验、标记或舍弃；中译英内容与中文基准一致。
• concepts 与 capabilities 不重复同一段机制解释。
• 中英文 Markdown 路径、页面结构和导航层级严格镜像；术语表仅允许已定义的列结构差异。
• 除纯英文语言修正外，中英文内容变化已在同一任务中同步。
• 文字克制、具体，没有明显 AI 写作痕迹。
• 实际文章改动已通过 production build 和链接检查；只读审阅已提供仓库证据。

最终响应说明读者能够感知的改进、验证证据、改动文件和 commit，并附上仓库 AGENTS.md 要求的固定执行清单。