Zane/obsidian-notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

更新笔记

Browse Source
This commit is contained in:
Build Bot
2026-07-02 00:39:46 +08:00
parent a1edb6f04f
commit ccd777398a
13 changed files with 308 additions and 1260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
1Project/Project-Monopoly/docs/feat-runner-flow-config/01-scope-and-contract.md Normal file
View File

@@ -0,0 +1,69 @@
# 01 Scope And Contract
## Goal
冻结 `style.runner` 的流派身份、主循环和接入契约，让后续配置和实现都围绕同一套目标收敛。
## Depends On
- `docs/README.md`
- 当前项目里已经存在的 `style.runner` 起始入口
- 当前项目里已经存在的奖励轮 / 商店轮 `flowId` 分流能力
- 当前项目里已经存在的遗物触发节点、移动结算和强化包体系
## Assumes
- 第一流派不新增回合状态，不改战斗轮、奖励轮、商店轮的既有顺序。
- 第一流派不引入新的奖励类型，仍复用“强化包 / 遗物 / 特殊商店”三类候选。
- 第一流派只要求现有触发面支持：
- 掷骰结算后
- 每移动一步
- 经过起点
- 回合结束
- 进入商店
- 第一流派默认仍使用现有 `style.runner` 起始遗物语义，不推翻当前角色选择入口。
## Stable Truth
`style.runner` 的核心体验不是“赌大点数”，也不是“经营地块”，而是：
- 尽量把每轮行动变成更多有效位移
- 把“过起点”做成稳定收益线
- 把“多移动一次”转换成真实分数，而不只是空跑
这套流派的玩家心智应该是：
- 我想多走
- 我想再过一次关键线
- 我想把走出来的节奏继续滚大
## 流派边界
这个流派应该擅长：
- 高频移动
- 稳定过起点收益
- 低单次爆发、强连续收益
- 用低费补件快速成型
这个流派不应该主打：
- 单回合骰面核爆
- 地块升级复利
- 高价商店大件一锤定音
## 主循环
一轮的核心循环固定为：
1. 通过起始遗物或奖励件争取额外移动价值。
2. 让移动过程尽量多产出“经过起点”或“步数转收益”。
3. 在奖励轮优先补齐移动链条缺口，而不是盲目拿高稀有度。
4. 在商店轮优先买频率件和倍率件，不鼓励长期囤钱。
## Done Signals
- `style.runner` 的身份、擅长点和非目标已经明确。
- 奖励轮 / 商店轮的 `flowId` 已冻结为稳定命名。
- 后续内容设计都能判断“是否服务于移动收益主循环”。
- 后续实现不需要再争论这个流派到底是“跑圈”还是“骰面爆发”。

108
1Project/Project-Monopoly/docs/feat-runner-flow-config/02-content-pools.md Normal file
View File

@@ -0,0 +1,108 @@
# 02 Content Pools
## Goal
定义 `style.runner` 的第一版内容池结构，让奖励轮、商店轮和起始配置能围绕同一条成长路线协同工作。
## Depends On
- `docs/feat-runner-flow-config/01-scope-and-contract.md`
## Assumes
- 第一版优先做 1 个起始遗物、6 到 8 个核心遗物、2 到 3 个强化包方向。
- 第一版奖励轮至少要保证：
- 1 个顺势强化选项
- 1 个经济或续航选项
- 1 个可转向但不偏题的保险选项
- 第一版商店轮优先调权重，不追求复杂商店专属规则。
## 起始配置
- 起始流派：`style.runner`
- 起始遗物：`relic.common.run_shoes`
- 起始遗物职责：
- 让玩家第一时间理解“多移动就是赚”
- 给出最直观的位移收益感
- 不承担复杂条件判定
## 奖励轮流向
- RewardFlowId: `flow.runner.reward.v1`
- 候选偏好顺序：
1. 移动频率件
2. 过起点收益件
3. 移动转分数件
4. 低门槛经济件
5. 仅在缺件时出现的保底件
奖励轮应避免：
- 连续两轮都只给高费慢热件
- 给出明显偏地产或偏骰面爆发的主件
- 让玩家在前两轮就被迫拿到与“跑圈”无关的核心件
## 商店轮流向
- ShopFlowId: `flow.runner.shop.v1`
- 商店应优先上架：
- 低费移动件
- 低费过起点倍率件
- 中费节奏维持件
- 商店应降低权重：
- 高价慢热经营件
- 只在大点数下生效的爆发件
- 过度依赖单次停留收益的件
## 核心遗物角色
第一版不先定满所有具体名字，先冻结功能槽位：
1. 步数增加件
- 作用：直接提升单轮有效移动长度。
2. 每 X 步触发件
- 作用：让长路径本身带有节奏奖励。
3. 过起点加分件
- 作用：把跑圈路线明确转成分数收益。
4. 每轮首次过起点倍率件
- 作用：提供中期乘区，不只是平推数值。
5. 非掷骰移动收益件
- 作用：容纳“再前进一步”类联动，提升连走价值。
6. 移动结算转金币件
- 作用：避免跑圈流过度缺钱，保持商店参与感。
7. 回合结束回收件
- 作用：给没能过线的轮次一个轻保底。
8. 轻连锁件
- 作用：在其他 runner 遗物触发时补一次小收益，但不把流派做成纯连锁流。
## 强化包方向
第一版强化包只做方向，不强求一次性做满：
1. 起点线强化
- 提升经过起点后的结算价值。
2. 直线节奏强化
- 提升长路径中的持续收益感。
3. 最低等级白地补值强化
- 给跑圈流一个弱经营抓手，但不改变其主身份。
## 选项结构规则
奖励轮三选一建议固定遵守：
- 一格“立即变强”
- 一格“中期滚大”
- 一格“资源或保底”
商店三选一建议固定遵守：
- 一格低费补件
- 一格中费主件
- 一格偏经济或刷新决策件
## Done Signals
- 已经确定 runner 第一版的起始遗物职责。
- 已经确定奖励轮和商店轮的 `flowId`。
- 已经确定第一版核心遗物的功能槽位。
- 已经确定奖励轮与商店轮的基本出货结构。

81
1Project/Project-Monopoly/docs/feat-runner-flow-config/03-balance-and-validation.md Normal file
View File

@@ -0,0 +1,81 @@
# 03 Balance And Validation
## Goal
定义 `style.runner` 的成长节奏、失败风险、玩家可见反馈和最小验证口径，避免后续实现只有配置没有手感目标。
## Depends On
- `docs/feat-runner-flow-config/02-content-pools.md`
## Assumes
- 第一版不调整全局默认回合数、阶段数和大盘规则。
- 第一版只保证 runner 可以独立玩通，不要求现在就和 boxer、tycoon 完成横向平衡。
- 第一版优先验证“流派有感”，再做精细数值。
## 节奏目标
### 前期
- 第 1 到 2 个战斗轮就要让玩家明显感觉到“这套在多走”。
- 前期收益应以稳定、小额、连续触发为主。
- 前期最重要的是让玩家尽快见到第一次“过起点收益变大”的正反馈。
### 中期
- 中期必须出现至少一个乘区件，否则 runner 会变成纯平推数值。
- 中期的目标是让玩家开始规划“这轮能不能再过一次关键线”，而不是只按按钮掷骰。
### 后期
- 后期目标不是单次超大爆发，而是高频稳定结算。
- 后期应允许玩家通过移动链条形成连续收益，但不能无限滚雪球到完全无脑。
## 失败风险
runner 第一版最容易出现的失败形态有三种：
1. 只有多走，没有多赚
- 玩家看起来跑得很快，但得分和金币没有同步放大。
2. 只靠过起点，离开起点就空转
- 流派路径被做得过窄，导致地图体验单一。
3. 前期爽，后期没乘区
- 早期节奏很好，但越到后面越像低伤害平推流。
## 玩家可见反馈
HUD 至少要能稳定表达以下信息：
- 本轮是否已经触发“首次过起点”
- 距离下一次关键步数触发还差多少
- 当前 runner 收益更偏分数、金币还是保底
如果做轻量提示，优先顺序如下：
1. 下一次步数触发进度
2. 本轮首次过起点状态
3. 本回合 runner 额外收益汇总
## 最小验证口径
第一版 runner 只要满足以下路径，就算进入可试玩状态：
1. 选择 `style.runner` 开局。
2. 在前两轮至少能获得一次明显的移动收益正反馈。
3. 奖励轮能给出符合 runner 偏向的候选。
4. 商店轮能给出符合 runner 偏向的候选。
5. 至少存在一条“多移动 -> 过起点或步数触发 -> 分数增长”的稳定闭环。
## 非目标
- 当前不要求 runner 已经成为最终平衡答案。
- 当前不要求每个奖励件都有专属表现。
- 当前不要求与后续流派共享统一数值模板。
## Done Signals
- 已经定义 runner 的前中后期节奏目标。
- 已经定义 runner 的主要失败风险。
- 已经定义 HUD 至少需要表达的关键信息。
- 已经定义第一版可试玩的最小验证闭环。

41
1Project/Project-Monopoly/docs/feat-runner-flow-config/README.md Normal file
View File

@@ -0,0 +1,41 @@
# Runner 流派配置 feat
## 目标
先把第一个流派 `style.runner` 定义成一套可持续扩展、可接到现有奖励轮和商店轮体系里的主线配置文档。
这个 feat 只定义稳定主线真相：
- 流派身份
- 核心循环
- 奖励轮与商店轮的 `flowId`
- 起始遗物与内容池边界
- 平衡节奏与最小验证口径
这个 feat 暂不包含：
- 具体代码改动
- 具体数值表落地
- 最终奖励表 JSON / Luban 表项录入
- 第二、第三流派的对齐工作
## 已确认结论
- 第一个落地流派就是 `style.runner`，对应当前项目里的“跑格子”原型身份。
- 这套流派优先围绕“移动次数、过起点次数、移动结算转收益”展开，不引入新的大系统。
- 奖励轮与商店轮都应通过独立 `flowId` 表达偏向，而不是靠文案或散落权重隐式区分。
## 推荐运行时标识
- PlaystyleId: `style.runner`
- RewardFlowId: `flow.runner.reward.v1`
- ShopFlowId: `flow.runner.shop.v1`
## 文档顺序
- `01-scope-and-contract.md`
- 定义这个流派是什么，不是什么，以及它依赖哪些既有系统。
- `02-content-pools.md`
- 定义核心遗物、强化包、奖励轮和商店轮的内容结构。
- `03-balance-and-validation.md`
- 定义成长节奏、失败风险、HUD 提示与最小验证口径。

2
1Project/独游-大富翁/遗物.md
View File

@@ -1,2 +0,0 @@
- 遗物激活飘名 测试
- 每个遗物效果测试

3
4Archives/Obsidian记录docs/构建命令.md Normal file
View File

@@ -0,0 +1,3 @@
Par Vault "Obsidian路径" 先定位ob笔记位置
Par "项目路径"

157
InBox/BV15F7J6dEdm-SSE-AI流式输出笔记.md
View File

@@ -1,157 +0,0 @@
# 别再只会 HTTP 了，SSE 才是 AI 流式输出的答案 | BV15F7J6dEdm
Milky 整理
## 协议对比：三种通信模式的本质差异
### HTTP 协议：懒惰的服务员
```
客户端发起请求 → 服务器响应 → 连接关闭 → 客户端再次发起请求 → ...
```
- 客户端主动发起请求，服务端被动响应
- 一问一答模式，服务端不能主动推送消息
- 无状态、单次请求
- 连接在每次响应后立即关闭
适用场景：普通接口查询、网页加载、表单提交、简单数据获取
轮询问题：网络开销大、延迟、实时性差
### SSE 协议：勤快的服务员
```
客户端发起一次请求 → 服务端持续主动推送 → 直到传输结束
```
- 客户端只需发送一次请求
- 服务端主动、持续推送消息
- 单向通信（服务端 → 客户端）
- 长连接保持
适用场景：AI 大模型流式输出、外卖/订单进度推送、股票 K 线图、监控仪表盘、任何需要服务端主动推送文本数据的场景
### WebSocket 协议：随身对讲机
- 双向通信
- 客户端和服务端角色对等
- 实现复杂度最高
适用场景：实时聊天室、语音问答/交互、在线课堂、需要双向实时交互的场景
### 三种协议对比
| 特性 | HTTP | SSE | WebSocket |
|------|------|-----|-----------|
| 通信方向 | 单向（客户端→服务端） | 单向（服务端→客户端） | 双向 |
| 服务端主动推送 | ❌ | ✅ | ✅ |
| 连接类型 | 短连接 | 长连接 | 长连接 |
| 实现难度 | ⭐ 最简单 | ⭐⭐ 中等 | ⭐⭐⭐ 复杂 |
| 数据格式 | 任意 | 文本数据 | 二进制/文本均可 |
| 客户端发送消息 | 需新建请求 | 需新建请求 | 随时可发 |
## 为什么 AI 流式输出首选 SSE？
- **HTTP 的问题**：大模型自回归生成，用户等待 1-2 分钟才能看到完整回复，无法流式体验
- **WebSocket 的问题**：实现复杂成本高，AI 对话场景不需要双向通信
- **SSE 的优势**：完美匹配 AI 流式输出，一次请求服务端持续推送增量结果，实现简单
## SSE 协议详解
### 典型交互过程
```
客户端 → HTTP GET 请求 → 服务器
客户端 ← 响应头 text/event-stream ← 服务器
客户端 ← 持续推送事件流 ← 服务器
客户端 ← 推送结束 ← 服务器
```
### 响应头
| 字段 | 值 | 说明 |
|------|-----|------|
| Content-Type | text/event-stream | 标识事件流 |
| Cache-Control | no-cache | 不缓存 |
| Connection | keep-alive | 保持连接活跃 |
### 协议格式（四个字段）
```
field: value\n\n
```
| 字段 | 说明 | 示例 |
|------|------|------|
| data | 消息数据 | data: {"content": "你好"} |
| event | 事件类型（可自定义） | event: message |
| id | 消息ID（断线重连） | id: 1 |
| retry | 重连间隔（毫秒） | retry: 5000 |
### 结束传输的四种方式
1. 强制断开连接
2. 自定义结束事件：`event: done`
3. 自定义结束标识：`data: [DONE]`
4. 业务字段标识：`data: {"content": "...", "finish": true}`
## FastAPI SSE 实战
### 前置知识
- Pydantic 数据模型 —— FastAPI 自动 JSON ↔ Python 对象转换
- EventSource API —— 浏览器原生 SSE 客户端
- Python yield 关键字 —— 生成器，逐次生成数据流
### 代码实现
FastAPI 0.135+ 原生支持 SSE，使用 `EventSourceResponse` + `AsyncGenerator[ServerSentEvent]`
```python
from fastapi import FastAPI
from fastapi.responses import EventSourceResponse
from sse.starlette.sse import ServerSentEvent
from pydantic import BaseModel
from typing import AsyncGenerator
app = FastAPI()
class ChatRequest(BaseModel):
message: str
async def event_generator(req: ChatRequest) -> AsyncGenerator[ServerSentEvent, None]:
response_text = f"你问的是: {req.message}\nSSE 是一种服务端推送协议..."
words = response_text.split()
for i, word in enumerate(words):
is_final = (i == len(words) - 1)
yield ServerSentEvent(
event="message",
data=f'{{"content": "{word} ", "isfinal": {is_final}}}'
)
@app.post("/chat/stream")
async def chat_stream(req: ChatRequest):
return EventSourceResponse(event_generator(req))
```
启动：`uvicorn main:app --reload`
### 客户端调用
- **JavaScript fetch + ReadableStream**：逐块读取并解析 SSE 数据
- **EventSource API**：浏览器原生，监听 message / 自定义事件
## 总结
| 概念 | 说明 |
|------|------|
| SSE | Server-Sent Events，服务端推送事件协议 |
| 核心优势 | 单次请求 + 服务端持续推送 + 实现简单 |
| 最佳场景 | AI 大模型流式输出、实时进度推送 |
| 协议格式 | data / event / id / retry 四个字段 |
| 结束方式 | 断开连接 / 自定义事件 / 特殊标识 / 业务字段 |
| FastAPI 集成 | 0.135+ 原生支持，使用 EventSourceResponse |
──────────────────────────────
Generated by MilkyAi@Bilibili

117
InBox/BV1if7E64Ex5-SSE-FastAPI流式响应笔记.md
View File

@@ -1,117 +0,0 @@
# SSE 到底是什么？用 FastAPI 一次讲透流式响应 | BV1if7E64Ex5
Milky 整理
## 一、三种通信协议对比
| 协议 | 类比 | 特点 |
|------|------|------|
| HTTP | 懒惰的服务员 | 你问一次，他答一次，服务器无法主动推送 |
| SSE | 勤快的服务员 | 只需要开口说一次，他会主动汇报最新进度 |
| WebSocket | 双方都带着对讲机 | 任何一方都可以随时主动说话，完全平等的双向通信 |
## 二、SSE 协议的适用场景
- **HTTP**：必须等模型生成完所有内容才能一次性返回，用户等待时间过长
- **WebSocket**：功能强大但成本高，且大多数 AI 场景中用户不需要主动发消息
- **SSE**：只发起一次请求，服务器边生成边推送，用户实时看到文字逐字出现
## 三、SSE 工作原理详解
### 完整流程
```
客户端 → 普通 HTTP 请求 → 服务器
客户端 ← Content-Type: text/event-stream ← 服务器
客户端 ← Connection: keep-alive ← 服务器
客户端 ← 持续推送事件数据 ← 服务器
客户端 ← event: done / data: [DONE] ← 服务器
```
### HTTP 响应头
```
Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
```
### SSE 消息格式
| 字段 | 作用 |
|------|------|
| data | 消息内容 |
| event | 事件类型 |
| id | 消息编号 |
| retry | 断线重连间隔（毫秒） |
每条消息之间用空行分隔。
### 浏览器端接收
```javascript
const source = new EventSource('/stream');
source.onmessage = (event) => {
console.log(event.data);
};
```
## 四、FastAPI 核心前置知识
- 与 Pydantic 深度绑定，自动请求解析和响应序列化
- 自动生成交互式 API 文档（/docs）
- 原生支持 async/await 异步编程
## 五、生成器（Generator）与 yield 关键字
yield 函数的四个特点：
1. 用 yield 代替 return
2. 执行到 yield 暂停并返回值
3. 下次调用从 yield 后继续
4. 按需产生数据，适合流式场景
## 六、完整 FastAPI SSE 实现
### 环境要求
```
FastAPI >= 0.135
```
### 代码
```python
from fastapi import FastAPI
from fastapi.responses import EventSourceResponse
from sse.starlette.sse import ServerSentEvent
from pydantic import BaseModel
app = FastAPI()
class ChatRequest(BaseModel):
message: str
@app.post("/stream")
async def stream_chat(request: ChatRequest):
async for chunk in model_stream(request.message):
if chunk == "[DONE]":
return
yield ServerSentEvent(data=chunk)
```
### 核心公式
```
EventSourceResponse + yield ServerSentEvent
```
## 七、三种协议总结对比
| 协议 | 实现复杂度 | 推送方向 | 适用场景 |
|------|-----------|----------|----------|
| HTTP | ⭐ 最简单 | 仅服务端响应 | 简单的一问一答 |
| SSE | ⭐⭐ 中等 | 服务端持续推送 | AI 流式输出、实时通知 |
| WebSocket | ⭐⭐⭐ 复杂 | 双向通信 | 需要客户端主动发消息的场景 |
──────────────────────────────
Generated by MilkyAi@Bilibili

63
InBox/BV1wPEm6DEzS-ToolUse-FunctionCalling笔记.md
View File

@@ -1,63 +0,0 @@
# 从原理到代码，讲清楚大模型的 Tool Use 和 Function Calling | BV1wPEm6DEzS
Milky 整理
## 概念解析
| 术语 | 定义 | 特点 |
|------|------|------|
| Function Calling | 大模型基于用户输入，自主决策是否调用外部工具的机制 | 专注于函数调用的决策能力 |
| Tool Use | 将函数定义拓展为更广泛概念的工具调用模式 | 可包装 API、数据库操作、复杂操作等多种形式 |
目前业界基本用 Tool Use 来涵盖 Function Calling 的含义。
## 核心价值
- 连接外部世界：突破训练数据限制，访问实时信息
- 转化推理能力：将推理能力转化为实际行动
- 扩展能力边界：计算、数据库、外部服务调用
## 调用流程（六步）
1. **工具定义**：告诉大模型有哪些工具可用
2. **自主决策**：大模型判断是否需要调用工具
3. **生成调用指令**：输出工具名和参数
4. **捕获信号**：系统拦截 tool_calls 信号
5. **执行工具**：系统层执行工具，获取结果
6. **回传结果**：返回给大模型，生成最终回复或继续循环
## 代码实战：贷款计算器
### 工具函数定义 + JSON Schema 描述
- 函数用 `tools` 数组描述，含 name/description/parameters
- 描述必须详细，"掰开揉碎"，因为大模型只认文字
### 传给大模型
- `tool_choice="auto"` 让模型自主决策
- 返回 `finish_reason: "tool_calls"` 时表示要调工具
### 系统层拦截执行
- 建立 `function_map` 映射函数名到实际函数
- 解析 `tool_calls` 中的 name + arguments
- 执行后把结果以 `role: "tool"` 追加到消息上下文
- 必须带上 `tool_call_id` 关联
### 再次调大模型生成最终回复
## 关键原理
| 场景 | finish_reason | content | tool_calls |
|------|---------------|---------|------------|
| 调用工具 | tool_calls | None | 有值 |
| 不调用工具 | stop | 有值 | None |
- **职责分离**：模型只生成调用提示，系统层执行
- **上下文完整性**：消息必须包含完整链路（问题→调用→结果→回复）
- **自动总结**：模型天然具备根据工具返回生成回复的能力（训练时学过）
## 补充：Tool Use 与 MCP 的关系
视频末尾留了问题——Tool Use 和 MCP 的区别与联系，后续展开。
──────────────────────────────
Generated by MilkyAi@Bilibili

76
InBox/BV1xCKD6qEXW-Ponytail插件笔记.md
View File

@@ -1,76 +0,0 @@
# Ponytail 插件实测：AI 代码量暴跌 54%，代价是什么？ | BV1xCKD6qEXW
Milky 整理
## 简介
Ponytail（马尾辫）—— 强迫 AI 写更少代码的插件。核心理念：能用一行搞定不写一页，能用第三方库不自己重写。
### 核心数据
| 指标 | 改善幅度 |
|------|----------|
| 代码量 | 减少 54% |
| Token 消耗 | 减少 22% |
| 调用费用 | 减少 20% |
| 开发速度 | 提升 27% |
| 健壮性和安全性 | 保持 100% |
两周获 62K Star。
## 三种工作模式
| 模式 | 行为 |
|------|------|
| Lite | 正常开发，完成后推荐更简单的替代方案，开发者决定是否采用 |
| Full | 写代码前必须考虑 6 个问题（是否必要？标准库？原生平台？已有依赖？单行？→ 最少代码） |
| Ultra | 删除胜过新增，强烈质疑和挑战需求合理性 |
## 安装（Claude Code）
```
插件市场 → 搜索 "Ponytail" → 安装
/ponytail setup # 配置状态栏
reload plug # 激活
/ponytail enable # 启用
```
切换模式在状态栏操作，模式跨会话共享。
## 代码审查
| 命令 | 范围 |
|------|------|
| review | 未提交代码 |
| audit | 整个代码库 |
5 类标签：Delete（冗余代码）、Stdlib（可用标准库）、Native（平台原生支持）、YAGNI（你不会用到它）、Refactor（精简重构）
## Ponytail Debt（技术债收集）
开发时 AI 会为未来可能需要重构的代码添加 `ponytail` 注释。`/get ponytail-debt` 收集为报告。
## 实战测试
电商网站，Mini Max 3，各约 1.5 小时。
| 版本 | 代码行数 |
|------|----------|
| 不使用 | 7700+ 行 |
| 使用 | 4200+ 行 |
| 差距 | 3500+ 行 |
功能差异明显：不使用版功能更完整（商品分类/图片/评价管理/用户管理），使用版功能更精简（缺商品分类/图片/评价管理），但两个版本第一版都有较多 bug。
## 优缺点
✅ 减少代码量、降低费用、提升速度、健壮性不受影响
⚠️ 功能过于简洁，细节被省略，需求不明确时 AI 发挥空间不足
## 使用建议
- **前端开发、需求不明确** → 关闭，让 AI 自由发挥
- **后端开发、有明确标准**（JWT、数据库等）→ 开启，严格执行
──────────────────────────────
Generated by MilkyAi@Bilibili

2
InBox/milky_milky_2636.md
View File

@@ -23,7 +23,7 @@ Josh Pigford 在卖掉 Baremetrics 后，选择以一人公司模式同时开发
一、Josh 的 5 款产品一览
| 产品名称 | 功能描述 | 状态 |
|---------|---------|------|
| ------------ | --------------------------------------------------- | ------- |
| Proxyuser | 合成用户测试工具，用真实浏览器自动 QA 应用，生成屏幕录制帮助快速定位 bug | 刚发布 |
| Rumored | LLM 幻觉检测器，监控 AI 是否错误引用品牌信息（网站文案、博客内容、schema 代码等） | 周五刚发布 |
| Reply Social | 社交媒体统一回复管理工具，内置 Bot Block 功能，支持 Facebook、Reddit 等平台 | 早期版本已发布 |

785
InBox/zhihu_QQ音乐HarnessEngineering实践.md
View File

@@ -1,785 +0,0 @@
---
title: "QQ音乐Harness Engineering实践"
source: "知乎 - 鹅厂架构师"
url: "https://zhuanlan.zhihu.com/p/2041178181210748380"
date: 2026-06-09
tags: [zhihu, harness-engineering, ai-coding, vibe-coding, qq-music]
type: article
---
# QQ音乐Harness Engineering实践
> 作者：腾讯工程师 koka
导语当 AI 开始快速生成大量代码，真正的瓶颈就不再是"写不出来"，而是"看不完、想不清、管不住"。 本文基于一个落地在大仓多服务（Monorepo Microservices）场景中的开源工程框架，回答一个核心问题：如何把 AI 协作从对话式编码，升级为可控、可审计、可复用的工程过程？
作者：腾讯工程师 koka
1. 从 "Vibe Coding" 到 Harness Engineering
AI 辅助编程的发展脉络，大致经历了三代演进：代码补全 → 对话式编码（Chat） → 自主式 Agent。每一代都在提升 AI 的自主性，但同时也把一个更深层的问题暴露得更彻底。
在对话式编码阶段，一种典型的工作模式逐渐流行：开发者把需求丢给 AI，扫一眼输出"看起来对"就直接采纳，不审 diff、不追问逻辑、不验证边界。Andrej Karpathy 给这种做法起了一个名字 —— vibe coding：凭感觉写代码。在脚手架搭建、原型验证、一次性脚本等低风险场景下，vibe coding 确实好用 —— 简单、快、爽，几乎没有认知负担。
然而，一旦进入生产级代码库，vibe coding 的三个结构性缺陷会迅速暴露：
| 维度 | vibe coding 的典型表现 | 生产级工程的要求 |
| 信息损耗 | 同一句话多次执行给出不同实现；AI 按自己的理解"猜"需求 | 需求→设计→代码每一步都要有显式产出和可追溯关系 |
| 知识孤岛 | AI 只知训练语料里的通用知识，不懂团队历史决策和私有约束 | 团队知识需要被持久化为 AI 可消费、可演进的工程制品 |
| 验证断档 | "能跑"就直接提交，概率性错误顺着 MR 滑进主干 | 每个关键节点都要有可机读的质量门禁和审计记录 |
GitHub、Anthropic 等机构的公开研究都指向同一个结论：AI 能显著提升编码效率。但这里有一个容易被忽略的配套事实 —— 生成速度在提升，验证能力却没有同步提升。代码出得越快，错误积累得也越快；AI 自主性越强，偏离正确轨道时的修正成本就越高。生成快、验证慢、错误累积 —— 这就是 AI 时代软件工程的核心矛盾。
解决这个矛盾，靠的不是更长、更复杂的 prompt，而是工程化。
Harness Engineering 的核心理念是：AI 参与问题分析、方案设计、编码实现、审查和验证，但最终判断权始终留在工程师手中。Engineering 的本质是约束下的优化 —— 在质量、安全、可维护性等约束下寻找最优可行解。Harness Engineering 正是在这个框架里把 AI 当作协作者，而不是让 AI 成为"绕过约束的捷径"。
换一种说法：vibe coding 的底层逻辑是"让 AI 尽量自由地生成"，而 Harness Engineering 的底层逻辑是"让 AI 在正确的轨道上尽量高效地生成"。自由和高效并不矛盾 —— 真正的高效，恰恰来自正确的约束。
2. 核心公式：代码产出 = AI 能力 × 上下文质量
如果说第 1 节回答了"为什么需要工程化"，这一节要回答的是"工程化的杠杆点在哪里"。
2.1 为什么是乘法，不是加法
代码产出 = AI 能力 × 上下文质量 —— 这个乘号至关重要。
如果公式是加法（AI 能力 + 上下文质量），那么模型足够强的时候，上下文差一点也无妨，大不了靠能力硬补。但乘法的含义截然不同：当上下文质量趋近于零时，模型再强，产出也是零。一个不了解服务拓扑的 AI，即使参数量再大，也会在跨服务需求面前持续犯错；一个不掌握团队规范的 AI，即使推理能力再强，也会产出不符合约束的代码。
这不是理论推演，而是日常现实：模型能力在过去两年快速提升，但 AI 在真实业务仓中的"可用度"并没有同步提升 —— 瓶颈不在模型，而在上下文。
2.2 真实业务仓里的上下文缺口
在真实业务仓里，AI 拿不到的上下文远比想象中多。这些缺口大致可以归为五类：
| 缺口类型 | 典型问题 | AI 的"盲区" |
| 隐性规范 | 团队约定的锁机制、埋点规则、错误码空间 | AI 不知道这些规范存在，更不知道它们的具体约束 |
| 历史决策 | "为什么当时选了 A 方案不选 B" | 训练语料里没有团队内部的决策记录 |
| 服务契约 | IDL 字段的冻结状态、下游是否强依赖 | AI 看到的是文本，不理解哪些字段动不得 |
| 跨服务依赖 | 同一个需求要改哪几个服务、谁调谁 | AI 缺乏全局视角，不知道改动的影响面 |
| 演进轨迹 | 某个模块上次大改的坑、灰度策略 | AI 没有跨会话记忆，无法继承团队的经验教训 |
每一类缺口，都在拉低上下文质量这个乘数因子。而当前行业的主流解法 —— 写更长的 prompt、贴更多的文档 —— 本质上是在用人力填补上下文，成本高、不可持续、无法复用。
2.3 工程化的杠杆点：系统性提升上下文质量
Harness Engineering 的核心思路，是把"补上下文"从一项每次重复的人工操作，变成一项一次投入、持续生效的工程基建：
隐性规范 → 写进 context/team/，所有 AI 会话自动继承
历史决策 → 沉淀到 context/project/{module}/experience/，新人新模型都能读到
服务契约 → 编码进 .service-matrix/dependencies.yaml 和 IDL 门禁，AI 不再"猜"依赖关系
跨服务依赖 → 由服务矩阵自动解析，影响面分析从"搜索"变成"查表"
演进轨迹 → 通过 Self-Refinement 闭环，让每次纠错都沉淀为团队资产
这就是为什么核心公式的乘号如此重要 —— 提升上下文质量，是比提升模型能力更高效的杠杆。因为模型能力的提升依赖外部厂商，而上下文质量的提升，完全掌握在团队自己手中。
3. 什么是 Harness Engineering？
要理解为什么我们的框架叫 Harness Engineering，先看看 "Harness" 这个词在 AI 工程语境中的含义变化。
3.1 为什么是"Harness"？一个词的语义迁移
"Harness" 在英语里本义是马具 / 挽具：把一匹原始力量巨大但方向不定的马，通过缰绳、鞍具、辔头接入可控系统。这个隐喻被 AI 工程社区借用后，恰好概括了当下 LLM 应用的本质矛盾：
┌───────────────────────────┐
│ 原始 LLM = 一匹烈马 │
│ ┌──────────────────────┐ │
│ │ 能力强 ✅ 方向不定 ❌ │ │
│ │ 速度快 ✅ 走不了远路 ❌ │ │
│ │ 理解广 ✅ 没有持久记忆 ❌ │ │
│ └──────────────────────┘ │
└───────────── ─────────────┘
│
▼ 加上 Harness（挽具）
┌───────────────────────────┐
│ Harness = 让烈马能拉动真实生产载荷的一整套 │
│ 挽具、缰绳、辔头、套绳 │
│ ┌──────────────────────┐ │
│ │ 工具编排 / 记忆 / 沙箱 / 校验 / 反馈 │ │
│ │ 上下文工程 / 生命周期 / 人机协同 │ │
│ └──────────────────────┘ │
└───────────────────────────┘
│
▼
**一个能稳定完成复杂任务的 Agent**
3.2 Harness Engineering 的四大标准组件
业界对 Harness Engineering 的共识拆解为四大子系统：
┌─────────────────────────────────────────┐
│ Harness Engineering │
│ │
│ ┌─────────────────┐ ┌────────────────┐ │
│ │ ① 运行时控制系统 │ │ ② 上下文工程 │ │
│ │ │ │ │ │
│ │ 工具编排 │ │ Context Window 优化 │ │
│ │ 状态持久化 │ │ 动态检索 / 摘要 │ │
│ │ 错误恢复 │ │ 防 Context Rot │ │
│ │ 反馈循环 │ │ 信息优先级 │ │
│ └─────────────────┘ └────────────────┘ │
│ │
│ ┌─────────────────┐ ┌────────────────┐ │
│ │ ③ 工具集成与防护 │ │ ④ 生命周期管理 │ │
│ │ │ │ │ │
│ │ API 调用标准化 │ │ 多步长任务 │ │
│ │ 预执行校验 │ │ Checkpoint / Crash Recovery │ │
│ │ 阻止幻觉执行 │ │ Human-in-the-Loop │ │
│ │ 安全护栏 │ │ 跨会话状态 │ │
│ └─────────────────┘ └────────────────┘ │
│ │
└─────────────────────────────────────────┘
3.3 QQ音乐 Harness Engineering
3.3 QQ音乐 Harness Engineering
但真实的企业级研发场景里，一个需求从开始到上线要经历多个 Agent、多个工具、多个服务、多个仓库的协同。这一层业界留白了：
┌───────────────────────────────────┐
│ │
│ ▼ │
│ Harness Engineering 接管的范围 │
│ ┌───────────────────────────┐ │
│ │ Team Agent Governance │ │
│ │ = Multi-Agent × Multi-Service × Multi-Lifecycle │ │
│ │ （让团队的 AI 协作跨会话、跨工具、跨服务可治理） │ │
│ └───────────────────────────┘ │
│ │
└───────────────────────────────────┘
4. QQ音乐 Harness Engineering 框架实现
如果没有真实业务压力，任何工程框架都容易变成“为了框架而框架”。Harness Engineering 不是从抽象方法论开始的，而是从音乐商业化团队每天面对的研发复杂度里长出来的。
我们的业务不是单体应用，也不是一个人维护的小仓库，而是一个典型的单仓多服务与多仓协同场景：业务代码分布在 50+ 微服务中，需求经常横跨多个模块；同时还要处理业务仓、IDL 契约仓和 Harness 规范仓之间的一致性。一个看似简单的需求，背后可能牵动服务调用链、配置、灰度、埋点、错误码、接口契约和历史兼容性。
4.1 真实业务场景：AI 面对的不是“代码”，而是“业务拓扑”
以音乐商业化业务为例，一个需求可能从 TAPD 单开始，经过需求评审、技术方案、服务影响面分析、IDL 契约变更、业务代码实现、测试验证、CR、灰度上线，最后才进入稳定运行。
在这个过程中，AI 需要回答的不是一个简单问题：
“帮我写一个接口。”
而是一组工程问题：
这个接口属于哪个业务域？
需要改哪个服务？是否还有上游调用方和下游依赖方？
是否涉及 IDL？如果涉及，契约仓路径在哪里？字段是否允许修改？
业务仓、IDL 仓、Harness 仓是否在同一个需求分支上？
需求文档、设计文档、任务拆分和代码 diff 能否互相追溯？
这个模块过去有没有踩过类似坑？经验沉淀在哪里？
如果 AI 这次犯错，如何确保下次不再犯同类错误？
这些问题如果靠一次聊天解决，必然会漂移；如果靠人工口头提醒，必然会漏；如果靠模型自己搜索，必然不稳定。因此，我们需要一个框架，把这些问题变成可读取、可校验、可复用的工程结构。
4.2 业务复杂度拆解：四类约束必须进入框架
我们最终把业务复杂度拆成四类约束，并分别落到 Harness Engineering 的具体结构里。
| 业务约束 | 具体问题 | Harness Engineering 的技术落点 |
| 流程约束 | 需求、设计、开发、交付之间容易跳步 | 五阶段主流程 + 四道门禁 + main-process-numbering.md |
| 拓扑约束 | AI 不知道服务之间真实依赖 | .service-matrix/dependencies.yaml + 影响面分析 |
| 契约约束 | IDL 字段兼容性和分支一致性容易被忽略 | 三仓联动 + idl_required + 服务仓库检查门禁 |
| 知识约束 | 团队规范和历史经验不在模型上下文里 | context/team/、context/harness-framework/、context/project/ 三层知识 |
| 演进约束 | AI 错误修完就丢，下次继续犯 | Self-Refinement + experience/*.md 版本化沉淀 |
注意，这里每一类约束都不是“提示词写得更详细”就能解决的。提示词可以提醒模型，但无法保证长期一致；聊天记录可以解释当下任务，但无法成为团队资产；单个工具可以提升效率，但无法替团队定义流程和审计口径。
4.3 为什么一定要自研：通用产品无法替我们定义业务语义
我们并不是因为“不喜欢现成工具”才自研。事实上，Harness Engineering 明确复用 Claude Code、Gemini CLI、Codex CLI、Continue、CodeBuddy 等执行层能力。真正需要自研的是它们上方这层业务语义和工程治理。我们有自己的微服务治理规范，有自己单独的一套CI/CD Devops 流程。调研了司内和业界的一些开源方案，发现适配度成本很高。最终选择复用开源方案的能力，站在巨人的肩膀上，搭建自己的Harness Engineering框架。
通用产品很难替我们定义下面这些内容：
服务矩阵语义
哪些服务属于同一业务域，哪个服务依赖哪个服务，哪个模块需要 IDL，仓库路径如何解析，是否存在多级 repo_path，这些都是业务团队自己的拓扑知识。它们必须由团队维护在 .service-matrix/dependencies.yaml 中，而不能依赖模型临场搜索。
需求生命周期语义
我们的需求不是“一句话任务”，而是有阶段、有门禁、有产物、有追溯关系的生命周期对象。什么时候算完成需求定义？什么时候可以进入开发？设计评审不过能不能继续写代码？这些规则必须写进 context/harness-framework/main-process-numbering.md，并被 Agent Skill Command 共同遵循。
IDL 契约语义
对业务系统来说，IDL 不是普通文本。它代表服务边界、兼容性和上下游契约。通用 AI 工具可以修改 IDL 文件，却不知道哪些字段冻结、哪些变更需要同步业务仓、哪些场景必须先建三仓同名分支。因此我们把 IDL 契约纳入三仓联动和阶段门禁。
团队经验语义
模型知道通用 Go 最佳实践，但不知道某个服务过去因为分页无上限打爆过下游，也不知道某个 goroutine 泄漏问题在本模块出现过两次。团队经验必须写成 AI 可消费的知识文件，进入 context/project/{project}/{module}/experience/。
工具解耦语义
今天团队可能用 Claude Code，明天可能换 Gemini CLI，内部也可能接入 CodeBuddy。我们不希望流程和知识被任何一个运行时锁定，所以把规范保存在 .codebuddy/ 和 context/，再渲染到不同 CLI 的本地目录。
4.4 自研不是重造 IDE，而是补齐 L5 工程治理层
一个容易误解的点是：自研 Harness Engineering 并不意味着我们要重造 Cursor、CodeBuddy 或 Claude Code。我们不做补全，不做编辑器，不做模型网关，不做通用 Agent 运行时。
我们只补齐一层：L5 工程治理层。
┌───────────────────────── ──────┐
│ L5 Harness Engineering：团队拥有的工程治理层 │
│ - 五阶段流程 │
│ - 四道门禁 │
│ - 三层知识体系 │
│ - 服务矩阵 │
│ - Self-Refinement │
│ - 多运行时适配 │
├───────────────── ──────────────┤
│ L3/L4 执行层： │
│ - 代码阅读 │
│ - 文件编辑 │
│ - 命令执行 │
│ - 测试修复 │
├──────────── ───────────────────┤
│ L1/L2 体验层：IDE、补全、对话、diff 可视化 │
└──────────────────── ───────────┘
换句话说，Harness Engineering 的边界非常清晰：不替代执行工具，只定义执行工具必须遵守的工程上下文和协作协议。
4.5 技术路线：把业务约束编码成 AI 可执行的工程制品
从技术实现上看，Harness Engineering 的核心不是某个复杂服务，而是一组被版本化管理的工程制品：
| 工程制品 | 作用 | 为什么重要 |
| AGENTS.md | 全局协作规范和硬规则入口 | 给所有 AI 运行时一个共同的行为基线 |
| .codebuddy/skills/ | 可复用能力单元 | 把复杂任务拆成可委派、可 review 的 Skill |
| .codebuddy/agents/ | 专家角色定义 | 让需求评审、设计评审、追溯检查等角色专业化 |
| .codebuddy/commands/ | 标准化入口 | 把“我想做需求”变成稳定命令，而不是自由聊天 |
| context/team/ | 团队级规范 | Git、日志、错误码、安全等规范 |
| context/harness-framework/ | 框架工程规范 | 定义 Harness 自身流程、门禁、模板和校验规则 |
| context/project/ | 服务级知识 | 每个模块的架构、经验、约束和历史坑 |
| .service-matrix/dependencies.yaml | 服务拓扑与仓库路径 | 让 AI 不再猜服务关系和路径 |
| requirements/ | 需求生命周期产物 | 让需求、设计、任务、门禁和代码形成追溯链 |
| scripts/install.sh | 多运行时渲染 | 让同一份规范适配不同 AI CLI |
这些文件全部在仓库里，意味着它们可以被 code review、可以被 diff、可以被回滚、可以被持续演进。对 AI 来说，它们是上下文；对团队来说，它们是资产；对工程管理来说，它们是审计线索。
4.6 典型链路：一个需求如何被 Harness 接住
以一个跨服务需求为例，Harness Engineering 的运行方式不是“用户随口说一句，AI 直接改代码”，而是逐步收敛上下文：
需求进入：通过 /requirement:new 创建标准目录和需求骨架，需求不再散落在聊天记录里。
需求定义：AI 根据模板补齐背景、目标、非目标、验收标准，并触发需求评审门禁。
影响面分析：从 .service-matrix/dependencies.yaml 读取服务依赖，识别可能涉及的业务仓和 IDL 仓。
设计阶段：生成详细设计，建立“需求条目 → 设计决策 → 开发任务”的追溯关系。
设计门禁：由专门 Agent 检查方案完整性、服务边界、IDL 风险和追溯链质量。
开发准备：检查三仓分支是否一致，确认服务仓库是否就位，避免进入错误分支或错误路径。
编码执行：调用底层 CLI / IDE 的 AI 能力完成代码修改、测试和修复。
交付沉淀：将踩坑经验、规则修正和框架改进写入对应知识目录，进入下一轮复用。
这个链路的关键，是让 AI 每一步都在“被约束的上下文”里工作。它仍然可以很快，但快的方向被限定在正确轨道上。
4.7 用工程视角重新定义“AI 编程效率”
如果只统计“从一句话到生成 diff 的时间”，Superpower 类方案非常强。但在生产环境里，真正的效率不是生成速度，而是端到端交付效率：
需求是否被正确理解；
影响面是否漏掉；
设计是否覆盖关键约束；
代码是否能追溯到需求；
契约变更是否安全；
问题是否能在更便宜的阶段被发现；
经验是否能进入下一次任务。
Harness Engineering 对效率的定义更接近软件工程的总成本：少返工、少漏改、少口径漂移、少重复踩坑、少工具迁移成本。这也是我们选择自研的根本原因：我们不是要让 AI “看起来更聪明”，而是要让 AI 在真实业务系统里“长期更可靠”。
4.8 小结：从业务出发，再回到技术
因此，自研 Harness Engineering 的逻辑链条是：
真实业务复杂度
→ 单个 AI 助手无法稳定覆盖跨服务、跨仓、跨阶段协作
→ 需要把流程、拓扑、契约、知识、经验显式化
→ 显式化后的工程资产必须可版本化、可审计、可迁移
→ 形成 L5 Harness Engineering 治理层
→ 复用 Superpower 类工具作为执行层，而不是被执行层绑定
这条路线看起来比“直接买一个更强的 AI 编程工具”慢，但它解决的是不同层级的问题：Superpower 提升个人战斗力，Harness Engineering 建设团队作战体系。
5. Harness Engineering 总览
5.1 一张图
┌─────────────────────────── ──────────┐
│ Harness Engineering 仓（脑） │
│ │
│ context/ .codebuddy/ requirements/ │
│ ├─ team/ ├─ agents/ (24) └─ {project}/ │
│ ├─ harness-framework ├─ skills/ (34) └─ {req-id}/ │
│ └─ project/ ├─ commands/(35) │
│ └─ hooks/ │
│ │
│ .service-matrix/dependencies.yaml │
│ (xx services, 3 teams, 单一真相源) │
└─────────────────────────── ──────────┘
│
┌───────┼───────┐
▼ ▼ ▼
┌──────┐ ┌──────┐ ┌──────┐
│业务仓 │ │业务仓 │ │ IDL │
│ (手) │ │ (手) │ │ (神经) │
└──────┘ └──────┘ └──────┘
xx+ 微服务，三仓分支联动，一条 TAPD 单 → 三个仓的同名分支
5.2 六句话讲清楚
Harness 仓 = 大脑：只放规范、知识、需求状态、工具链，不放任何业务代码
业务仓 = 手脚：代码和测试，路径由 .service-matrix/dependencies.yaml 的 repo_path 声明
IDL 契约仓 = 神经：跨服务协议（.jce 等），路径由同一个文件的 idl_repo 字段派生
三仓联动：每个需求在三个仓里使用完全相同的分支名feature/{devops-name}/{tapd-id}，这是跨仓协同的基础约束
五阶段 + 四门禁：初始化 → 需求定义⭐ → 设计⭐ → 开发⭐⭐ → 交付
全部可版本化：规范是文件、知识是文件、需求状态也是文件，任何改动都可 diff 可审计 可 rollback
5.3 四个差异化亮点
接下来四节分别展开：
亮点一：五阶段 + 四门禁 —— 流程与质量的"骨架"
亮点二：三层知识体系 + 三仓联动 —— 单仓多服务下的上下文治理
亮点三：Skill Agent Command 三件套 —— 能力原子化与意图委派
亮点四：Self-Refinement —— 让 AI 从错误中沉淀经验
6. 五阶段 + 四门禁 —— 让错误死在最便宜的地方
传统 SDLC 的大阶段，在 AI 协作语境里往往被随意跳过 —— 比如"需求一句话、设计嘴上说、AI 直接上代码"。代价是等到 MR 阶段才发现需求理解错了、接口契约和下游不兼容、数据迁移没想过回滚。
Harness Engineering 把主流程收敛成五阶段 + 四道强制门禁：
┌──────────┐ ┌──────────┐ ┌─────────┐
│ 阶段 1 │ │ 阶段 2 ⭐ │ │ 阶段 3 ⭐ │
│ 初始化 │───▶│ 需求定义 │───▶│ 设计 │
│ │ │ │ │ │
│ 目录骨架 │ │ 撰写 → 评审⭐ │ │ 预研 │
│ │ │ │ │ 设计 │
│ │ │ │ │ 评审+追溯⭐ │
└──────────┘ └───── ─────┘ └─────────┘
│
┌──────────────────────────────────────┘
▼
┌───────────────────────┐ ┌─────────────┐
│ 阶段 4 ⭐⭐ │ │ 阶段 5 │
│ 开发 │─▶│ 交付 │──▶ Done
│ │ │ │
│ 4.1 任务拆分 │ │ 测试验收 │
│ 4.2 Dev 进入门禁 ⭐ │ │ 收尾 │
│ 4.3 服务仓库检查 ⭐ │ │ │
│ 4.4 编码循环 │ │ │
│ 选择→上下文→编码→审查→提交 │ │ │
└───────────────────────┘ └─────────────┘
⭐ = 强制门禁（共 4 个，不可跳过）
核心理念：错误越早被拦住，代价越低。
┌────────────────────────────────┐
│ 错误代价递增曲线 │
│ │
│ 代价 ╱ │
│ ▲ ╱ │
│ │ ╱ │
│ │ ⭐ 需求门禁（2.2） ⭐ 服务门禁 │ │
│ │ │ （4.3） │ │
│ │ │ ⭐ 设计门禁 │ │ │
│ │ │ （3.3） ⭐ Dev │ │ │
│ │ │ │ 门禁（4.2） │ │
│ │ │ │ │ │ ▼ │
│ │ ▼ ▼ ▼ ▼ 代码/IDL 已写 │
│ │ 数据迁移已做 │
│ │ ◎ 改几行 ◎ 改设计 ◎ 改任务 ◎ 重切分支 │
│ │ 文档 文档 拆分 改环境 │
│ │ │
│ └──────────────────────────▶阶段 │
│ 阶段 2 阶段 3 阶段 4.1 阶段 4.3 阶段 4.4 │
│ │
│ ⭐ 正是设在"代价最低的拐点上" │
└────────────────────────────────┘
6.1 门禁总览（单一真相源）
| 门禁 | 位置 | 阻塞条件 |
| 需求评审门禁 | 阶段 2.2 | 需求文档不合格 / 评审未通过 |
| 设计门禁 | 阶段 3.3 | 设计评审未通过 / 追溯链不达标 |
| Dev 进入门禁 | 阶段 4.2 | tasks/features.json 缺失或不合法 |
| 服务仓库检查门禁 | 阶段 4.3 | 三仓分支不一致 / 服务仓库未就位 |
门禁口径收拢在 context/harness-framework/main-process-numbering.md 这一份文档 —— 这是整条流程语义的唯一真相源。AGENTS.md、每一个 Skill、每一个 Command 都围绕它保持一致。这个"真相源"的意义在于：一次更新，全仓生效，避免规范口径散落多处并逐渐漂移。
6.2 为什么门禁要"尽量少、尽量靠前"
门禁是摩擦。加多了，研发绕开；加少了，错误漏出去。我们的平衡点是：
需求评审门禁（2.2）—— 拦住"需求没理解对"
设计门禁（3.3）—— 拦住"方案漏了关键约束 / 没追溯到需求"
Dev 门禁（4.2）—— 拦住"feature 拆分不合规，开发起点不对"
服务仓库检查（4.3）—— 拦住"三仓分支漂移 / IDL 契约仓未就位"
这 4 个点，分别对应"意图、方案、任务、环境"四个最容易出大错、改动代价又最低的节点。一旦过了 4.4 编码循环再回退，代价就从"改几行文档"升到"回滚代码 + 回滚 IDL + 回滚数据迁移"。
6.3 门禁是"机读"的，不是"口头的"
每个门禁都有对应的 Agent / Skill 和 markdown 检查规范，例如：
requirement-quality-reviewer Agent（需求评审门禁）
detail-design-quality-reviewer Agent（设计门禁）
traceability-gate-checker Skill（追溯链校验）
managing-requirement-lifecycle/gates/service-repo-check.md（服务仓库检查门禁）
门禁结论需要写入文件，并采用固定格式，确保可读、可审计。这条规范避免了"AI 口头说通过，但没有任何可追溯记录"的情况。
7. 三层知识体系 + 三仓联动 —— 单仓多服务下的上下文治理
7.1 三层知识架构
| 层级 | 位置 | 范围 | 典型内容 |
| 团队级 | context/team/ | 所有项目必须遵循 | Git 规范、错误码空间、日志规范 |
| 框架工程级 | context/harness-framework/ | 所有需求研发必须遵循 | 五阶段流程、门禁规则、文档模板 |
| 服务级 | context/project/{project-name}/{module-name}/{service-name}/ | 特定服务 | 架构图、API、运维手册、踩坑经验 |
三层知识的可视化：
┌──────────────────────┐
│ 团队级 (最稳定) │
│ context/team/ │
│ ├─ Git 规范 │
│ ├─ 错误码空间 │
│ └─ 日志规范 │
└──────────┬───────────┘
│ 被所有项目继承
▼
┌────────────────────────────┐
│ 框架工程级 (中频更新) │
│ context/harness-framework/ │
│ ├─ 五阶段流程 │
│ ├─ 门禁规则 │
│ ├─ 文档模板 │
│ └─ 上下文收集规范 │
└────────────┬───────────────┘
│ 被所有需求研发继承
▼
┌───────────────────────────────┐
│ 服务级 (高频演进、量最大) │
│ context/project/ │
│ └─ music_commercial_go_proj/ │
│ ├─ vip/ │
│ │ ├─ INDEX.md │
│ │ ├─ architecture.md │
│ │ ├─ sop/ │
│ │ └─ experience/ │
│ ├─ assetcard/ │
│ └─ campaign/ │
└───────────────────────────────┘
AI 按"团队 → 项目 → 模块 → 服务"逐层缩小范围，O(1) 命中
每一层都有 INDEX.md 作为入口，检索成本 O(1)。AI 不需要遍历整个仓库，只需要按 团队 → 项目 → 模块 → 服务 的路径逐层缩小范围。这是"渐进式披露"的物理实现。
7.2 .service-matrix/dependencies.yaml —— 单一真相源
workspace: ".."
business_repo: "music_commercial_go_proj"
idl_repo: "qqmusicjce"
default_team: "music-commercial"
teams:
music-commercial:
business_repo: "music_commercial_go_proj"
idl_repo: "qqmusicjce"
modules:
vip:
team: music-commercial
name: 会员核心域
services:
vipapi:
module: vip
repo_path: "{business-repo}/vipapi"
idl_required: true
assetcardmallcgi:
module: assetcard
repo_path: "{business-repo}/assetcard/mall/assetcardmallcgi"
特点：
路径从不硬编码：用 {business-repo} / {idl-repo} 占位符，跨机器、跨账号无缝迁移
多团队共用同一 Harness 仓：teams: 块让不同业务团队有各自的业务仓 + IDL 仓
Active Team 三级解析：$HARNESS_TEAM > .harness/local.yaml > default_team，既支持会话级临时切换也支持仓库级默认
校验脚本：scripts/validate-service-matrix.js 会在每次 CI 跑过，保证占位符能正确解析、没有幽灵依赖
目前仓内实际管理 57 个服务，路径深度分布非常真实：
整个框架没有对路径深度做出过强假设，一切走 repo_path 真相源 —— 这是在真实业务拓扑里被反复打磨出来的设计。
7.3 三仓联动：同一条 TAPD 单的三个分支
这是 Harness Engineering 很有特色的一个工程实践：每个需求，在三个仓里用完全相同的分支名。
┌──────────────────────────┐
│ 一条 TAPD 单 T12345 │
└─────────────┬────────────┘
│
┌──────────────────┼────────────────────┐
▼ ▼ ▼
┌───────────────┐ ┌─────────────┐ ┌───────── ───┐
│ Harness 仓 │ │ 业务代码仓 │ │ IDL 契约仓 │
│ (脑) │ │ (手脚) │ │ (神经) │
│ │ │ │ │ │
│ feature/Base/ │ │ feature/Base/ │ │ feature/Base/ │
│ T12345 ✓ │ │ T12345 ✓ │ │ T12345 ✓ │
│ │ │ │ │ (仅当涉及 │
│ 需求文档/ │ │ 代码/测试 │ │ IDL 变更) │
│ 设计/门禁/ │ │ │ │ │
│ 知识/状态 │ │ │ │ .jce 契约 │
└───────┬───────┘ └─────┬───────┘ └───────┬─ ───┘
│ │ │
└────────────────┼───────────────────┘
│
┌────────▼──────┐
│ 阶段 4.3 门禁强制校验 │
│ 三仓分支名必须完全一致 │
│ 任何漂移 → 阻塞进入 4.4 │
└───────────────┘
为什么这么做：
一条 TAPD 单 ID → 三仓分支名一对一，追溯链整洁
阶段 4.3 服务仓库检查门禁会自动校验三仓分支一致性，不一致直接阻塞
CR 时可以快速对齐三个仓的改动
回滚时三个仓同步处理，避免出现"代码回了、IDL 没回"的不一致状态
这条基础约束，是所有跨仓协调的锚点。
7.4 占位符词典（唯一真相源）
全仓只允许使用下列占位符：
| 占位符 | 语义 | 举例 |
| {business-repo} | 业务代码仓根的磁盘路径（绝对） | /data/workspace/music_commercial_go_proj |
| {business-repo-name} | 业务代码仓根的目录名 | music_commercial_go_proj |
| {idl-repo} / {idl-repo-name} | IDL 契约仓 | 对称 |
| {project-name} | 逻辑项目名，用于知识库 / 需求目录归属 | music_commercial_go_proj |
| {requirement-id} | 需求 ID | minimal-requirement-practice |
| {module-name} / {service-name} | 业务模块 / 服务 | vip / vipapi |
写路径 vs 写归属两个语境绝不混用。这种"纪律性的枯燥"，换来的是一份可扫描、可 sed、可自动生成的结构化规范。
8. Skill Agent Command 三件套
8.1 三种能力原子的分工
| 类型 | 定位 | 数量 | 调用方式 |
| Skill | 可复用的工作流 规范 最佳实践 | 34 | 主对话按需 load，或被 Agent 调用 |
| Agent | 自主子任务执行者（可调工具、可调 Skill） | 24 | 主对话 Task 委派，或命令触发 |
| Slash Command | 固定入口 + 标准化参数 | 35 | 用户输入 /xxx:yyy |
这三类能力都是版本化 markdown 文件（.codebuddy/skills/*/SKILL.md、.codebuddy/agents/*/*.md、.codebuddy/commands/*/*.md），任何一次修改都能 code review、都能 diff、都能 rollback —— 这就是 Knowledge as Code 的物理实现。
8.2 按阶段组织的 Agent 体系
.codebuddy/agents/
├── Init/ 项目初始化
│ ├── project-bootstrapper
│ └── repo-ops-runner
├── RequirementManagement/ 需求管理
│ └── universal-context-collector
├── Startup/ 阶段 1
│ └── requirement-bootstrapper
├── Definition/ 阶段 2
│ ├── requirement-input-normalizer
│ └── requirement-quality-reviewer
├── TechResearch/ 阶段 3.1
│ └── tech-feasibility-assessor
├── OutlineDesign/ 阶段 3.2
│ └── outline-design-quality-reviewer
├── DetailDesign/ 阶段 3.2
│ └── detail-design-quality-reviewer
├── Implementation/ 阶段 4.4
│ ├── auxiliary-checker
│ ├── code-review-preparer
│ ├── complexity-checker
│ ├── concurrency-checker
│ ├── design-checker
│ ├── error-checker
│ ├── security-checker
│ └── traceability-consistency-checker
├── Acceptance/ 阶段 5
│ └── test-runner
└── KnowledgeMaintenance/ 知识沉淀
亮点：阶段 4.4 的代码审查被拆成 8 个维度的独立 Agent 并行执行：
┌─────────────────────────────┐
│ code-review-preparer Agent │
│ （收集 diff + 上下文） │
└──────────────┬──────────────┘
│ 分发
┌───────┬───────┬──────┼──────┬───────┬────────┬────────┐
▼ ▼ ▼ ▼ ▼ ▼ ▼ ▼
┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐
│设计 │ │复杂 │ │并发 │ │错误 │ │安全 │ │契约 │ │追溯 │ │辅助 │
│一致 │ │度 │ │安全 │ │处理 │ │漏洞 │ │一致 │ │性 │ │检查 │
└──┬──┘ └──┬──┘ └──┬──┘ └──┬──┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘
│ │ │ │ │ │ │ │
└───────┴───────┴───────┼──────┴────────┴────────┴────────┘
│ 聚合
▼
┌─────────────────────────────┐
│ code-review-report Skill │
│ （结论写入 reviews/*.md） │
└─────────────────────────────┘
这是典型的多视角审查，效果远好于单次"AI 通读 + 写意见"。
8.3 Skill 全景
34 个 Skill，按功能归类：
类别 代表 Skill
需求生命周期 managing-requirement-lifecycle、feature-lifecycle-manager、requirement-session-restorer
文档撰写 requirement-doc-writer、outline-design-doc-writer、detail-design-doc-writer
代码审查 code-review-report、traceability-gate-checker、api-contract-consistency-validator
服务治理 service-dependency-analyzer、load-domain、load-service
知识沉淀 managing-knowledge、self-refinement
工程工具 dev-ocs、git-commit-message-generator、devops-cli、gongfeng
规范查询 engineering-spec-query、docs-index-updater、context-index-updater
managing-requirement-lifecycle 是整个框架的"中央调度"。需求工作通过它推进，以保证阶段、门禁和上下文口径一致。它负责：意图识别、阶段检查、门禁验证、债务检查和计划更新。
8.4 Slash Command：标准化入口
/requirement:new # 新建需求
/requirement:continue # 恢复上下文
/requirement:next # 进入下一阶段
/requirement:gate-check # 门禁自检
/req-task:list / start / context / done # 功能点级别的任务流转
/agentic:code-review # 多维度代码审查
/agentic:load-service # 加载服务并生成技术总结
/agentic:note # 记录需求过程信息
/service:deps # 查看依赖
/service:onboard # 零配置接入外部服务
/service:load-domain # 域级跨服务沉淀
/knowledge:extract-experience # 提取经验
/knowledge:generate-sop # 生成 SOP
35 个 Command 构成口径统一的交互表面：同一个命令，对应同一套流程，无论用 Claude Code Gemini CLI Codex CLI / Continue，体验都一致。
9. Self-Refinement —— 让 AI 从错误中沉淀经验
LLM 没有跨会话记忆。但团队的每一个"纠正"，都是一次宝贵的信号。
Harness Engineering 里有一个专门的 Skill 叫 self-refinement，外加 AGENTS.md 的认知模式第 5 条：
当遇到新模式或教训时：主动提议更新到 context/（Self-Refinement）
┌──────────────────────────────┐
│ ① 用户纠正 AI 某个错误 │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ ② AI 识别：这是"模式性教训" │
│ 还是"一次性 diff"？ │
└──────────────┬───────────────┘
│ 模式性
▼
┌──────────────────────────────┐
│ ③ AI 主动提议沉淀层级 │
│ ┌────────── ──────────────┐ │
│ │ 团队级 → context/team/ │ │
│ │ 框架工程级 → harness- │ │
│ │ framework/ │ │
│ │ 服务级 → context/ │ │
│ │ project/{...} │ │
│ └────────────────────────┘ │
└──────────────┬───────────────┘
│ 用户确认
▼
┌──────────────────────────────┐
│ ④ 生成 experience 文档 / │
│ 更新 Skill / 修订规范 │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ ⑤ 下次同类场景，AI 主动引用 │
│ ↓ │
│ 新会话 / 新模型 / 新人也受益 │
└──────────────────────────────┘
📌 错误不再"走一次算一次"，而是成为团队资产
9.2 具体产物示例
context/project/music_commercial_go_proj/campaign/DEPENDENCY_ANALYSIS.md —— 子域依赖影响分析的真实记录
context/project/music_commercial_go_proj/{module}/experience/*.md —— 踩坑经验（分页必须有上限、goroutine 泄漏、🔒字段约束 …）
context/project/{project}/sop/*.md —— 从经验提炼出的标准操作规程
这种"知识驻留在仓库里"的设计，让新人 新模型 新会话都能复用团队的集体经验，而不是从零开始理解业务约束。
9.3 一个微型 meta 案例
写这篇文章的过程本身就是一次 Self-Refinement：
最早的文档里 {project-root}{business-repo}{project-name} 三个占位符分工模糊
有人在 IDE 里选中一行问"这个定义清楚吗？"
于是发起了 MR !49：把占位符词典写进 AGENTS.md 作为唯一真相源，废弃 {project-root} 别名
再后续的 MR（→ 51）修正了 rollback 文档里的路径错误（项目名套两遍、没覆盖子域层）
这些修正本身都是 Self-Refinement 的直接产物
框架自身的演进，就是 Self-Refinement 的活样本。
10. 与 Claude Code Cursor Cline 的关系
简答：Harness Engineering 不是这类工具的替代品，而是它们上层的治理层协议。
我们把 AI 编程工具分成两类能力来看：
| 类型 | 代表 | 角色 |
| Claude Code Cursor Cline Gemini CLI Codex CLI / Continue | 执行层 | 提供 AI 能力、代码理解、文件编辑、命令执行、测试修复 |
| Harness Engineering | 治理层 | 定义流程、门禁、知识体系、服务矩阵、三仓联动和经验沉淀 |
执行层工具越强，越需要治理层把它们接入正确轨道。否则 AI 生成速度越快，错误扩散也越快；工具自主性越强，越需要明确它可以做什么、什么时候做、做到什么程度算通过。
Harness 仓的 .codebuddy/skills/ agents/ commands/ 是真相源；scripts/install.sh 会把它们渲染到各 CLI 的本地目录：
.claude/ ← Claude Code 读这个 .gemini/ ← Gemini CLI 读这个 .codex/ ← Codex CLI 读这个 .continue/ ← Continue 读这个
这些是 gitignored 的镜像目录。修改规范时只改 .codebuddy/，不同 CLI 自动受益。
因此，Harness Engineering 和 Superpower 类工具的关系可以概括为三句话：
执行交给工具：读代码、改代码、跑测试、修复报错，交给更强的 AI IDE / CLI。
规则留在仓库：流程、门禁、服务拓扑、团队知识和经验沉淀，保留为可 review 的工程资产。
协议连接两者：Skill Agent Command 把团队规范翻译成执行层工具可消费的上下文。
一句话：工程规范与 AI 工具解耦。今天用 Claude Code，明天换 Superpower 类新工具，流程和知识都不丢。
结语：工程化不是慢，是稳
回到导语那句话：AI 让写代码变快了，但快不等于对。
Harness Engineering 把 AI 协作从"聊天式"改成"工程化"的方式，不是给研发加负担，而是让 AI 每一次发力都落在正确的位置上：
在最便宜的地方拦住错误 —— 需求和设计门禁
在最重要的地方注入上下文 —— 三层知识体系 + 服务矩阵
在最可复用的地方沉淀经验 —— Knowledge as Code + Self-Refinement
在最容易漂移的地方收敛口径 —— 单一真相源 + 占位符词典
最后一句话
Context Engineering + Spec-First + Knowledge as Code，构成了可验证、可演进的 AI 协作工程基线。
如果你的团队正卡在"AI 写得快但对不对"的纠结里，不妨把 Harness Engineering 当作一面工程镜子 —— 对照看看流程是否完整、门禁是否可机读、知识是否已沉淀、跨服务协调是否已显式化。

54
InBox/zhihu_李开复的提示词_降低AI谄媚幻觉.md
View File

@@ -1,54 +0,0 @@
---
source: 知乎想法
url: https://www.zhihu.com/pin/2051445408837195308
created: 2026-06-20
tags: [zhihu, 转载, AI, prompt-engineering]
author: 独元殇
---
# 李开复的提示词，大幅降低 AI 谄媚与幻觉
> 来源：[知乎想法](https://www.zhihu.com/pin/2051445408837195308) | 作者：独元殇
李开复（零一万物创始人）分享的 system prompt，能有效降低 AI 大模型的谄媚（一味迎合用户）和幻觉（胡说八道）。
建议使用英文原版，中文效果也不错。放到系统提示词中使用。
## 提示词内容
顶级专家。准确性高于迎合。直白，有争辩性。不要免责声明，也不要夸奖。先提出反驳意见。没有新证据，不要让步。
### 论断标签体系
给每一个论断打标签：
| 标签 | 含义 |
|---|---|
| [KNOWN] | 训练资料中的事实 |
| [COMPUTED] | 计算得出 |
| [INFERRED] | 推导得出 |
| [COMMON] | 领域通用知识 |
| [FRAME] | 象征系统，自洽 ≠ 真实 |
| [GUESS] | 没有依据的猜测 |
疾病、法律条文、引用来源、命名实体，不能没有标签。
### 关键规则
- **禁止 FRAME→REALITY**：不要把象征框架（如占星、类型学）翻译成现实世界论断（如医学、法律、金融），除非明确标记这是一次转换；结论必须留在原框架内。
- **置信度等级**：HIGH ≥80% · MED 50–80% · LOW 20–50% · VERY LOW <20% · UNKNOWN。[FRAME] 的现实世界结论和 [GUESS] 最高只能到 LOW。
- **不知道就说不知道**：第一行写 "I don't know." 不要埋在后面，不要编造。
### 反谄媚红旗检测
异常优雅；一个模式解释一切；没有证据却在被反驳后同意；用具体细节制造不该有的权威感。
触发后：删掉具体细节，添加 [GUESS]，或写 "I don't know."
### 事后解释自查
这个框架在不知道结果前，能预测这件事吗？如果不能 → [INFERRED, post-hoc]，它是在容纳结果，不是在预测结果。
永远不要编造引用。如果为了保持前后一致而坚持某个立场，要公开修正。
结尾附上：「[RULES I BROKE]: 哪些规则，在哪里，为什么。」