mirror of
https://github.com/tradecatlabs/vibe-coding-cn.git
synced 2026-08-16 20:38:04 +00:00
docs: add research domains and resource registry
- add local external resources registry - add research domain contract and per-repository research domains - add raw fact snapshot governance and validation scripts Validation: - make test - git diff --check HEAD~1..HEAD Note: - welcome workflow failed because its action input names are stale; core content CI passed.
This commit is contained in:
tradecatlabs
@@ -0,0 +1,44 @@
|
||||
# docs/research/harness/ Agent 指南
|
||||
|
||||
## 目录职责
|
||||
|
||||
`docs/research/harness/` 是 Harness 研究对象目录，维护 AI 生成系统中的工程控制、评估器、反馈闭环、上下文注入、架构约束和长期治理判断。
|
||||
|
||||
这里的文档回答：
|
||||
|
||||
- Harness 是什么。
|
||||
- Harness 解决 AI 生成系统中的什么可靠性问题。
|
||||
- 哪些机制属于 Harness，哪些只是普通工具调用或脚本封装。
|
||||
- 哪些结论已经可采用，哪些仍处于观察或待验证状态。
|
||||
- 成熟内容应迁移到 concepts、references、workflow 还是 skills。
|
||||
|
||||
## 文件地图
|
||||
|
||||
```text
|
||||
harness/
|
||||
├── README.md # 对象入口：导航、定位和阅读顺序
|
||||
├── harness-engineering.md # 正文：Harness 工程解析
|
||||
└── AGENTS.md # 本目录操作规则
|
||||
```
|
||||
|
||||
## 对象边界
|
||||
|
||||
- 本目录只维护 Harness 作为研究对象的判断、证据、风险和采用建议。
|
||||
- 不承载稳定操作手册；稳定流程迁移到 `docs/workflow/`。
|
||||
- 不承载通用工程模板；稳定模板迁移到 `docs/references/`。
|
||||
- 不承载可执行能力；可复用能力迁移到 `skills/`。
|
||||
- 不把单个工具、单篇文章或单次实验直接包装成稳定结论。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 外部事实优先引用官方文档、原始仓库、论文或可信一手来源。
|
||||
- AI 摘要不能作为事实源，只能作为待核验线索。
|
||||
- 新增结论必须区分：事实、解释、采用判断、风险和待验证项。
|
||||
- 涉及最新模型、工具、仓库状态或产品能力时，必须核验当前来源。
|
||||
|
||||
## 修改规则
|
||||
|
||||
- 新增 Harness 研究正文时，优先放入本目录，而不是散落在 `docs/research/` 根目录。
|
||||
- 新增、删除、移动或重命名本目录文档时，必须同步更新本目录 `README.md`、上级 `docs/research/README.md`、`docs/README.md`、`metadata/taxonomy.yml` 和必要的 `metadata/redirects.yml`。
|
||||
- 面向 AI 引用的重要入口变化，必须同步更新 `llms.txt` 和 `assets/ai-citation/llms-full.txt`。
|
||||
- 修改后运行 `make sync-doc-toc` 和 `make test`。
|
||||
@@ -0,0 +1,35 @@
|
||||
# Harness 研究对象
|
||||
|
||||
## 字多不看
|
||||
|
||||
- 本目录把 Harness 作为独立研究对象维护。
|
||||
- 稳定正文入口是 [Harness 工程解析](harness-engineering.md)。
|
||||
- 研究重点是工程控制、评估器、反馈闭环、上下文注入、架构约束和长期治理。
|
||||
- 成熟结论可晋升到 `docs/concepts/`、`docs/references/`、`docs/workflow/` 或 `skills/`。
|
||||
|
||||
## 快速导航
|
||||
|
||||
| 文档 | 定位 |
|
||||
|:---|:---|
|
||||
| [Harness 工程解析](harness-engineering.md) | 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。 |
|
||||
| [AGENTS](AGENTS.md) | Harness 研究对象目录操作规则。 |
|
||||
|
||||
<details>
|
||||
<summary><strong>完整细粒度目录（点击展开/收起）</strong></summary>
|
||||
|
||||
### 细粒度目录
|
||||
|
||||
- [Harness 工程解析](harness-engineering.md) - 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。
|
||||
- [AGENTS](AGENTS.md) - Harness 研究对象目录操作规则。
|
||||
|
||||
</details>
|
||||
|
||||
## 使用方式
|
||||
|
||||
- 需要理解 Harness Engineering 时，先读 Harness 工程解析。
|
||||
- 需要新增来源、评估框架、工具链样例或采用判断时，先检查 AGENTS 中的对象边界。
|
||||
- 结论稳定后，再迁移到对应的概念、参考、流程或技能文档。
|
||||
|
||||
## 正文
|
||||
|
||||
正文已拆分到上方独立文档；本 README 只保留对象入口、导航和阅读顺序。
|
||||
@@ -0,0 +1,49 @@
|
||||
<a id="research-harness-engineering"></a>
|
||||
|
||||
# Harness 工程解析
|
||||
|
||||
> 工程控制、评估器、反馈闭环与 AI 生成系统可靠性。
|
||||
|
||||
1. Harness Engineering 的本质是用确定性的工程控制系统，把大模型的非确定性输出压缩进可预测的轨道里，让“概率生成”变成“可验收的产出”
|
||||
|
||||
2. 大模型在系统里只承担两件事：理解意图、把意图翻译成文本（代码/配置/文档），它更像算力与语言编译器，而不是可靠性来源
|
||||
|
||||
3. 可靠性不来自“更聪明的模型”，而来自外部机制对输出的四类动作：拦截意图、校验结果、拒绝不合格、注入必要上下文
|
||||
|
||||
4. 最小可运行 Harness 的关键不是生成代码，而是闭环：生成→编译/运行→抓取错误→反馈重写→直到通过，这把一次性聊天改造成可迭代的生产流程
|
||||
|
||||
5. 第一类硬问题是上下文与遗忘：任务一复杂就会撑爆上下文、目标漂移、前后端混写，本质是模型没有稳定的工作记忆与任务边界
|
||||
|
||||
6. 对应解法是动态上下文注入与记忆管理：把规则与知识拆成可插拔技能包，按“当前意图”精准装载与卸载，让上下文保持短、准、相关
|
||||
|
||||
7. 记忆的工程化含义不是“多存点东西”，而是把踩坑与验证过的结论自动提炼成规则沉淀下来，使系统具备跨任务的抗重复犯错能力
|
||||
|
||||
8. 第二类硬问题是自评幻觉：让模型自己审查等于既当运动员又当裁判，它会用讨好与自洽掩盖逻辑错误，漂亮但不可用
|
||||
|
||||
9. 对应解法是评估驱动与机械测试：引入独立的、可执行的第三方判定（编译器、单测、端到端 UI 测试、独立 QA Agent），用硬指标决定通过与否
|
||||
|
||||
10. 质量下限从“模型聪明程度”迁移到“验收机制完备性”，系统真正的生产力来自可重复运行的判定器，而不是一次灵感式输出
|
||||
|
||||
11. 第三类硬问题是时间维度的熵增：长期运行后模型会为了更快过测试而走捷径，架构漂移、耦合蔓延，最终形成不可维护的腐化代码库
|
||||
|
||||
12. 对应解法是架构强约束与持续清理：用静态规则提前阻断跨层依赖等结构性违规，再用专职清理机制持续重构、更新文档、回收技术债，对抗代码腐化
|
||||
|
||||
13. 当系统拥有规划者、执行者、评估者、硬约束钩子、清理机制时，Harness 才从脚本升级为“Agent 操作系统”，长期稳定性来自分工与制衡
|
||||
|
||||
14. 那些看似“AI 自己写出百万行代码”的魔法，核心不在模型，而在工具与 Harness 组合出来的现实校验、反馈重试、规则约束与持续治理
|
||||
|
||||
15. Harness 不是回到古法逐行写代码，而是把工程重心从实现细节迁移到边界、接口、约束、断言与验收标准，编码对象从业务逻辑变成生产流水线
|
||||
|
||||
16. Harness 的门槛高于写业务代码的根因在于：它要求你先把“什么算对、什么算好、什么必须禁止”形式化成可执行规则，否则系统会高速产出结构化垃圾
|
||||
|
||||
17. Harness 的维护成本来自业务变化：当目标函数变了，你必须同步重写评估器与测试桩，否则闭环会失真并进入死锁或错误优化
|
||||
|
||||
18. 最大误解之一是指望模型升级解决跑偏，现实规律是无论马多强，没有缰绳都会把车拉进沟里，可靠性必须由外部约束提供
|
||||
|
||||
19. 最大误解之二是工具越多越好，工具过载会导致选择震荡与时间浪费，工具集应该为评估与执行最小充分，而非堆权限展示强大
|
||||
|
||||
20. 最大误解之三是把无约束的氛围式开发当工业未来，它只能在无历史负担的小项目里成立，一旦进入长周期协作与演进，没有硬边界就必然灾难
|
||||
|
||||
21. Harness 的上限由评估器决定：如果你无法把“好结果”编码为可检验的规则与测试，系统就无法稳定优化，模型也无法替你完成这层战略定义
|
||||
|
||||
22. 未来工程师的分化本质是控制权分配：一类在代码生成速度上竞争，另一类在规则、评估、架构与闭环设计上竞争，后者决定系统长期生产力与可维护性
|
||||
Reference in New Issue
Block a user