From ccd777398ae3efc9d9e6534eb33ff1ebb6e242b7 Mon Sep 17 00:00:00 2001 From: Build Bot Date: Thu, 2 Jul 2026 00:39:46 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=E7=AC=94=E8=AE=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../01-scope-and-contract.md | 69 ++ .../02-content-pools.md | 108 +++ .../03-balance-and-validation.md | 81 ++ .../docs/feat-runner-flow-config/README.md | 41 + 1Project/独游-大富翁/遗物.md | 2 - 4Archives/Obsidian记录docs/构建命令.md | 3 + InBox/BV15F7J6dEdm-SSE-AI流式输出笔记.md | 157 ---- InBox/BV1if7E64Ex5-SSE-FastAPI流式响应笔记.md | 117 --- ...V1wPEm6DEzS-ToolUse-FunctionCalling笔记.md | 63 -- InBox/BV1xCKD6qEXW-Ponytail插件笔记.md | 76 -- InBox/milky_milky_2636.md | 12 +- InBox/zhihu_QQ音乐HarnessEngineering实践.md | 785 ------------------ InBox/zhihu_李开复的提示词_降低AI谄媚幻觉.md | 54 -- 13 files changed, 308 insertions(+), 1260 deletions(-) create mode 100644 1Project/Project-Monopoly/docs/feat-runner-flow-config/01-scope-and-contract.md create mode 100644 1Project/Project-Monopoly/docs/feat-runner-flow-config/02-content-pools.md create mode 100644 1Project/Project-Monopoly/docs/feat-runner-flow-config/03-balance-and-validation.md create mode 100644 1Project/Project-Monopoly/docs/feat-runner-flow-config/README.md delete mode 100644 1Project/独游-大富翁/遗物.md create mode 100644 4Archives/Obsidian记录docs/构建命令.md delete mode 100644 InBox/BV15F7J6dEdm-SSE-AI流式输出笔记.md delete mode 100644 InBox/BV1if7E64Ex5-SSE-FastAPI流式响应笔记.md delete mode 100644 InBox/BV1wPEm6DEzS-ToolUse-FunctionCalling笔记.md delete mode 100644 InBox/BV1xCKD6qEXW-Ponytail插件笔记.md delete mode 100644 InBox/zhihu_QQ音乐HarnessEngineering实践.md delete mode 100644 InBox/zhihu_李开复的提示词_降低AI谄媚幻觉.md diff --git a/1Project/Project-Monopoly/docs/feat-runner-flow-config/01-scope-and-contract.md b/1Project/Project-Monopoly/docs/feat-runner-flow-config/01-scope-and-contract.md new file mode 100644 index 0000000..7fb8eb5 --- /dev/null +++ b/1Project/Project-Monopoly/docs/feat-runner-flow-config/01-scope-and-contract.md @@ -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` 已冻结为稳定命名。 +- 后续内容设计都能判断“是否服务于移动收益主循环”。 +- 后续实现不需要再争论这个流派到底是“跑圈”还是“骰面爆发”。 diff --git a/1Project/Project-Monopoly/docs/feat-runner-flow-config/02-content-pools.md b/1Project/Project-Monopoly/docs/feat-runner-flow-config/02-content-pools.md new file mode 100644 index 0000000..5b8e8b4 --- /dev/null +++ b/1Project/Project-Monopoly/docs/feat-runner-flow-config/02-content-pools.md @@ -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`。 +- 已经确定第一版核心遗物的功能槽位。 +- 已经确定奖励轮与商店轮的基本出货结构。 diff --git a/1Project/Project-Monopoly/docs/feat-runner-flow-config/03-balance-and-validation.md b/1Project/Project-Monopoly/docs/feat-runner-flow-config/03-balance-and-validation.md new file mode 100644 index 0000000..ef7b581 --- /dev/null +++ b/1Project/Project-Monopoly/docs/feat-runner-flow-config/03-balance-and-validation.md @@ -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 至少需要表达的关键信息。 +- 已经定义第一版可试玩的最小验证闭环。 diff --git a/1Project/Project-Monopoly/docs/feat-runner-flow-config/README.md b/1Project/Project-Monopoly/docs/feat-runner-flow-config/README.md new file mode 100644 index 0000000..90ee26f --- /dev/null +++ b/1Project/Project-Monopoly/docs/feat-runner-flow-config/README.md @@ -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 提示与最小验证口径。 diff --git a/1Project/独游-大富翁/遗物.md b/1Project/独游-大富翁/遗物.md deleted file mode 100644 index bfd5a8e..0000000 --- a/1Project/独游-大富翁/遗物.md +++ /dev/null @@ -1,2 +0,0 @@ -- 遗物激活飘名 测试 -- 每个遗物效果测试 \ No newline at end of file diff --git a/4Archives/Obsidian记录docs/构建命令.md b/4Archives/Obsidian记录docs/构建命令.md new file mode 100644 index 0000000..31f0f7d --- /dev/null +++ b/4Archives/Obsidian记录docs/构建命令.md @@ -0,0 +1,3 @@ + +Par Vault "Obsidian路径" 先定位ob笔记位置 +Par "项目路径" \ No newline at end of file diff --git a/InBox/BV15F7J6dEdm-SSE-AI流式输出笔记.md b/InBox/BV15F7J6dEdm-SSE-AI流式输出笔记.md deleted file mode 100644 index 4da3ef0..0000000 --- a/InBox/BV15F7J6dEdm-SSE-AI流式输出笔记.md +++ /dev/null @@ -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 diff --git a/InBox/BV1if7E64Ex5-SSE-FastAPI流式响应笔记.md b/InBox/BV1if7E64Ex5-SSE-FastAPI流式响应笔记.md deleted file mode 100644 index 47c7b0f..0000000 --- a/InBox/BV1if7E64Ex5-SSE-FastAPI流式响应笔记.md +++ /dev/null @@ -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 diff --git a/InBox/BV1wPEm6DEzS-ToolUse-FunctionCalling笔记.md b/InBox/BV1wPEm6DEzS-ToolUse-FunctionCalling笔记.md deleted file mode 100644 index b5a8478..0000000 --- a/InBox/BV1wPEm6DEzS-ToolUse-FunctionCalling笔记.md +++ /dev/null @@ -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 diff --git a/InBox/BV1xCKD6qEXW-Ponytail插件笔记.md b/InBox/BV1xCKD6qEXW-Ponytail插件笔记.md deleted file mode 100644 index 803e523..0000000 --- a/InBox/BV1xCKD6qEXW-Ponytail插件笔记.md +++ /dev/null @@ -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 diff --git a/InBox/milky_milky_2636.md b/InBox/milky_milky_2636.md index 6f33ae8..cd07969 100644 --- a/InBox/milky_milky_2636.md +++ b/InBox/milky_milky_2636.md @@ -22,13 +22,13 @@ Josh Pigford 在卖掉 Baremetrics 后，选择以一人公司模式同时开发 一、Josh 的 5 款产品一览 -| 产品名称 | 功能描述 | 状态 | -|---------|---------|------| -| Proxyuser | 合成用户测试工具，用真实浏览器自动 QA 应用，生成屏幕录制帮助快速定位 bug | 刚发布 | -| Rumored | LLM 幻觉检测器，监控 AI 是否错误引用品牌信息（网站文案、博客内容、schema 代码等） | 周五刚发布 | +| 产品名称 | 功能描述 | 状态 | +| ------------ | --------------------------------------------------- | ------- | +| Proxyuser | 合成用户测试工具，用真实浏览器自动 QA 应用，生成屏幕录制帮助快速定位 bug | 刚发布 | +| Rumored | LLM 幻觉检测器，监控 AI 是否错误引用品牌信息（网站文案、博客内容、schema 代码等） | 周五刚发布 | | Reply Social | 社交媒体统一回复管理工具，内置 Bot Block 功能，支持 Facebook、Reddit 等平台 | 早期版本已发布 | -| Chops | 开源 Mac 应用，用于管理和编辑 AI 技能文件 | 已开源 | -| 医疗信息管理工具 | 为母亲（晚期胰腺癌）开发的家庭沟通和文档管理工具，支持与医疗文档对话 | 上个月开发 | +| Chops | 开源 Mac 应用，用于管理和编辑 AI 技能文件 | 已开源 | +| 医疗信息管理工具 | 为母亲（晚期胰腺癌）开发的家庭沟通和文档管理工具，支持与医疗文档对话 | 上个月开发 | 二、三阶段 AI 开发流 diff --git a/InBox/zhihu_QQ音乐HarnessEngineering实践.md b/InBox/zhihu_QQ音乐HarnessEngineering实践.md deleted file mode 100644 index f1396d0..0000000 --- a/InBox/zhihu_QQ音乐HarnessEngineering实践.md +++ /dev/null @@ -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 当作一面工程镜子 —— 对照看看流程是否完整、门禁是否可机读、知识是否已沉淀、跨服务协调是否已显式化。 diff --git a/InBox/zhihu_李开复的提示词_降低AI谄媚幻觉.md b/InBox/zhihu_李开复的提示词_降低AI谄媚幻觉.md deleted file mode 100644 index e75de4b..0000000 --- a/InBox/zhihu_李开复的提示词_降低AI谄媚幻觉.md +++ /dev/null @@ -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]: 哪些规则，在哪里，为什么。」