@mison/ling 1.0.0

package/.spec/references/gda-framework.md

@@ -0,0 +1,394 @@
+# GDA Framework
+
+## 1. 为什么这个 skill 需要总体设计视角
+
+从工程实践看：
+
+- 初级工程师关注语法和框架
+- 中级工程师关注算法和模式
+- 高级工程师真正解决的是：**如何控制复杂性**
+
+这个 skill 的理论底座来自两个方向：
+
+1. **系统工程**
+   - 关注总体目标、边界、分解、集成、组织
+2. **工程控制论**
+   - 关注反馈、稳定性、时滞、噪声、鲁棒性、调节策略
+
+把它们映射到软件工程，核心不是数学推导，而是：
+
+- 把软件系统当作可观测、可控制、会受扰动、会振荡的复杂系统
+
+## 2. 五大维度
+
+### 2.1 第一性原理
+
+先问：
+
+- 业务真正目标是什么
+- 物理极限是什么
+- 什么是不变量
+- 什么是绝对不能妥协的约束
+
+软件中的等价问题：
+
+- 吞吐 vs 一致性
+- 延迟预算
+- 网络 RTT
+- 磁盘 IOPS
+- 内存 / 缓存边界
+
+对应方法：
+
+- 约束驱动设计
+
+### 2.2 公理化思维
+
+系统必须建立在少数不可推翻的契约上：
+
+- API 契约
+- schema 契约
+- 状态机合法跃迁
+- 事件语义
+
+软件中的反面典型：
+
+- 模块越权访问
+- 影子实现
+- 同一状态有两套解释
+
+对应方法：
+
+- 定义即防御
+- 契约优先于实现
+
+### 2.3 多模型思维
+
+复杂系统不能只用一种图来理解。
+
+至少应切换三种模型：
+
+1. 数据流模型
+2. 状态机模型
+3. 时序 / 并发 / 排队模型
+
+软件中的典型价值：
+
+- 同步 RPC 看不清的问题，换成事件流模型会更清楚
+- OOP 卡住的高并发状态流转，换成 Actor / 队列模型更稳定
+- 代码 profiler 看不清的延迟问题，用排队模型更直观
+
+对应方法：
+
+- 正交投影建模法
+
+### 2.4 类比迁移能力
+
+软件系统没有物理形体，但可以寻找物理同构：
+
+- 限流 / 降级 -> 漏桶 / 令牌桶
+- 自动扩缩容 -> PID
+- 消息队列 -> 水库 / 缓冲池
+- 熔断 -> 自动断路器
+
+当系统出现：
+
+- 拥堵
+- 雪崩
+- 震荡
+- 超调
+
+就应该主动寻找物理世界中的成熟控制经验。
+
+### 2.5 反馈与验证能力
+
+没有反馈回路的系统，等价于盲飞。
+
+必须有：
+
+- metrics
+- logs
+- traces
+- replay / repro
+- tests / benchmarks / gate
+
+尤其要关注：
+
+- 时滞
+- 非线性
+- 噪声
+- 偶然通过的测试
+
+## 3. GDA 四步法
+
+### Step 1: Axiom & Boundary
+
+执行动作：
+
+1. 明确系统最终目标
+2. 写出不变量
+3. 列出硬约束
+4. 算清物理边界
+
+产物：
+
+- 控制合同（Control Contract）
+- 边界清单
+- 风险清单
+
+### Step 2: Multi-model Construction
+
+执行动作：
+
+1. 建立静态契约域
+   - API
+   - schema
+   - 配置
+   - 事件格式
+2. 建立动态状态域
+   - 状态机
+   - 生命周期
+   - 状态收口
+3. 建立容量与排队域
+   - 队列
+   - 缓冲
+   - 背压
+   - 瓶颈
+
+产物：
+
+- 最小系统图
+- 状态机图或文字版
+- 容量/时滞估计
+
+### Step 3: Cybernetic Control
+
+执行动作：
+
+1. 识别主要误差
+2. 选择最小控制输入
+3. 一次只改一类问题
+4. 防止振荡
+
+典型控制动作：
+
+- 缩小改动范围
+- 加强可观测点
+- 从大修退回最小修复
+- 从“改实现”切换到“补测试/补契约/修接口”
+
+### Step 4: Closed-loop Observability
+
+执行动作：
+
+1. 分层验证
+   - L0：快回路
+   - L1：中回路
+   - L2：慢回路
+2. 明确什么只能在真实环境验证
+3. 沉淀 review / gate / handoff 文档
+
+产物：
+
+- 测试矩阵
+- 审计报告
+- gate 文档
+- handoff
+
+## 4. 对软件架构师的直接启示
+
+### 4.1 不是先选技术，而是先选控制目标
+
+错误问题：
+
+- 用什么数据库？
+- 上不上微服务？
+
+正确问题：
+
+- 哪个指标必须优先满足？
+- 哪个不变量绝不能破？
+- 哪个失败模式必须被优先吸收？
+
+### 4.2 不是先加抽象，而是先界定契约
+
+错误问题：
+
+- 如何把实现写得更“通用”？
+
+正确问题：
+
+- 什么应该是 public？
+- 什么只是测试方便，不该变成公共 API？
+- 什么是模块的业务区位？
+
+### 4.3 不是所有“通过测试”都等于问题解决
+
+必须区分：
+
+- 语义测试
+- schema 契约测试
+- 主链测试
+- 真实环境 gate
+
+这是本 skill 最关键的现实原则之一。
+
+## 5. 使用这个 skill 时的输出风格
+
+默认要求输出这些内容中的大部分：
+
+1. 当前误差是什么
+2. 当前系统状态估计是什么
+3. 当前改动为什么是最小控制输入
+4. 验证层次是什么
+5. 哪些风险还没被闭环吸收
+
+## 6. 常见误区
+
+1. 把控制论理解成“堆术语”
+2. 把系统工程理解成“画更多图”
+3. 把离线通过等价为真实环境通过
+4. 把测试便利性凌驾于模块职责之上
+5. 把临时修复变成新的影子事实源
+
+## 7. 一页版执行模板
+
+### Control Contract
+
+- Primary Setpoint:
+- Acceptance:
+- Guardrail Metrics:
+- Sampling Plan:
+- Known Delays / Delay Budget:
+- Recovery Target:
+- Rollback Trigger:
+- Constraints:
+- Boundary:
+- Coupling Notes:
+- Approximation Validity:
+- Actuator Budget:
+- Risks:
+
+### State Estimate
+
+- Entry:
+- Key state:
+- Key invariants:
+- Current error signal:
+
+### Hypotheses
+
+1. H1:
+2. H2:
+3. H3:
+
+### Experiment Plan
+
+- E1:
+- E2:
+- E3:
+
+### Patch Plan
+
+- Step 1:
+- Step 2:
+- Step 3:
+
+### Verification
+
+- L0:
+- L1:
+- L2:
+
+### Recovery Evidence
+
+- Trigger:
+- Recovery time:
+- Rollback / restart:
+
+### Observability Evidence
+
+- Metrics / traces:
+- Profiling baseline:
+- Before vs after:
+
+### Residual Risks
+
+- Risk 1:
+- Risk 2:
+
+## 8. 现代映射附录
+
+这一节不是重复主 skill，而是把《论系统工程》《工程控制论》的经典问题，映射到云原生、分布式和 AI 原生工程语境。
+
+### 8.1 系统工程总体设计 -> 云原生总体控制结构
+
+- 经典问题：
+  - 如何为一个大系统建立总体设计部，统一目标、边界、分工与集成
+- 现代映射：
+  - 平台团队、架构委员会、共享边界 owner、发布治理和统一门禁
+- 典型例子：
+  - 微服务拆分后，团队不再只管“自己的服务”，还要定义共享 API、共享 schema、mesh 策略和发布窗口
+
+### 8.2 时滞 -> 异步传播、CI 排队、缓存刷新与灰度延迟
+
+- 经典问题：
+  - 时间延迟会让原本稳定的系统出现低频振荡
+- 现代映射：
+  - 异步队列传播、CDN 或缓存刷新、控制面配置下发、CI 队列、灰度生效延迟
+- 典型例子：
+  - 你刚调了限流参数，dashboard 还没刷新，第二次调参就已经把系统推过头了
+
+### 8.3 采样 -> 监控抓取周期、批量上报与窗口聚合
+
+- 经典问题：
+  - 离散采样会带来别名和误判
+- 现代映射：
+  - metrics 抓取周期、日志批量上传、trace 采样率、profiling 采样窗口
+- 典型例子：
+  - 用 1 分钟粒度看 5 秒一个周期的抖动，会把真实震荡看成偶发现象
+
+### 8.4 反馈 -> 自动扩缩容、重试、熔断、回滚控制器
+
+- 经典问题：
+  - 反馈能增强稳定性，但错误反馈也会放大震荡
+- 现代映射：
+  - HPA、队列消费调度、自动回滚、熔断半开、重试预算控制
+- 典型例子：
+  - HPA、应用内重试和网关重试同时工作时，系统不再是单控制器，而是耦合反馈系统
+
+### 8.5 解耦 -> 输入输出影响矩阵与平台边界
+
+- 经典问题：
+  - 多变量系统要先解耦，否则一个输入会同时打坏多个输出
+- 现代映射：
+  - 限流参数、缓存策略、连接池、批量大小、并发度这些高耦合 knob 的影响矩阵
+- 典型例子：
+  - 调大重试可能抬高成功率，但也会同时抬高延迟、成本和队列长度
+
+### 8.6 噪声 -> flake、监控抖动、依赖 brownout
+
+- 经典问题：
+  - 噪声会污染观测，使错误控制建立在伪信号上
+- 现代映射：
+  - flaky test、监控抖动、短时网络毛刺、依赖 brownout、缓存击穿带来的尖峰
+- 典型例子：
+  - 把短时 brownout 当成永久故障，会触发错误的扩容、回滚或切流
+
+### 8.7 自适应 -> 在线调参、搜索、学习型控制
+
+- 经典问题：
+  - 当环境持续变化时，固定控制律会失效
+- 现代映射：
+  - 自适应限流、动态并发、在线容量预测、带反馈的调参系统、AI agent 的在线策略更新
+- 典型例子：
+  - AI 原生系统中，固定 prompt 路由和固定超时很快会老化，必须让策略能根据观测在线修正
+
+### 8.8 冗余 -> 多副本、双写、影子链路与容错恢复
+
+- 经典问题：
+  - 用不可靠部件构造可靠系统，要靠冗余、仲裁和恢复
+- 现代映射：
+  - 多副本部署、跨可用区、双写双读、shadow 流量、冷备热备、幂等恢复
+- 典型例子：
+  - 双写不是“多一份保险”，而是引入了新的对账、顺序和一致性问题，必须被当成状态面控制问题

package/.spec/references/harness-engineering-digest.md

@@ -0,0 +1,93 @@
+# Harnesses are underrated 文章蒸馏
+
+## 文章信息
+
+- 标题: Harnesses are underrated
+- 来源: OpenAI
+- 发布时间: 2025-07-31
+- 作者: Boris Power、Brendan Dolan-Gavitt、Calvin French-Owen、Charles Lamanna、Katie Gamanji、Oliver Greenwood、Romain Huet
+- 链接: https://openai.com/index/harness-engineering/
+
+## 全文核心观点
+
+这篇文章的主张是：模型能力决定理论上限，但工程系统（harness）决定实际交付效果。  
+“好 harness”不是单一技巧，而是把代理放到真实工作回路里，让它能访问文档、代码、测试、CI 和故障反馈，并在明确的边界内迭代。
+
+## 关键内容蒸馏
+
+### 1. 先解决执行环境，再谈提示词细节
+
+- 让代理直接使用真实工具：代码库、测试命令、日志、PR、CI。
+- 如果代理无法运行或验证改动，即使模型很强也难以稳定产出。
+- 实践里，基础 harness 的改进经常比微调提示词更有效。
+
+### 2. 给代理“可控自主权”
+
+- 不要把代理变成每一步都等待人工确认的脚本。
+- 在可控预算内允许代理先自行尝试并迭代。
+- 自主执行必须伴随可观测性：每次尝试有明确输入、输出和失败信号。
+
+### 3. 用分层权限降低风险
+
+- 从低权限开始（读代码、查文档），按证据逐级放开（跑测试、改代码、执行受限操作）。
+- 权限升级应有触发条件；失败应能回滚到安全级别。
+- 这样既提高成功率，也减少误操作风险。
+
+### 4. 明确定义“何时请求人工”
+
+- 不是遇到问题就立刻抛给人，也不是无限重试。
+- 需要在系统层面定义求助阈值，例如：
+  - 同类失败重复出现；
+  - 关键信息缺失；
+  - 需要越权或高风险动作；
+  - 多方案权衡需要业务取舍。
+- 求助请求应包含证据和候选方案，便于人快速决策。
+
+### 5. 把 agent 纳入 CI 回路
+
+- 让代理并行尝试修复，CI 作为客观判定器。
+- 失败时把上下文移交人工，而不是隐藏失败。
+- 这种人机接力可以缩短故障恢复时间。
+
+### 6. 关注真实指标，而非演示效果
+
+- 衡量指标应围绕真实交付：任务闭环率、修复成功率、回归通过率、人工介入频次、平均修复时间。
+- 文章案例强调：当 harness 做对后，任务完成率会明显提升。
+
+## 文中提到的案例信号
+
+- 在 HumanEval 场景，完善 agent-only harness 后，完成率可从接近 0 提升到约 50% 量级。
+- 在 SWE-bench Verified 场景，先达到约 65%，继续优化 harness 后可到约 75%。
+- 文中还给出团队实践信号：通过强化 harness，任务解决率可从约 28% 提升到约 65%。
+
+## 与“人机协作/主动请求”直接相关的落地规则
+
+1. 先让代理独立跑到“可证明卡住”为止，再请求人工。  
+2. 请求人工时只问一个关键决策，并给出 A/B/C 选项。  
+3. 每个选项明确成本、风险、收益与时间。  
+4. 人工确认后，代理继续执行并返回证据，而不是重复讨论。  
+5. 将协作过程写入任务日志，保持可追溯。
+
+## 可直接复用的求助阈值
+
+- 连续 2-3 次同类失败，且错误模式一致。
+- 缺失关键上下文，无法再通过本地推断补足。
+- 需要生产级权限、外网访问、密钥或不可逆操作。
+- 变更范围超出既定边界，可能影响无关模块。
+
+## 可直接复用的求助结构
+
+1. 当前阻塞（一句话）。  
+2. 已尝试动作与证据（命令、日志、结果）。  
+3. 根因假设（含置信度）。  
+4. 备选方案 A/B/C（成本、风险、预计耗时）。  
+5. 需要人工确认的唯一问题。  
+
+## 与 skill 的关系
+
+本目录下的 `SKILL.md` 把这些原则转成可执行流程，重点覆盖：
+- harness 先行；
+- 自主执行预算；
+- 主动求助阈值；
+- 选项型协作提问；
+- 可追溯交付收束。