fix: smooth fan curve cooldown behavior (#16)

make fan curve hysteresis follow rising temperatures immediately while holding cooldown inside the deadband, add optional fall_slew_rate for gentler RPM drops, and update the cooler profile guidance.

Author: harryisfish

Sources/PolicyEngine/PolicyEngine.swift

@@ -330,14 +330,16 @@ public struct FanCurve: Codable, Equatable, Sendable {
     public var points: [FanCurvePoint]
     public var hysteresisCelsius: Double
     public var slewRateRPMPerSecond: Double?
+    public var fallSlewRateRPMPerSecond: Double?
 
     public init(
         name: String,
         sensors: [String] = [],
         sensorWeights: [String: Double] = [:],
         points: [FanCurvePoint],
         hysteresisCelsius: Double = 0,
-        slewRateRPMPerSecond: Double? = nil
+        slewRateRPMPerSecond: Double? = nil,
+        fallSlewRateRPMPerSecond: Double? = nil
     ) throws {
         let sortedPoints = points.sorted { $0.temperatureCelsius < $1.temperatureCelsius }
         guard sortedPoints.count >= 2 else {
@@ -352,6 +354,7 @@ public struct FanCurve: Codable, Equatable, Sendable {
         self.points = sortedPoints
         self.hysteresisCelsius = max(0, hysteresisCelsius)
         self.slewRateRPMPerSecond = slewRateRPMPerSecond.map { max(0, $0) }
+        self.fallSlewRateRPMPerSecond = fallSlewRateRPMPerSecond.map { max(0, $0) }
     }
 
     public static func quiet(maxRPM: Double) -> FanCurve {
@@ -368,7 +371,8 @@ public struct FanCurve: Codable, Equatable, Sendable {
                 FanCurvePoint(105, maxRPM)
             ],
             hysteresisCelsius: 3,
-            slewRateRPMPerSecond: 400
+            slewRateRPMPerSecond: 400,
+            fallSlewRateRPMPerSecond: 180
         )
     }
 
@@ -416,18 +420,19 @@ public struct FanCurveEngine: Sendable {
         now: Date
     ) throws -> FanCurveEvaluation {
         let aggregated = try Self.aggregate(samples: samples, sensors: curve.sensors, weights: curve.sensorWeights)
-        let effectiveTemperature: Double
-        if
-            let previous = lastEffectiveTemperature,
-            abs(aggregated - previous) <= curve.hysteresisCelsius
-        {
-            effectiveTemperature = previous
-        } else {
-            effectiveTemperature = aggregated
-        }
+        let effectiveTemperature = Self.hysteresisAdjustedTemperature(
+            aggregated: aggregated,
+            previous: lastEffectiveTemperature,
+            hysteresis: curve.hysteresisCelsius
+        )
 
         let interpolated = Self.interpolate(points: curve.points, temperature: effectiveTemperature)
-        let target = slewLimitedTarget(rawTarget: interpolated, slewRate: curve.slewRateRPMPerSecond, now: now)
+        let target = slewLimitedTarget(
+            rawTarget: interpolated,
+            riseSlewRate: curve.slewRateRPMPerSecond,
+            fallSlewRate: curve.fallSlewRateRPMPerSecond,
+            now: now
+        )
 
         lastEffectiveTemperature = effectiveTemperature
         lastRPM = target
@@ -440,6 +445,19 @@ public struct FanCurveEngine: Sendable {
         )
     }
 
+    static func hysteresisAdjustedTemperature(aggregated: Double, previous: Double?, hysteresis: Double) -> Double {
+        guard let previous, hysteresis > 0 else {
+            return aggregated
+        }
+        if aggregated >= previous {
+            return aggregated
+        }
+        if aggregated >= previous - hysteresis {
+            return previous
+        }
+        return aggregated
+    }
+
     public static func interpolate(points: [FanCurvePoint], temperature: Double) -> Double {
         let sorted = points.sorted { $0.temperatureCelsius < $1.temperatureCelsius }
         guard let first = sorted.first, let last = sorted.last else {
@@ -497,19 +515,26 @@ public struct FanCurveEngine: Sendable {
         return selected.map(\.celsius).max() ?? 0
     }
 
-    private func slewLimitedTarget(rawTarget: Double, slewRate: Double?, now: Date) -> Double {
+    private func slewLimitedTarget(rawTarget: Double, riseSlewRate: Double?, fallSlewRate: Double?, now: Date) -> Double {
         guard
-            let slewRate,
-            slewRate > 0,
             let lastRPM,
             let lastEvaluationDate
         else {
             return rawTarget
         }
-        let maxDelta = slewRate * max(0, now.timeIntervalSince(lastEvaluationDate))
+        let elapsed = max(0, now.timeIntervalSince(lastEvaluationDate))
         if rawTarget > lastRPM {
+            guard let slewRate = riseSlewRate, slewRate > 0 else {
+                return rawTarget
+            }
+            let maxDelta = slewRate * elapsed
             return min(rawTarget, lastRPM + maxDelta)
         }
+        let slewRate = fallSlewRate ?? riseSlewRate
+        guard let slewRate, slewRate > 0 else {
+            return rawTarget
+        }
+        let maxDelta = slewRate * elapsed
         return max(rawTarget, lastRPM - maxDelta)
     }
 }

Sources/SMCtlDaemonCore/Daemon.swift

@@ -149,6 +149,7 @@ struct FanCurveConfig: Codable, Equatable, Sendable {
     var points: [[FanPointValue]]
     var hysteresis: Double
     var slew_rate: Double?
+    var fall_slew_rate: Double?
     var weights: [String: Double]?
 
     init(
@@ -157,29 +158,32 @@ struct FanCurveConfig: Codable, Equatable, Sendable {
         points: [[FanPointValue]],
         hysteresis: Double = 0,
         slew_rate: Double? = nil,
+        fall_slew_rate: Double? = nil,
         weights: [String: Double]? = nil
     ) {
         self.name = name
         self.sensors = sensors
         self.points = points
         self.hysteresis = hysteresis
         self.slew_rate = slew_rate
+        self.fall_slew_rate = fall_slew_rate
         self.weights = weights
     }
 
     enum CodingKeys: String, CodingKey {
-        case name, sensors, points, hysteresis, slew_rate, weights
+        case name, sensors, points, hysteresis, slew_rate, fall_slew_rate, weights
     }
 
-    // Custom decoding so `hysteresis`/`slew_rate` are optional (default rather than
-    // keyNotFound) and accept TOML integers — see decodeLenientDoubleIfPresent (#9).
+    // Custom decoding so optional numeric tuning fields default rather than throwing
+    // keyNotFound and accept TOML integers — see decodeLenientDoubleIfPresent (#9).
     init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         name = try container.decode(String.self, forKey: .name)
         sensors = try container.decodeIfPresent([String].self, forKey: .sensors) ?? []
         points = try container.decode([[FanPointValue]].self, forKey: .points)
         hysteresis = try container.decodeLenientDoubleIfPresent(forKey: .hysteresis) ?? 0
         slew_rate = try container.decodeLenientDoubleIfPresent(forKey: .slew_rate)
+        fall_slew_rate = try container.decodeLenientDoubleIfPresent(forKey: .fall_slew_rate)
         weights = try container.decodeLenientDoubleDictionaryIfPresent(forKey: .weights)
     }
 }
@@ -1019,7 +1023,8 @@ public final class SmctlDaemon: @unchecked Sendable {
                 sensorWeights: curve.weights ?? [:],
                 points: points,
                 hysteresisCelsius: curve.hysteresis,
-                slewRateRPMPerSecond: curve.slew_rate
+                slewRateRPMPerSecond: curve.slew_rate,
+                fallSlewRateRPMPerSecond: curve.fall_slew_rate
             )
         }
     }
@@ -1232,6 +1237,9 @@ public final class SmctlDaemon: @unchecked Sendable {
             if let slewRate = curve.slew_rate {
                 text += "slew_rate = \(slewRate)\n"
             }
+            if let fallSlewRate = curve.fall_slew_rate {
+                text += "fall_slew_rate = \(fallSlewRate)\n"
+            }
             if let weights = curve.weights, !weights.isEmpty {
                 let pairs = weights.sorted { $0.key < $1.key }.map { "\"\($0.key)\" = \($0.value)" }.joined(separator: ", ")
                 text += "weights = { \(pairs) }\n"

Tests/PolicyEngineTests/FanCurveEngineTests.swift

@@ -33,7 +33,7 @@ final class FanCurveEngineTests: XCTestCase {
         )
     }
 
-    func testHysteresisIsBidirectionalDeadZone() throws {
+    func testHysteresisFollowsHeatingAndHoldsCooldown() throws {
         let curve = try FanCurve(
             name: "custom",
             points: [
@@ -53,7 +53,7 @@ final class FanCurveEngineTests: XCTestCase {
             samples: [FanTemperatureSample(sensor: "cpu", celsius: 62.9)],
             now: Date(timeIntervalSince1970: 1)
         )
-        let outsideUp = try engine.evaluate(
+        let furtherUp = try engine.evaluate(
             curve: curve,
             samples: [FanTemperatureSample(sensor: "cpu", celsius: 63.1)],
             now: Date(timeIntervalSince1970: 2)
@@ -65,15 +65,15 @@ final class FanCurveEngineTests: XCTestCase {
         )
         let outsideDown = try engine.evaluate(
             curve: curve,
-            samples: [FanTemperatureSample(sensor: "cpu", celsius: 59)],
+            samples: [FanTemperatureSample(sensor: "cpu", celsius: 59.9)],
             now: Date(timeIntervalSince1970: 4)
         )
 
         XCTAssertEqual(first.effectiveTemperature, 60, accuracy: 0.01)
-        XCTAssertEqual(insideUp.effectiveTemperature, 60, accuracy: 0.01)
-        XCTAssertEqual(outsideUp.effectiveTemperature, 63.1, accuracy: 0.01)
+        XCTAssertEqual(insideUp.effectiveTemperature, 62.9, accuracy: 0.01)
+        XCTAssertEqual(furtherUp.effectiveTemperature, 63.1, accuracy: 0.01)
         XCTAssertEqual(insideDown.effectiveTemperature, 63.1, accuracy: 0.01)
-        XCTAssertEqual(outsideDown.effectiveTemperature, 59, accuracy: 0.01)
+        XCTAssertEqual(outsideDown.effectiveTemperature, 59.9, accuracy: 0.01)
     }
 
     func testSlewRateLimitsRpmChangesPerSecondInBothDirections() throws {
@@ -110,4 +110,37 @@ final class FanCurveEngineTests: XCTestCase {
         XCTAssertEqual(down.unclampedRPM, 1000, accuracy: 0.01)
         XCTAssertEqual(down.targetRPM, 1500, accuracy: 0.01)
     }
+
+    func testFallSlewRateCanBeSlowerThanRiseSlewRate() throws {
+        let curve = try FanCurve(
+            name: "custom",
+            points: [
+                FanCurvePoint(50, 1000),
+                FanCurvePoint(90, 5000)
+            ],
+            slewRateRPMPerSecond: 1000,
+            fallSlewRateRPMPerSecond: 200
+        )
+        var engine = FanCurveEngine()
+        let start = Date(timeIntervalSince1970: 0)
+
+        _ = try engine.evaluate(
+            curve: curve,
+            samples: [FanTemperatureSample(sensor: "cpu", celsius: 50)],
+            now: start
+        )
+        let up = try engine.evaluate(
+            curve: curve,
+            samples: [FanTemperatureSample(sensor: "cpu", celsius: 90)],
+            now: start.addingTimeInterval(1)
+        )
+        let down = try engine.evaluate(
+            curve: curve,
+            samples: [FanTemperatureSample(sensor: "cpu", celsius: 50)],
+            now: start.addingTimeInterval(2)
+        )
+
+        XCTAssertEqual(up.targetRPM, 2000, accuracy: 0.01)
+        XCTAssertEqual(down.targetRPM, 1800, accuracy: 0.01)
+    }
 }

Tests/SMCtlDaemonCoreTests/SmctlDaemonTests.swift

@@ -357,6 +357,8 @@ final class SmctlDaemonTests: XCTestCase {
         sensors = []
         points = [[0, "max"], [105, 2000]]
         hysteresis = 3
+        slew_rate = 600
+        fall_slew_rate = 180
         """.write(toFile: configPath, atomically: true, encoding: .utf8)
 
         let daemon = makeDaemon(backend: RecordingBackend(), capabilities: .oneFan)
@@ -368,6 +370,8 @@ final class SmctlDaemonTests: XCTestCase {
         XCTAssertEqual(daemon.config.safety.temp_ceiling, 95)
         let curve = try XCTUnwrap(daemon.config.fan.curves.first)
         XCTAssertEqual(curve.hysteresis, 3)
+        XCTAssertEqual(curve.slew_rate, 600)
+        XCTAssertEqual(curve.fall_slew_rate, 180)
         XCTAssertEqual(curve.points, [[.number(0), .maximum], [.number(105), .number(2000)]])
     }
 

docs/design.md

@@ -124,8 +124,8 @@ locked ──直写 modeKey=1 成功──► manual          （M1/M5 路径）
 ### 5.4 风扇曲线引擎（PolicyEngine）
 
 - 曲线 = 折线段：`[(温度, RPM), ...]`，输入为**多传感器加权聚合值**（可配权重，默认取 max）
-- **滞回**：双阈值死区（升温越过 T 才升档，降温越过 T−delta 才降档），杜绝转速抖动——与充电状态机共用同一个 hysteresis 抽象
-- **变化率限制**：RPM 目标变化做 slew rate 限制，避免风扇忽高忽低的体感噪音
+- **滞回**：升温及时跟随，降温必须低于上次有效温度一段 `hysteresis` 后才下调，避免临界点附近反复升降
+- **变化率限制**：RPM 目标变化做 slew rate 限制，支持升速与降速分开配置；降速通常更慢，避免“刚转起来又马上掉下去”的体感噪音
 - profile：`quiet` / `auto` / `full` / 自定义曲线，TOML 定义
 
 ### 5.5 唤醒恢复
@@ -207,6 +207,8 @@ name = "custom"
 sensors = ["cpu", "gpu"]   # 聚合：默认 max，可加权
 points = [[50, 0], [65, 2000], [80, 4000], [95, "max"]]
 hysteresis = 3             # ℃
+slew_rate = 600            # RPM/s, rising target
+fall_slew_rate = 180       # RPM/s, falling target; defaults to slew_rate when omitted
 
 [safety]
 temp_ceiling = 100         # 温度护栏（℃），不可关闭，硬上限 105；连续 2 tick 超限才触发

docs/fan-profiles.md

@@ -60,8 +60,9 @@ Apple 没有公开 SMC 温度 key 的稳定语义。下面的前缀只能当经
 name = "cooler"
 sensors = ["Tp3P", "Tp0E", "Tp06"]
 points = [[75, 1000], [85, 1600], [95, 2600], [105, 4200], [110, "max"]]
-hysteresis = 2
-slew_rate = 800
+hysteresis = 4
+slew_rate = 600
+fall_slew_rate = 180
 ```
 
 daemon 每秒执行一次曲线：
@@ -73,8 +74,9 @@ daemon 每秒执行一次曲线：
 5. 如果配置了 `weights`，就按权重算加权平均。只有正权重会生效。
 6. 用 `points` 做线性插值，得到目标 RPM。
 7. daemon 会把目标 RPM 限制在风扇上报的最小/最大转速内。`"max"` 会展开成每个风扇自己的最大转速。
-8. `hysteresis` 控制温度死区，避免风扇在临界点来回抖动。
-9. `slew_rate` 控制每秒最大 RPM 变化，避免转速突然跳变。
+8. `hysteresis` 控制降温死区。温度升高时曲线会及时跟随；温度下降时，必须比上次有效温度低出这段余量，才会开始降低目标转速。
+9. `slew_rate` 控制升速时每秒最大 RPM 变化，避免目标转速突然上跳。
+10. `fall_slew_rate` 控制降速时每秒最大 RPM 变化。它通常应该小于 `slew_rate`，让风扇把热量继续带走一会儿，而不是刚碰到临界温度就立刻降速。
 
 曲线启用后，`smctl fan status` 里风扇模式会显示 `manual`。这是正常现象。曲线本质上是 daemon 托管的手动目标转速，不是一次性的 `smctl fan set`。
 
@@ -90,8 +92,9 @@ profile = "cooler"
 name = "cooler"
 sensors = ["Tp3P", "Tp0E", "Tp06", "Tp02", "Tp09", "Tp05", "Tp01"]
 points = [[75, 1000], [85, 1600], [95, 2600], [105, 4200], [110, "max"]]
-hysteresis = 2
-slew_rate = 800
+hysteresis = 4
+slew_rate = 600
+fall_slew_rate = 180
 ```
 
 这些点的含义：
@@ -101,8 +104,9 @@ slew_rate = 800
 - `95C -> 2600 RPM`：持续负载下开始真正带走热量，但不直接拉满。
 - `105C -> 4200 RPM`：接近热点高位时快速加强冷却。
 - `110C -> max`：接近热点硬上限时不再保留余量。
-- `hysteresis = 2`：温度小幅波动时不频繁调整目标转速。
-- `slew_rate = 800`：允许风扇足够快地跟上热点变化，但不会瞬间大跳。
+- `hysteresis = 4`：温度下降时保留 4C 的回落余量，避免在 95C、105C 这类临界点附近反复升降。
+- `slew_rate = 600`：升速仍然足够快，热点真的升高时不会拖太久。
+- `fall_slew_rate = 180`：降速更慢。风扇会继续带走热量，听感也不会出现“刚转起来又马上掉下去”。
 
 保留原有 `[safety]`。不要通过提高安全阈值来掩盖曲线太慢的问题。根本方案是更早从正确传感器提速，让安全护栏只做最后兜底。