release: v4.3.23

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # 架构说明
 
-Runtime Self-Learning `v4.3.22` 当前由 `1` 个入口点、`87` 个 `lib` 模块和一组工具面组成。整体目标不是“尽量自动化”，而是“在不放宽边界的前提下，把本地经验整理成后续可复用的受限提示和低风险动作”。
+Runtime Self-Learning `v4.3.23` 当前由 `1` 个入口点、`88` 个 `lib` 模块和一组工具面组成。整体目标不是“尽量自动化”，而是“在不放宽边界的前提下，把本地经验整理成后续可复用的受限提示和低风险动作”。
 
 ---
 
@@ -188,6 +188,7 @@ flowchart TD
 | `event-log.js` | 审计事件追加、回放和校验。 |
 | `config-defaults.js` | 默认配置。 |
 | `hana-runtime-compat.js` | Hanako 插件系统兼容层。 |
+| `complexity.js` | 复杂度预算的单一事实源（扫描、限额、违规判定），供 CLI 与发布门共用。 |
 
 ---
 

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 本文档记录 Runtime Self-Learning 的版本演进。`v4.x` 为 LTS 维护线，因此该阶段的记录重点放在缺陷修复、审计加固、性能整理和发布治理，不再扩张自动化边界。
 
+## 4.3.23
+
+- 新增复杂度治理门：`lib/complexity.js` 定义 hard limit / soft target，`npm run complexity:check` 在超出 hard limit 时失败，`npm run complexity:report` 生成 `docs/COMPLEXITY_REPORT.md`。
+- 发布门纳入 `complexity.within_budget` 检查，并补充 `docs/COMPLEXITY_BUDGET.md` / `docs/COMPLEXITY_DEBT.md`，把 v4.x LTS 的模块数、单文件 LOC、import/export 数和 TODO/FIXME 预算写成可审计规则。
+- 拆分控制面热点复杂度：新增 `tools/control-parameters.js`、`tools/control-summaries.js` 与 `tools/control-handlers/*`，让 `tools/control.js` 从 712 LOC 收敛到约 602 LOC，并保留行为特征回归。
+- 测试总数 `606 -> 665`：新增控制面参数、摘要、脱敏、handler characterization 与 release-readiness 复杂度门回归；README 徽章和发布门默认测试基线同步到 665。
+- 边界未放宽：本版只增加本地静态治理、文档和控制面结构整理，无新增自动放行、网络、发布或外部副作用能力。
+
 ## 4.3.22
 
 - **新增自学习控制台（`chat.surface`，Hanako v0.344+）**：新增只读工具 `self_learning_console`，把"最近活动 + 待处理提案"快照投递进一条插件自有的 `plugin_private` 会话，并以原生 `chat.surface` transcript 卡片在当前聊天内嵌展示，可点开滚动查看历史快照。这是 UX/呈现层的可选增强，**不扩张自动化边界**：控台只读、由用户显式调用工具触发，不自动应用任何动作、不在后台主动推送。

INSTALL.md

@@ -50,10 +50,10 @@ OK    skills/self-learning/SKILL.md
 
 ## 固定版本安装
 
-如需固定到某个 release，例如 `v4.3.22`：
+如需固定到某个 release，例如 `v4.3.23`：
 
 ```powershell
-git clone --branch v4.3.22 https://github.com/326sun/Hanako-runtime-learner.git
+git clone --branch v4.3.23 https://github.com/326sun/Hanako-runtime-learner.git
 cd Hanako-runtime-learner
 npm run install-plugin
 ```

README.md

@@ -5,12 +5,12 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-4.3.22-blue" alt="version">
+  <img src="https://img.shields.io/badge/version-4.3.23-blue" alt="version">
   <img src="https://github.com/326sun/Hanako-runtime-learner/actions/workflows/ci.yml/badge.svg" alt="CI">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="license">
   <img src="https://img.shields.io/badge/platform-Hanako%20Agent%20v0.293%2B-orange" alt="platform">
   <img src="https://img.shields.io/badge/node-%E2%89%A518-brightgreen" alt="node">
-  <img src="https://img.shields.io/badge/tests-606%2F606-success" alt="tests">
+  <img src="https://img.shields.io/badge/tests-665%2F665-success" alt="tests">
 </p>
 
 Runtime Self-Learning 会观察本地 Hanako 对话中的重复工作流、用户纠正、常见报错和大上下文使用模式，把经过证据约束的经验整理成后续会话可用的保守提示。
@@ -60,7 +60,7 @@ npm run install-plugin
 固定版本安装：
 
 ```powershell
-git clone --branch v4.3.22 https://github.com/326sun/Hanako-runtime-learner.git
+git clone --branch v4.3.23 https://github.com/326sun/Hanako-runtime-learner.git
 cd Hanako-runtime-learner
 npm run install-plugin
 ```
@@ -176,10 +176,12 @@ flowchart LR
 
 ```powershell
 npm run check          # 语法与源代码检查
-npm test               # 606 个测试
+npm test               # 665 个测试
 npm run benchmark      # 17 个内置基准场景
 npm run perf           # 热路径微基准
-npm run release:check  # 发布元数据与 LTS 契约检查
+npm run complexity:check   # 复杂度预算门禁（超 hard limit 即失败）
+npm run complexity:report  # 生成 docs/COMPLEXITY_REPORT.md
+npm run release:check  # 发布元数据与 LTS 契约检查（含复杂度预算）
 ```
 
 当前热路径基线（以有界运行规模 `N=100 = MAX_PATTERN_COUNT * 2` 为准）：
@@ -208,12 +210,12 @@ npm run perf -- --json
 npm run release:check
 ```
 
-`v4.3.22` 的预期结果：
+`v4.3.23` 的预期结果：
 
 ```text
-package version: 4.3.22
+package version: 4.3.23
 npm run check: passed
-npm test: 606 tests, 601 passed, 5 skipped
+npm test: 665 tests, 665 passed, 0 skipped
 npm run benchmark: passed, 17 scenarios
 npm run perf: passed, no threshold breaches
 npm run release:check: Score 100
@@ -238,7 +240,7 @@ npm run release:check: Score 100
 | [docs/MIGRATION_v3_to_v4.md](docs/MIGRATION_v3_to_v4.md) | v3 到 v4 迁移说明。 |
 | [docs/LTS_MAINTENANCE_PLAN.md](docs/LTS_MAINTENANCE_PLAN.md) | v4.x LTS 维护策略。 |
 | [docs/DESIGN_GOAL_COMPLETION_MATRIX.md](docs/DESIGN_GOAL_COMPLETION_MATRIX.md) | 设计目标完成矩阵。 |
-| [docs/ACCEPTANCE-v4.3.22.md](docs/ACCEPTANCE-v4.3.22.md) | 当前版本验收记录。 |
+| [docs/ACCEPTANCE-v4.3.23.md](docs/ACCEPTANCE-v4.3.23.md) | 当前版本验收记录。 |
 | [CHANGELOG.md](CHANGELOG.md) | 版本历史。 |
 
 ## 许可证

docs/ACCEPTANCE-v4.3.23.md

@@ -0,0 +1,49 @@
+# v4.3.23 验收记录
+
+## 版本目标
+
+`v4.3.23` 在 `v4.3.22` 的自学习控制台版本基础上，引入 v4.x LTS 的复杂度治理基础设施，并完成 C-001（`tools/control.js`）低风险拆分。本版目标是让复杂度预算、复杂度债务和发布门形成可审计闭环，同时不放宽运行时安全边界。
+
+## 实现范围
+
+- 新增 `lib/complexity.js` 作为复杂度预算单一事实源，扫描 `lib/`、`scripts/`、`tests/`、`tools/` 的 LOC、import/export 数和 TODO/FIXME 标记。
+- 新增 `scripts/complexity-check.js` 与 `scripts/complexity-report.js`，分别提供 hard-limit 门禁与 `docs/COMPLEXITY_REPORT.md` 报告生成。
+- 新增 `docs/COMPLEXITY_BUDGET.md` 与 `docs/COMPLEXITY_DEBT.md`，把 v4.x LTS 的复杂度预算、软警告和 deferred 项写入文档。
+- `lib/release-readiness.js` 新增 `complexity.within_budget` 检查项，作为发布就绪度的一部分，保持本地 in-process 检查，无新增外部副作用。
+- C-001 低风险拆分：抽出 `tools/control-parameters.js`、`tools/control-summaries.js`、`tools/control-handlers/skill-policy.js`、`tools/control-handlers/events.js`，降低 `tools/control.js` 热点复杂度。
+- C-004 公共面收敛：`lib/json-io.js` 对外导出面从 17 收敛到 15。
+- 新增 characterization tests，覆盖 control parameters、summaries、redaction、handlers 与 release-readiness complexity gate。
+
+## 边界确认
+
+| 项目 | 结论 |
+|---|---|
+| 运行时依赖 | 未新增 |
+| 安全策略 | 未放宽 |
+| `execute` / `sessionPermission` / `*_ACTIONS` / `describeControlSideEffect` | 未改语义边界 |
+| 自动放行 / 网络 / 发布 / 外部副作用能力 | 未新增 |
+| 高风险 control handler 迁移 | deferred，不纳入本版 |
+
+## 验收结果
+
+| 项目 | 结果 |
+|---|---|
+| `npm run check` | 通过 |
+| `npm test` | 665 个测试，665 通过，0 跳过 |
+| `npm run complexity:check` | 通过，0 violation，3 soft warning |
+| `npm run complexity:report` | 通过，生成 `docs/COMPLEXITY_REPORT.md` |
+| `npm run release:check` | Score 100 |
+| `npm run benchmark` | 17/17 通过 |
+| `npm run perf` | 通过，无阈值越界 |
+
+## 本版确认项
+
+1. 复杂度预算成为发布门的一部分，`complexity.within_budget` 可在 `release:check` 中审计。
+2. 复杂度治理只读取本地源码并生成本地报告，不引入网络、凭证、外部写入或发布动作。
+3. `tools/control.js` 的低风险拆分保持参数 schema、摘要输出、脱敏行为和 handler 行为回归稳定。
+4. `docs/COMPLEXITY_DEBT.md` 明确记录 C-001 中高风险/低收益部分为 deferred，避免为了追求 LOC 指标扩大重构风险。
+5. README、CHANGELOG、设计矩阵、package/manifest/package-lock 版本号同步至 `4.3.23`。
+
+## 结论
+
+`v4.3.23` 满足当前 release gate，可作为 v4.x LTS 的复杂度治理正式版准备发布。实际 tag、GitHub Release 与合并动作仍应由维护者在 PR 审查通过后显式执行。

docs/COMPLEXITY_BUDGET.md

@@ -0,0 +1,73 @@
+# Complexity Budget (v4.x LTS)
+
+本文件定义 Runtime Self-Learning 在 v4.x LTS 维护期的复杂度预算与治理规则。
+它是 hard limit / soft target 的**权威说明**；可机读的实际数值定义在
+[`lib/complexity.js`](../lib/complexity.js) 的 `COMPLEXITY_HARD_LIMITS` /
+`COMPLEXITY_SOFT_TARGETS` 常量中，两者必须保持一致。
+
+- 状态报告：`npm run complexity:report` → [COMPLEXITY_REPORT.md](COMPLEXITY_REPORT.md)
+- 门禁检查：`npm run complexity:check`（超出 hard limit 时 `exit 1`）
+- 发布集成：`npm run release:check` 含 `complexity.within_budget` 检查项
+
+## 设计原则
+
+v4.x 已进入 LTS 维护期，复杂度预算的目的是**防止膨胀**，不是强迫重构。
+
+1. **冻结优先**：维护期不为新功能放宽预算。新增复杂度需要明确依据。
+2. **可机读、可验证**：预算落在代码常量与脚本里，不只是散文约定。
+3. **headroom 而非现状卡死**：hard limit 高于当前最大值，留出维护余量；
+   soft target 贴近现状，作为优先治理信号。
+4. **零运行时依赖不可动摇**：复杂度治理本身不得引入任何运行时依赖。
+
+## 扫描范围
+
+`lib/`、`scripts/`、`tests/`、`tools/` 下的 `.js` / `.cjs` / `.mjs` 文件。
+度量为轻量启发式（非完整 AST 解析）：LOC、import+require 数、export 数、TODO/FIXME 数。
+TODO/FIXME 仅统计约定式标记（`TODO:` / `FIXME:` / `TODO(author):`），
+代码或字符串中单纯出现这两个词（含本治理工具自身）不计入，避免自指误报。
+
+## Hard limits（超出即 `release:check` 失败）
+
+| 维度 | Hard limit |
+|---|---|
+| 单文件 LOC | 900 |
+| 单文件 import + require 数 | 35 |
+| 单文件 export 数 | 25 |
+| TODO/FIXME 总数 | 40 |
+| `lib/` 模块数 | 110 |
+
+## Soft targets（超出记为债务，不阻断发布）
+
+| 维度 | Soft target |
+|---|---|
+| 单文件 LOC | 600 |
+| 单文件 import + require 数 | 20 |
+| 单文件 export 数 | 18 |
+| TODO/FIXME 总数 | 10 |
+| `lib/` 模块数 | 95 |
+
+超出 soft target 但在 hard limit 内的项，会在复杂度报告中列为 soft 警告，并应登记到
+[COMPLEXITY_DEBT.md](COMPLEXITY_DEBT.md)。
+
+## 模块新增规则
+
+1. **禁止新增无依据模块**。任何新增 `lib/` 模块必须有明确依据（治理/安全/兼容），
+   并在 PR 描述与 CHANGELOG 中说明，否则视为预算违规。
+2. **one-in-one-out**：维护期内每新增一个非必要模块，应同步合并/删除一个等量模块，
+   使 `lib/` 模块数保持稳定（目标 ≤ soft target 95）。
+3. 治理/基础设施工具（如本复杂度治理自身）可作为一次性有依据的例外，但仍计入 `lib/` 模块数预算。
+
+## 依赖规则
+
+- **不允许新增运行时依赖**，除非经过明确批准并记录在案。
+- 复杂度治理工具仅使用 Node 内置模块（`fs` / `path`），不引入任何第三方包。
+- `package.json` 不得出现 `dependencies` 字段；如需新增请先走批准流程。
+
+## 调整预算的流程
+
+收紧或放宽任一 limit 都是**显式治理动作**：
+
+1. 修改 `lib/complexity.js` 中的常量。
+2. 同步更新本文件对应表格。
+3. 在 CHANGELOG 记录原因。
+4. 确认 `npm run check`、`npm test`、`npm run complexity:check`、`npm run release:check` 全部通过。