traceway-write

Traceway 写入权限

此技能通过 traceway-write CLI（或写入 MCP 服务）执行值班工程师常做的例行操作：归档问题、确认并解决告警、暂缓或切换告警规则、运行监控、撰写事后复盘，以及标记响应缓慢的端点。

若要在变更前后了解 Traceway 某项功能的运作方式（例如确认告警后会如何影响升级流程、暂缓告警与停用规则有何区别、监控如何创建事件），请使用 traceway-learn 技能。它是完整的产品指南。通过 MCP 使用时，同一指南对应 traceway://knowledge/learn 资源。

若只需调查（调试问题、分析延迟），只读 traceway 技能提供更深入的操作指南。此处的命令用法相同：traceway 中的每个读取命令在 traceway-write 中也都可用。

如果已连接 traceway-write MCP 服务（stdio traceway-write mcp 或 https://<instance>/mcp/write），请优先使用其工具，而不是通过 shell 调用命令。其资源包含此技能的知识，工具名称列于下表。

设置

1. 安装写入 CLI

traceway-write 是独立的二进制文件，拥有单独的登录流程，因此无法将只读版 traceway 原地升级为写入版。

curl -fsSL https://cli.tracewayapp.com/install.sh | sh -s -- --write
traceway-write version

预编译归档文件位于 发布页面，对应 cli/vX.Y.Z 标签，文件名为 traceway-write_<version>_<os>_<arch>.tar.gz。从源码构建：cd traceway/cli && go build -tags write -o bin/traceway-write ./cmd/traceway。

2. 使用写入权限登录

请让用户自行通过浏览器登录（在 Claude Code 中：! traceway-write login --url https://<instance>）。审批页面会说明登录需要读取和写入权限。

traceway-write login --url https://<instance>

无头环境的替代方法：用户创建一个读写个人访问令牌（Account > Personal Access Tokens，前缀为 tww_，有效期不超过 90 天），并在不回显令牌的情况下存储：

printf '%s' "$TRACEWAY_WRITE_TOKEN" | traceway-write login --url https://<instance> --token-stdin

存储在 traceway-write 中的读取令牌（twp_）仍无法写入：服务器会拒绝所有写入操作，并显示“This credential is read-only”。

3. 组织主动启用

组织所有者或管理员必须启用 Settings > Agent Access > Allow agent writes。在启用之前，写入请求会收到 403 错误：“Agent write access is turned off for this organization”。不要尝试绕过限制：请告知用户谁可以启用此设置。

4. 选择项目

traceway-write projects list
traceway-write projects use <project-id>

使用 MCP 而非 CLI

• 本地 stdio：claude mcp add traceway-write -- traceway-write mcp（使用 traceway-write login）。
• 远程：将 https://<instance>/mcp/write 添加为 HTTP MCP 服务。客户端会运行 OAuth，且授权页面会请求读取和写入权限。普通的 /mcp 服务永远不会开放写入工具，即使使用写入令牌也不例外。

使用写入权限

写入权限可让 Agent 执行值班工程师在事件期间及之后的常规操作。它分为三个级别，必须全部同意后才能执行写入操作：

1. 凭据。 只有写入凭据才能执行写入操作：tww_ 个人访问令牌、traceway-write login，或连接到 /mcp/write 服务的 MCP 客户端。twp_ 令牌、traceway login 和 /mcp 服务均为只读，无论此人的角色是什么。
2. 组织。 管理员必须在 Settings > Agent Access 中启用该功能。在此之前，所有 Agent 写入操作都会被拒绝，并返回说明原因的 403 错误。
3. 个人。 写入操作使用创建凭据者的角色，并遵循与仪表板相同的规则。readonly 成员的写入令牌不能归档问题、更改警报、运行监控或编辑事后分析：此类写入操作会被拒绝，并返回以“Your role in this project is read-only”开头的 403 错误。projects list（list_projects）会显示此人在各项目中的角色。确认和解决页面不需要写入角色，因此任何成员的写入令牌都可以执行这些操作。

写入凭据在组织中执行的每项操作，无论操作已被接受，还是因 Agent Access 关闭而遭拒，都会记录在组织的 Agent 活动日志中，其中包含人员、凭据、项目和操作结果。

Agent 可以更改的内容

操作	CLI（traceway-write）	MCP 工具	可撤销
归档或取消归档问题	exceptions archive <hash>... / unarchive	archive_exceptions / unarchive_exceptions	是
确认页面	pages ack <id>	acknowledge_page	否，但无害：只会停止升级
解决页面	pages resolve <id> [--archive-issue]	resolve_page	否
启用或停用警报规则	alerts enable <id> / alerts disable <id>	set_notification_rule_enabled	是
暂停警报规则	alerts snooze <id> --minutes N（0 表示清除）	snooze_notification_rule	是，到期后会自动恢复
立即运行监控	monitors run <id>	run_check	无需撤销
编写事后分析	post-mortems create / update <id>	create_post_mortem / update_post_mortem	编辑内容会保留在活动日志中
将端点标记为预期较慢	endpoints mark-slow <endpoint> --offset-ms N --reason ...（0 表示移除）	set_slow_endpoint	是

其他所有操作（创建规则和频道、编辑排班和策略、状态页面和公开事件更新、成员、令牌、项目设置、删除任何内容）仍需在仪表板中完成。这些路由会直接拒绝 Agent 凭据。

每次写入的规则

• 仅在用户提出要求时执行。 调查、调试、总结或“看一看”都不意味着要写入。用户必须明确要求进行更改。
• 如果请求可能超出用户了解的范围，就先询问。 如果写入会涉及多条记录，且它们存在用户可能不了解的差异（例如，一条仍在发生、原因不同或属于另一个团队），请列出这些记录，说明差异，并在写入前询问用户要更改哪些记录。不要自行决定，哪怕只是排除那条特殊记录也不行。
• 执行前先说明。 用一行说明操作、记录和新值：“将规则 12（GET /api/search 上的 Endpoint P95）暂停 60 分钟。” CLI 会在 TTY 中请求确认，否则需要 --yes。MCP 客户端会执行自己的审批步骤。
• 优先选择可撤销的选项。 暂停而不是禁用。问题仍在发生时，先确认而不是解决。如果不确定问题页面是否已处理完毕，请归档问题，而不是使用 --archive-issue 解决其页面。
• 报告更改内容以及撤销方法。
• 将 403 视为明确答复。 每个 403 都会指出对应的权限层级，且都是策略决定。不要重试、切换凭据或寻找其他途径。告诉用户返回的信息及可以更改该设置的人：
  • “此凭据为只读”：该凭据只有读取权限。用户需要写入凭据（tww_ 令牌、traceway-write login 或 /mcp/write）。
  • “Agent 写入权限已关闭”：组织管理员可在 Settings > Agent Access 中开启此权限。
  • “你在此项目中的角色为只读”：该凭据具有写入权限，但此人在项目中的角色是 readonly。更换其他凭据无济于事。组织所有者或管理员可在 Settings > Team Members 中更改该角色，或亲自进行更改。

操作指南

有人收到页面通知

1. 使用 pages list（状态为 active）查找页面，然后使用 pages show <id> 查看规则、主题和收到通知的人。
2. 使用读取工具进行调查。对于问题页面，页面中包含异常哈希：请按照调试流程操作。
3. 用户表示正在处理后：执行 pages ack <id>。这会停止向所有人升级通知。
4. 原因已修复并确认后：执行 pages resolve <id>；仅当用户也希望归档该问题时，才添加 --archive-issue。

已知事件期间警报反复触发

1. 使用 alerts list 查找规则 ID，并确认它就是产生过多通知的规则。
2. 执行 alerts snooze <id> --minutes 60（或按用户要求设置时长）。该规则会静音，并在设定时间后自动恢复。
3. 告知用户暂停何时结束。只有用户希望规则保持关闭，直到有人重新开启时，才禁用规则。

确认修复

1. 对受影响的监视器执行 monitors run <id>。
2. 等待大约一个间隔，然后执行 monitors show <id>：查看最新一次运行以及未解决的事件是否已解决。
3. 对于问题，执行 exceptions show <hash>，并确认没有发生时间晚于部署时间的异常。仅当用户同意问题已修复时，才将其归档。

撰写事后复盘报告

1. 使用读取工具收集事实：从 monitors show 获取事件时间窗口、问题及其首次和最后一次发生时间、页面及确认人、缓慢的端点，以及失败请求的跟踪记录。
2. 用 Markdown 起草文档，包含以下部分：摘要、影响（涉及对象和影响程度，附具体数字）、时间线（UTC，从首次信号到解决）、根本原因、解决方案、后续行动（如已知，注明负责人）。只陈述遥测数据或用户确认的内容，并将尚未解决的问题标记为开放问题。
3. 将草稿展示给用户。只有在用户批准后才创建：post-mortems create --title "..." --content-file draft.md --tag <tag> --incident <id>。
4. 后续编辑：先运行 post-mortems show <id>，然后运行 post-mortems update <id> --content-file revised.md --expected-updated-at <updatedAt from that show>，并提供完整的修订正文。如果期间有人编辑过，更新会因冲突而失败：再次显示内容，然后重新应用更改。--unlink-incident 可移除错误关联的事件。

端点本来就慢

1. 向用户确认可以接受该延迟，并了解原因。
2. 使用 endpoints list --search "<endpoint>" 检查当前 p95。
3. 运行 endpoints mark-slow "<endpoint>" --offset-ms <a bit above p95> --reason "<why>"。原始百分位数不会改变。Apdex 和影响指标在偏移值以内不再受到惩罚。

命令参考

每个 traceway 读取命令都可在 traceway-write 中使用（exceptions list|show|occurrence、logs query、endpoints list|chart|show|slow、tasks show、ai-traces show、sessions show、traces show、metrics query、pages list|show、alerts list、monitors list|show、post-mortems list|show）。写入命令如下：

命令	MCP 工具	修改内容
traceway-write exceptions archive <hash>... [--yes]	archive_exceptions	从默认列表中隐藏问题
traceway-write exceptions unarchive <hash>... [--yes]	unarchive_exceptions	将问题重新列出
traceway-write pages ack <id>	acknowledge_page	停止升级某个页面
traceway-write pages resolve <id> [--archive-issue]	resolve_page	关闭页面，可选择归档其问题
traceway-write alerts enable <id> / disable <id>	set_notification_rule_enabled	启用或停用规则
traceway-write alerts snooze <id> --minutes N	snooze_notification_rule	将规则静默 N 分钟；0 表示取消静默
traceway-write monitors run <id>	run_check	将监控器的立即运行任务加入队列
traceway-write post-mortems create --title T [--content-file F] [--tag X] [--incident N]	create_post_mortem	新建事后复盘报告
traceway-write post-mortems update <id> [--title] [--content-file --expected-updated-at] [--tag] [--incident | --unlink-incident]	update_post_mortem	仅编辑传入的标志对应的内容。更新正文需要提供其所依据的 updatedAt
traceway-write endpoints mark-slow <endpoint> --offset-ms N --reason R	set_slow_endpoint	设置端点可接受的延迟；0 表示移除

每个写入命令都会显示即将执行的操作，并在 TTY 中请求确认。在脚本和 Agent 中，只有在用户明确要求执行该项更改后，才能传入 --yes（或设置 TRACEWAY_ASSUME_YES=1）。输出、标志、退出代码和错误封装与读取 CLI 相同：管道输出为 JSON，可使用 --fields 精简字段；身份验证和权限错误的退出代码为 4。

解析仪表板 URL

用户会在任何工作流中粘贴仪表板 URL（https://<instance>/<route>）作为参考。根据路由类型进行解析：

URL 路径	标识内容	获取方式
/issues/<hash> 和 /issues/<hash>/events	异常组（hash = 16 位十六进制字符）	traceway exceptions show <hash>
/issues/<hash>/<occurrenceId>（UUID）	组内的一个发生记录	traceway exceptions occurrence <occurrenceId> --recorded-at <t>，其中 t 是 URL 的 ?t= 参数。直接且快速；还会返回该发生记录的 sessionId 和会话录制。没有 URL？从 traceway exceptions show <hash> 的发生记录中获取 recordedAt
/endpoints/<endpoint>	端点组；该片段是经过 URL 编码的端点名称（GET%20%2Fapi%2Fusers%2F%3Aid 即 GET /api/users/:id）	解码后，运行 traceway endpoints list --search "<decoded name>"（该组没有 ID；endpoints show 用于单个请求，见下一行）
/endpoints/<endpoint>/<endpointId>	该端点的一个请求（事务）	traceway endpoints show <endpointId> --recorded-at <t>（t = URL 的 ?t= 参数）。返回请求、其 span 时间线，以及任何关联的异常/消息
/tasks/<task>	后台任务组	没有用于查询任务组的 CLI；如需查询单次运行，请使用下一行
/tasks/<task>/<taskId>	单次任务运行	traceway tasks show <taskId> --recorded-at <t>（t = URL 的 ?t= 参数）
/sessions/<sessionId>	会话（期间触发的异常；回放仅在仪表板中提供）	traceway sessions show <sessionId> --started-at <t>。URL 中没有 ?t=；使用会话的开始时间、URL 的 from=，或关联发生记录的 recordedAt（它位于时间范围内）。发生记录通过 sessionId 引用会话
/ai-traces/<traceName>	AI 跟踪组	没有用于查询跟踪组的 CLI；如需查询单个跟踪，请使用下一行
/ai-traces/<traceName>/<traceId>	单个 AI 跟踪	traceway ai-traces show <aiTraceId> --recorded-at <t>（使用 URL 中的 UUID，而不是 32 位十六进制跟踪 ID）（t = URL 的 ?t= 参数）；返回 token/成本统计数据和对话
/logs	日志页面（其筛选条件不会保存在 URL 中）	使用从用户描述中获取的标志运行 traceway logs query
/issues、/endpoints、/metrics、/	列表和仪表板页面	对应的 list / query 命令

时间范围：大多数仪表板 URL 都包含 ?preset=<p> 或 ?from=<iso>&to=<iso>（在页面间保持不变）；应遵循这些参数，而不是使用默认时间范围。

• preset 值 5m 30m 60m 3h 6h 12h 24h 3d 7d 直接映射到 --since；CLI 没有月单位，因此将 1M 映射为 --since 30d，将 3M 映射为 --since 90d。
• from/to 是 ISO 时间戳；通过 --from/--to 传入，若缺少 Z（或正确的时区偏移量），则补上，因为 CLI 要求使用 RFC3339 格式。
• 没有时间参数表示页面使用的是默认时间范围；根据基本规则选择 --since。

preset/from/to 为列表/分组视图设置时间范围。详情 URL 还会包含 ?t=<iso>，表示单条记录经过 URL 编码的时间戳。该 t 值正是按 ID 查询命令所需的 --recorded-at（会话则使用 --started-at）。接下来请参阅“按 ID 快速查询”。

快速按 ID 查询（始终传入时间戳）

按 ID 查询详情的命令（exceptions occurrence、endpoints show、tasks show、ai-traces show、sessions show、traces show）必须提供记录的时间戳（--recorded-at；对于会话则使用 --started-at）。遥测表按天分区：提供时间戳后，查询范围会缩小到一个较小的时间窗口，ClickHouse 也只需扫描少数几个分区；如果不提供，服务器就会扫描所有分区（冷加载速度很慢）。正因如此，该标志是必填项，所以绝不要省略。时间戳可以是近似值（在 ±24 小时内）；如果没有人提供，你也可以找回或估算时间戳，详见下文“没有时间戳时”。

时间戳的来源，按优先顺序排列：

1. 仪表板 URL：?t=<iso> 参数就是记录的 recordedAt；对其进行 URL 解码后，原样传入。（会话没有 t；请使用会话开始时间、from=，或关联事件的 recordedAt。）
2. 已获取的列表或分组：每个 exceptions show 事件都带有 recordedAt。同时记录 ID 和对应的 recordedAt，然后再深入查询。
3. 通知：见下文。

持有 ID 时的查询顺序：先解析其 recordedAt（通过 URL、分组或通知），然后再调用按 ID 查询的命令并传入该时间戳。

没有时间戳时

该标志是必填项，所以你必须提供某个值，但可以是近似值。查询窗口是传入时间前后 ±24 小时（traces show 为 ±48 小时）；如果记录不在该窗口内，服务器会退回到不受限扫描。因此，时间戳与实际时间相差一天以内时，查询仍然很快；即使猜错，仍会返回正确记录，只是速度较慢。按以下顺序确定时间戳：

1. 通过 API 找回时间戳。 如果你知道某个事件的哈希（例如，粘贴的 /issues/<hash>/<occurrenceId> 链接不带 ?t=），运行 traceway exceptions show <hash> 并读取该事件的 recordedAt。哈希端点不需要时间戳。通过 exceptions list 获取的分组 firstSeen/lastSeen 可以限定事件发生时间（lastSeen ≈ 最近一次事件的时间）。
2. 根据上下文估算。 通知发送时间、问题的 firstSeen/lastSeen，或 URL 的 preset/from 时间窗口，都能让你确定一个 ±24 小时内的时间。对于快速查询，这已足够。
3. 询问用户。 如果没有任何信息可以确定时间（例如，只有一个事件/端点 ID，没有哈希、时间，也没有可供找回信息的列表），就询问大致发生时间（“大约是什么时候触发的？一天以内就够了”），并传入该时间。如果问题比较旧，不要随便填“现在”之类的占位值；这样会妨碍分区裁剪，还可能完全超出 ±24 小时窗口。