twg-confluence

twg-confluence

当 Confluence 是主要信息源或变更目标时，与根命令 twg 配合使用。 此技能负责内容类型、层级、格式和并发语义； 具体命令语法以实时帮助为准。

CLI 启动器备用方案

运行 twg <command>。如果 shell 提示 command not found，请使用 $HOME/.local/bin/twg （macOS/Linux）/ $env:LOCALAPPDATA\Programs\twg\bin\twg.exe（PowerShell），然后 告知用户将该目录添加到 PATH。不要将身份验证或命令错误视为 PATH 故障。

适用场景

• 用于以 Confluence 为核心的内容或空间读取与变更：CQL、 正文、层级、版本、权限、导出。
• 在更广泛的工作流中，如果 Confluence 链接只是辅助信息，则不要加载。

首选路由

意图	路由
已知内容 ID 或 URL	confluence content get
多个已知页面	对整组页面调用一次 docs get <id-or-url…>
精确筛选 Confluence 内容	使用 CQL 进行 Confluence 搜索
按日期筛选页面／博客文章列表	使用带 lastmodified 的 confluence search query --cql；content list 不支持日期筛选
模糊查找页面／主题	跨产品搜索，然后使用原生命令获取
创建或更新内容	统一的 confluence content 命令入口
空间元数据／生命周期	confluence space
层级	confluence tree
导出	Word 会直接返回下载内容；PDF 需要轮询导出状态

执行不熟悉或影响重大的变更前，先运行 twg help describe "<exact path>"。

Confluence 语义

分页。

• 内容操作请使用实时帮助中说明的统一内容命令入口；空间操作使用 confluence space，层级操作使用 confluence tree。
• 搜索摘要只是发现候选内容的依据。总结或编辑内容前，先阅读选中的内容。
• confluence content get 和 content versions list --id 一次只能处理单个页面。 对于一组页面，先从一次 confluence search query --cql 获取元数据（标题、 空间、lastmodified、作者），然后只对其内容会影响答案的页面读取正文—— 通过一次批量调用 docs get <id-or-url…> 完成，该命令可一次接收多个 ID， 并使用 --agent-fields @compact。绝不要对页面列表逐个调用单页路由，也不要 针对每个页面重新运行 CQL 查询。
• 页面标题与正文分别提供。不要在正文开头重复标题。
• Remix 创建操作返回的是资源，而不是页面嵌入内容。请按照已加载的 HTML 指南进行嵌入，并回读页面；仅有 ID／URL 不能作为成功证明。
• Maui 创建操作使用 --content-id 仅用于归属／嵌入，而非读取页面。先读取源内容；在提示词中包含数值、标签、叙述内容和可视化说明。只写“此页面”是不够的。

安全创作与编辑

• 将用户授权与 CLI 确认视为归档、移至回收站和清除操作的独立检查。通过 --yes 是执行前检查，并不代表用户已授权进行更改。仅当用户明确指出要执行的更改以及确切目标或此前展示的有界目标集后，才使用 --yes。
• 用户在看到具体列表后明确指示，例如“归档页面 XYZ”或“归档那 15 个页面”，即授权执行，无需再次确认。诸如“清理”“整理”或“处理一下”之类的模糊表述，不构成归档、移至回收站或清除的授权。
• 如果更改或目标是推断得出的，先确定拟议的目标，展示确切操作和有界目标列表，并等待用户明确同意。不要将类似的先前操作所获批准视为通用授权；trash 不代表授权永久清除。
• 开始创作前，每个会话中对每个空间应用一次目标空间的说明；请参阅 references/spaces.md。说明为空时，使用默认设置。
• 在支持的情况下，协作式内部内容优先使用 live_doc。未特别说明的“页面”或“文档”创建操作也默认创建实时文档。
• 对于明确要求经典/非实时内容、知识库、客户帮助内容、已有经典页面的空间，或仅支持页面的操作，使用 page。保留现有目标的类型；经典父级不会决定子级的类型。
• 对于非简单编辑，先读取当前内容，将正文保存到本地，编辑文件，然后使用快照令牌更新。
• 如果涉及宏或必须精确保留存储格式，请使用无损 HTML 往返流程。
• 仅在用户明确要求预览或直接执行未获请求且编辑风险异常高时，才使用 --dry-run。
• 更改后重新读取内容或空间，并报告其 URL。

工作移交

• 对于相关的 Jira 工作、项目、目标或依赖项，加载 twg-context-discovery；对于人员、所有权、权限或升级处理，加载 twg-responsibility-routing。
• 如果页面是更广泛状态报告的一部分，加载 twg-status-rollups。
• 对于运行手册、事件或 PIR，加载 twg-operational-health。
• 要创建或克隆整个空间，请加载 twg-space-creation。

参考资料

• references/content.md - 内容类型、读取、写入和导出
• references/editing.md - 并发安全的正文编辑
• references/spaces.md - 空间生命周期和层级结构
• references/querying.md - CQL 和模糊发现
• references/body-formats.md - HTML、Markdown、提及和特殊格式