unity-console

**调用此模块中的任何技能前：**如果你准备根据技能名称或描述猜测参数后调用技能，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已从 recommend/schema 获取参数定义，则可以直接进行 dryRun。

触发条件

• 检查控制台输出
• 过滤错误或警告
• 输出日志消息
• 配置控制台
• 查看控制台输出、过滤错误或警告、输出日志、配置控制台

Unity 控制台技能

使用 Unity 控制台——捕获日志、写入消息并调试项目。

操作模式

• 审批：只读技能（console_get_logs / console_get_stats，标记为 SkillMode.SemiAuto）直接执行；其余技能（console_start_capture / console_stop_capture / console_clear / console_log / console_export / console_set_pause_on_error / console_set_collapse / console_set_clear_on_play，默认为 SkillMode.FullAuto）需要用户授权，授权后一步执行并返回结果。
• 自动 / 绕过：直接执行。
• 本模块不包含 Delete / PlayMode / Reload / RiskLevel=high 类技能——没有 IsForbiddenInSemi 拦截，无需 Bypass 即可运行的高危操作。

切勿（常见幻觉）：

• console_filter 不存在 → 使用带有 filter 参数的 console_get_logs
• console_read 不存在 → 使用 console_get_logs
• console_write 不存在 → 使用 console_log
• 不要与 debug_get_logs 混淆——console_get_logs 是持久化的带时间戳历史记录 API；debug_get_logs 是原生 Console 兼容读取器

路由：

• 对于编译错误 → 使用 debug 模块的 debug_check_compilation
• 对于错误堆栈跟踪 → 使用 debug 模块的 debug_get_stack_trace
• 对于控制台设置（折叠、播放时清除）→ console_set_collapse / console_set_clear_on_play（本模块）

技能概览

技能	描述
console_start_capture	开始捕获日志
console_stop_capture	停止捕获日志
console_get_logs	获取带固定快照分页的持久化时间戳日志
console_clear	清除控制台
console_log	写入日志消息
console_set_pause_on_error	启用或禁用播放模式下的错误暂停
console_export	将控制台日志导出到文件
console_get_stats	获取日志统计信息（按类型计数）
console_set_collapse	设置控制台日志折叠模式
console_set_clear_on_play	设置播放模式下清除控制台

---

技能

console_start_capture

开始兼容性捕获会话。系统始终会收集托管日志历史记录，因此此操作会记录会话游标，且不会清除之前的后台历史记录。

无参数。

console_stop_capture

停止兼容性捕获会话。此操作不会丢弃保留的历史记录。

无参数。

console_get_logs

获取保留的 Unity Console 日志。默认情况下，完全相同的 (type, message, stackTrace) 记录会合并为一个组。此读取设置与 Unity Console 的 UI「Collapse」切换项相互独立。

参数	类型	必填	默认值	描述
type	string	否	"All"	All / Error / Warning / Log（不区分大小写；指定其他值将被拒绝，并返回 SEMANTIC_INVALID）
filter	string	否	null	在完整消息或堆栈跟踪中进行不区分大小写的子字符串匹配
limit	int	否	100	每页结果数（1–1000）
collapse	bool	否	true	返回稳定的重复项分组，而不是单条记录
fromUtc	string	否	null	ISO-8601 UTC 起始时间（包含；格式为 ...Z 或零时差）
toUtc	string	否	null	ISO-8601 UTC 结束时间（不包含）；范围为 [fromUtc, toUtc)
groupId	string	否	null	限定为合并响应中返回的一个组 ID
cursor	string	否	null	由上一响应返回的不透明固定快照分页游标；执行 console_clear 后失效
includeStackTrace	bool	否	false	在返回的记录/分组中包含完整堆栈跟踪

返回： {count, logs, source, cursor, nextCursor, totalMatched, hasMore, complete, dropped, coverage}。单条记录包含 {seq, type, message, stackTrace?, utc, timeKnown, sessionId, source}。合并后的行包含 {groupId, type, message, stackTrace?, count, countKnown, firstUtc, lastUtc, firstSeq, lastSeq}。groupId 对完整的 (type, message, stackTrace) 元组保持稳定。cursor 会固定后续每一页的最高序列号；新日志不会进入该分页序列。complete:false 或 dropped>0 表示保留策略、清除历史记录、数据损坏、持久化问题或较旧的原生记录导致无法保证内容完整。此服务创建之前的原生日志具有 utc:null 和 timeKnown:false；系统不会为其编造时间戳。其 count 为 null 且 countKnown:false，因为 Unity 的旧版 Console 反射接口无法提供未合并的出现次数。Unity 反射可能会截断原生消息，因此只有托管记录能保证全文筛选。coverage 会报告这些情况、保留数量上限、持久化健康状态以及可用的 Editor.log 路径；Editor.log 不会导入游标历史记录，仅作为手动备用方案。

console_clear

清除 Unity 控制台。

无参数。

console_log

写入自定义日志消息。

参数	类型	必填	默认值	描述
message	string	是	-	日志消息
type	string	否	"Log"	Log/Warning/Error

console_set_pause_on_error

在 Play 模式下启用或禁用 Error Pause。

参数	类型	必填	默认值	描述
enabled	bool	否	true	启用或禁用错误暂停

返回： { success, enabled }

console_export

将保留的控制台历史记录导出到文件，其中包含可用的 UTC 时间戳和完整堆栈跟踪。

参数	类型	必填	默认值	描述
savePath	string	否	"Assets/console_log.txt"	保存日志的文件路径

返回： { success, path, count, source, complete, dropped, truncated }。在将导出内容视为完整证据之前，请检查 truncated。

console_get_stats

获取保留日志历史记录的统计信息。

无参数。

返回： {success, total, source, logs, warnings, errors, exceptions, asserts, complete, dropped, truncated}。在将零错误计数作为运行正常的证据之前，请检查 truncated。

console_set_collapse

设置控制台日志折叠模式。

参数	类型	必填	默认值	说明
enabled	bool	是	-	启用或禁用折叠模式

返回： { success, setting, enabled }

console_set_clear_on_play

设置运行时清除模式。

参数	类型	必填	默认值	说明
enabled	bool	是	-	启用或禁用运行时清除

---

使用示例

import unity_skills

# History starts automatically. The first response fixes a snapshot; later pages do not admit new logs.
page = unity_skills.call_skill("console_get_logs", type="Error", includeStackTrace=True)
while page["hasMore"]:
    page = unity_skills.call_skill("console_get_logs", type="Error", includeStackTrace=True,
                                  cursor=page["nextCursor"])

# For occurrence-level evidence instead of duplicate groups, opt out of collapse and constrain time.
logs = unity_skills.call_skill("console_get_logs", collapse=False,
    fromUtc="2026-10-10T00:00:00Z", toUtc="2026-10-11T00:00:00Z")

# Write custom log
unity_skills.call_skill("console_log",
    message="AI Agent: Task completed",
    type="Log"
)

# Write warning
unity_skills.call_skill("console_log",
    message="AI Agent: Performance issue detected",
    type="Warning"
)

# Clear invalidates every old cursor and deletes retained history. A capture session is optional
# and limits reads/exports/stats to records created after its start without deleting background history.
unity_skills.call_skill("console_start_capture")
unity_skills.call_skill("console_clear")
unity_skills.call_skill("console_stop_capture")

最佳实践

1. 首先折叠错误组，只有在需要查看各次发生记录时，才请求 collapse:false 和 groupId 或时间范围。
2. 持续使用 nextCursor 获取后续页面，直到 hasMore:false；保留第一页的固定快照，并在 complete:false 时拒绝结果。
3. 将 dropped、coverage.corruptRows 或 coverage.durabilityIssue 视为证据不完整。保留上限为 50,000 条记录和 64 MiB。
4. 仅使用 console_start_capture 标记兼容性会话的起止范围；自动托管的捕获已在运行，且开始捕获不会清除历史记录。
5. coverage.editorLogPath 回退路径仅用于手动排查。其时间戳未经标准化，也不会合并到此 API 中。

---

精确签名

确切名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非此文件。