Wiki Writer

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。

判定页面职责

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

不要让 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、复用产物、修改状态和处理结果：

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

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

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

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

• 深度定制，例如隔离编译器运行环境、定制 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 要求的固定执行清单。