name: standard-out-setup description: 添加控制台输出和日志记录以使错误对代理可见。标准输出是一个关键杠杆点 - 没有它，代理无法看到错误或理解应用状态。在代理静默失败、调试代理工作流或为新代码库设置代理编码时使用。 allowed-tools: Read, Edit, Grep

标准输出设置

指南，指导如何添加控制台输出来使错误对代理可见。这是最关键杠杆点之一 - 没有标准输出可见性，代理操作时如同盲人。

何时使用

代理失败且没有可见错误输出
静默函数返回但没有日志记录
新代码库设置用于代理编码
调试为什么代理无法自我纠正

为什么标准输出重要

代理只能根据所见行动。如果您的应用静默失败：

代理不知道出了问题
代理无法识别错误
代理无法修复问题
需要人工干预（破坏自主性）

当代理失败时，标准输出通常是缺失的环节。

模式

之前（代理看不到）

def process_data(data):
    return transform(data)  # 静默 - 发生了什么？

function processData(data) {
    return transform(data);  // 静默 - 成功？失败？
}

之后（代理可以看到）

def process_data(data):
    try:
        result = transform(data)
        print(f"SUCCESS: 处理了 {len(result)} 项")
        return result
    except Exception as e:
        print(f"ERROR in process_data: {str(e)}")
        raise

function processData(data) {
    try {
        const result = transform(data);
        console.log(`SUCCESS: 处理了 ${result.length} 项`);
        return result;
    } catch (error) {
        console.error(`ERROR in processData: ${error.message}`);
        throw error;
    }
}

记录什么

总是记录

成功并附带上下文
- 完成了什么操作
- 处理了多少项
- 创建或修改了什么
错误并附带详情
- 什么操作失败
- 错误消息
- 足够上下文以便调试
状态变化
- 文件创建、修改、删除
- API调用
- 数据库操作

不要过度记录

避免记录每个循环迭代
不要记录敏感数据（密码、令牌）
保持消息简洁但信息丰富

实施工作流

步骤1：识别关键函数

查找：

API端点
数据处理函数
文件操作
外部服务调用
数据库操作

步骤2：添加成功记录

为每个函数添加成功输出：

print(f"SUCCESS: {operation} 完成 - {context}")

步骤3：添加错误记录

包装在 try/except 中并输出错误：

try:
    # 操作
except Exception as e:
    print(f"ERROR in {function_name}: {str(e)}")
    raise  # 重新抛出以便代理看到错误

步骤4：验证可见性

运行应用并验证：

能否看到成功消息？
失败时能否看到错误消息？
是否有足够上下文理解发生了什么？

语言特定模式

Python

import logging

# 简单打印以立即可见
print(f"INFO: 开始 {operation}")
print(f"SUCCESS: {operation} 完成")
print(f"ERROR: {operation} 失败 - {error}")

# 或使用 logging 以更多控制
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

logger.info(f"开始 {operation}")
logger.error(f"{operation} 失败: {error}")

TypeScript/JavaScript

// 简单 console 以立即可见
console.log(`INFO: 开始 ${operation}`);
console.log(`SUCCESS: ${operation} 完成`);
console.error(`ERROR: ${operation} 失败 - ${error.message}`);

// 或使用 logger
import { logger } from './logger';

logger.info(`开始 ${operation}`);
logger.error(`${operation} 失败`, { error });

Go

import "log"

log.Printf("INFO: 开始 %s", operation)
log.Printf("SUCCESS: %s 完成", operation)
log.Printf("ERROR: %s 失败 - %v", operation, err)

API端点模式

这是代理最需要可见性的常见地方：

@app.post("/api/upload")
async def upload_file(file: UploadFile):
    print(f"INFO: 收到上传请求，文件 {file.filename}")
    try:
        result = await process_file(file)
        print(f"SUCCESS: 上传 {file.filename} - 处理了 {len(result)} 行")
        return {"status": "success", "rows": len(result)}
    except Exception as e:
        print(f"ERROR: 上传失败，文件 {file.filename} - {str(e)}")
        raise HTTPException(status_code=500, detail=str(e))

要修复的反模式

静默返回

# 坏
ndef fetch_data():
    return requests.get(url).json()

# 好
def fetch_data():
    print(f"INFO: 从 {url} 获取数据")
    response = requests.get(url)
    print(f"SUCCESS: 收到 {len(response.content)} 字节")
    return response.json()

裸 except 块

# 坏 - 代理永远看不到错误
try:
    risky_operation()
except:
    pass

# 好 - 代理看到哪里出了问题
try:
    risky_operation()
except Exception as e:
    print(f"ERROR: risky_operation 失败 - {str(e)}")
    raise

空 catch 块

// 坏
try {
    riskyOperation();
} catch (e) {}

// 好
try {
    riskyOperation();
} catch (error) {
    console.error(`ERROR: riskyOperation 失败 - ${error.message}`);
    throw error;
}

验证清单

添加标准输出后：

[ ] 成功消息出现在正常操作中
[ ] 错误消息出现在操作失败时
[ ] 消息包括足够上下文以理解发生了什么
[ ] 代理可以看到并响应输出
[ ] 未记录敏感数据

版本历史

v1.0.0 (2025-12-26): 初始发布

最后更新

日期: 2025-12-26 模型: claude-opus-4-5-20251101

标准输出设置Skill standard-out-setup