jzy/my_wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

重构WikiLLM技能结构并更新内容

Browse Source 
- 将wikillm技能移动到skills/wikillm/目录
- 添加详细的技能参考文档（workflows.md, qa.md, standards.md, errors.md）
- 更新README中的参考资料列表
- 添加Harness Engineering相关的图片和查询
- 更新wiki索引
This commit is contained in:
Junjian Wang
2026-04-13 18:43:50 +08:00
parent 94d4617299
commit a58453865b
10 changed files with 681 additions and 258 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+13 -7
View File
@@ -45,13 +45,19 @@ wikillm/
本 wiki 当前包含关于 **Harness Engineering**的综合知识库，基于以下来源编译：
- OpenAI - Harness Engineering：在智能体优先的世界中利用 Codex
- Anthropic - Harness design for long-running application development
- Martin Fowler - Harness engineering for coding agent users
- LangChain - Improving Deep Agents with harness engineering
- NxCode - Harness Engineering: The Complete Guide
- MiniMax - MiniMax M2.7: Early Echoes of Self-Evolution
- Mitchell Hashimoto - My AI Adoption Journey
- [Externalization in LLM Agents: 智能体记忆/技能/协议/Harness工程统一综述](https://arxiv.org/html/2604.08224v1)
- [Meta-Harness: 模型Harness的端到端优化](https://arxiv.org/html/2603.28052v1)
- [Anthropic: 托管智能体的架构设计：脑手分离](https://www.anthropic.com/engineering/managed-agents)
- [Anthropic: 长生命周期应用的Harness设计](https://www.anthropic.com/engineering/harness-design-long-running-apps)
- [OpenAI: 智能体优先世界中的Codex Harness工程](https://openai.com/zh-Hans-CN/index/harness-engineering/)
- [OpenAI: 英文原版Harness工程指南](https://openai.com/index/harness-engineering/)
- [MiniMax M2.7 模型自我进化发布公告](https://www.minimaxi.com/news/minimax-m27-zh)
- [RedHat: AI辅助开发的结构化Harness工作流](https://developers.redhat.com/articles/2026/04/07/harness-engineering-structured-workflows-ai-assisted-development#the_fix__a_two_phase_workflow)
- [Mitchell Hashimoto (HashiCorp创始人)的AI应用落地历程](https://mitchellh.com/writing/my-ai-adoption-journey)
- [NxCode: Harness工程完整指南 2026](https://www.nxcode.io/resources/news/harness-engineering-complete-guide-ai-agent-codex-2026)
- [LangChain: 基于Harness工程优化深度智能体](https://blog.langchain.com/improving-deep-agents-with-harness-engineering/)
- [Martin Fowler: 编码智能体用户的Harness工程实践](https://martinfowler.com/articles/harness-engineering.html)
- [Martin Fowler: Harness工程早期思考笔记](https://martinfowler.com/articles/exploring-gen-ai/harness-engineering-memo.html)
## 快速开始
skills/SKILL.md
-251
View File
@@ -1,251 +0,0 @@
# 使用 LLM 生成高质量中文 Wiki 知识库
## 1. Skill 概述
本 Skill 旨在利用大模型（LLM）将原始文档和图像（`raw/`）增量“编译”为 **结构化、交叉链接、高质量的中文 Wiki 知识库（`wiki/`）** 的完整思路和方法。
* **核心逻辑**：人工不直接编写 Wiki，仅负责投放素材和发起查询；LLM 负责理解、重写、链接与维护。
* **适配工具**：Obsidian（IDE 前端），通过插件支持更多格式：
- Markdown（文本内容）
- Matplotlib（数据可视化）
- Marp（幻灯片渲染）
- Mermaid（架构图）
---
## 1.5 大文档处理要求
对于篇幅较长的 raw 文档（如学术论文、长篇技术文章），**必须完整阅读和分析**，不得仅基于开头部分生成简短摘要。
### 具体要求：
1. **完整内容获取**：
- 使用 Grep 搜索章节标题（如 `^#{1,3} `）了解文档结构
- 分段读取完整内容，确保覆盖所有主要章节
- 特别关注：摘要、引言、方法、实验、讨论、结论、附录等核心章节
2. **深度分析维度**：
- **核心论点**：提取文章的主要主张和关键发现
- **方法细节**：理解技术方案的实现细节和设计决策
- **实验结果**：完整记录所有实验数据、表格、图表信息
- **案例研究**：保留具体的定性示例和应用场景
- **相关工作**：建立与其他研究的联系和对比
3. **输出内容标准**：
- wiki 页面长度应与原文档的重要性和复杂度相匹配
- 学术论文应包含：摘要、核心方法、完整实验结果、详细讨论
- 技术文章应包含：问题背景、完整解决方案、实际应用案例
- 保留所有定量数据（表格、指标、分数等）
4. **例外情况**：
- 仅在以下情况下可生成较短摘要：
- 文档是纯新闻报道或简短公告
- 文档主要是代码或配置（无大量叙事内容）
- 用户明确要求仅生成摘要
---
## 2. 标准文件系统架构
严格遵循 I/O 分离原则，确保知识库的纯净度与可迁移性：
```text
📁 wikillm
├── 📁 raw/ # 【输入层】原始素材（只读）
│ └── 📁 images/ # 原始图片文件（png, jpg, webp, gif, svg 等）
└── 📁 wiki/ # 【输出层】编译器生成的知识产物
├── 📁 concepts/ # 核心概念、原理分析
├── 📁 practices/ # 部署指南、最佳实践
├── 📁 visual/ # Marp 幻灯片、Matplotlib 趋势图
├── 📁 queries/ # 高价值 Q&A 的沉淀归档
├── 📁 assets/ # 图像和资源文件（从 raw/images/ 同步而来）
├── INDEX.md # 动态索引与学习路径
├── Glossary.md # 统一术语表与双链枢纽
└── sources.md # 来源文档索引（原始 URL 列表）
```
---
## 3. 核心工作流 (The "Compilation" Loop)
### 阶段 0：增量检查 (Incremental Check)
* **任务**：检查 `raw/` 目录下哪些文件需要编译。
* **读取状态**：读取 `wiki/compile-results.tsv`，获取已编译文件的哈希记录。
* **扫描文件**：遍历 `raw/` 目录，计算每个文件的 SHA-256 哈希。
* **识别变更**：对比哈希值，识别：
- **新增文件**：在 `compile-results.tsv` 中不存在的文件
- **修改文件**：哈希值与记录不同的文件
- **未修改文件**：哈希值相同的文件（跳过编译）
* **记录日志**：将检查过程写入 `wiki/compile.log`。
### 阶段 0.5：资源同步 (Asset Sync)
* **任务**：将 `raw/images/` 下的所有图片资源同步到 `wiki/assets/`。
* **同步范围**：所有图像文件，包括但不限于：
- `png`, `jpg`, `jpeg`, `gif`, `webp`, `svg`
* **同步方式**：
- 使用 `cp -r raw/images/* wiki/assets/` 进行完整同步
- `raw/images/` 是权威来源，同名文件直接覆盖
- 保留原始文件名（包括空格和特殊字符）
* **验证**：确保 `wiki/assets/` 包含 `raw/images/` 中的所有文件
* **时机**：每次编译前必须执行此步骤
### 阶段 1：多模态解构 (Ingest & Analyze)
* **任务**：解析 `raw/` 目录下的新增或修改内容。
* **大文档完整阅读**：对于篇幅较长的文档（学术论文、长篇技术文章），必须完整阅读和分析：
- 首先用 Grep 搜索章节标题（如 `^#{1,3} `）了解文档结构
- 分段读取完整内容，确保覆盖所有主要章节
- 特别关注：摘要、引言、方法、实验、讨论、结论、附录等核心章节
* **视觉解析**：对图片进行深度 OCR 与逻辑识别。将架构图转化为文字描述及 **Mermaid** 代码块，存入对应 Wiki 页面。
* **元数据提取**：为每篇文档生成 YAML Frontmatter（包含：`tags`, `source`, `raw_sources`, `confidence_score`, `last_updated`）。
- `raw_sources` 字段：记录源文件路径和哈希值，格式如下：
```yaml
raw_sources:
- path: raw/anthropic-harness-design.md
hash: "sha256:abc123..."
```
### 阶段 2：增量编译 (Incremental Writing)
* **非线性重构**：不进行 1:1 翻译，而是基于源文档的“核心贡献”进行重写。
* **中文化增强**：
* 消除翻译腔：使用行业专业术语（如将 "Agent" 译为 "智能体"）。
* 添加上下文：为中文读者补充必要的背景知识或行业对比。
* **可视化输出**：若涉及多步流程或对比，自动生成 **Marp** 格式的幻灯片文件（`.md`），以便在 Obsidian 中演示。
### 阶段 3：网络化链接 (Wikilinks & Indexing)
* **双链注入**：全文检索 `Glossary.md` 中的术语，使用 `[[术语名]]` 自动包裹。
* **Wikilink 格式规范**：
- 文件名使用 kebab-case（连字符分隔），例如：`Harness-Engineering.md`
- Wikilink 格式为 `[[文件名|显示文本]]`，其中**文件名部分必须与实际文件名完全匹配**（不带 .md 扩展名）
- 正确示例：`[[Harness-Engineering|Harness 工程]]`（对应文件 `Harness-Engineering.md`）
- 错误示例：`[[Harness Engineering|Harness 工程]]`（文件名带空格，不匹配实际文件）
- **文章列表格式**：
- 错误写法（表格无法正确解析双链）：
```
| 文章 | 描述 |
|------|------|
| [[Mitchellh-Adoption-Journey|Mitchellh AI 采用之旅]] | HashiCorp 创始人从怀疑论者到深度用户的六个阶段 |
| [[Building-Your-First-Harness|构建你的第一个 Harness]] | 从个人开发者到工程组织的三级实用框架 |
```
- 正确写法（使用无序列表）：
```
- [[Mitchellh-Adoption-Journey|Mitchellh AI 采用之旅]] - HashiCorp 创始人从怀疑论者到深度用户的六个阶段
- [[Building-Your-First-Harness|构建你的第一个 Harness]] - 从个人开发者到工程组织的三级实用框架
```
* **反向链接**：在文末生成 `## 相关研究` 模块，强制链接到 Wiki 内部至少 2 篇关联文档。
* **动态索引**：根据新增内容，自动更新 `INDEX.md` 中的”最新研究”与”学习路径”部分。
### 阶段 4：健康检查与维护 (Linting)
* **一致性检查**：扫描 `wiki/`，发现术语冲突（如 A 文档叫”智能体”，B 文档叫”代理”）时，自动统一。
* **孤岛扫描**：识别没有任何链接指向的页面，强制将其挂载到导航树中。
* **补丁发布**：当 `raw/` 有新版本（如论文更新）时，在对应 Wiki 页面顶部发布 `[Update Patch]` 摘要。
### 阶段 5：来源索引更新 (Sources Update)
* **任务**：更新 `wiki/sources.md`，记录本次编译涉及的来源文档。
* **格式规范**：使用简单无序列表，每项格式为 `- [标题](URL)`
* **增量更新**：添加本次新增的来源，保持已有来源不变
* **分类组织**：按”学术论文”、”概念文章”、”实践指南”等类别合理分组
---
## 4. 输出质量标准 (The Gold Standard)
### 表达标准
> **原则**：读起来像是由该领域的资深专家直接用中文撰写的。
* **禁止词汇**：产生、输出（作为动词）、这个、那个（指代不明）。
* **提倡词汇**：负责构建、驱动、沉淀、权衡（Trade-off）。
### 技术标准
| 维度 | 要求 |
| :--- | :--- |
| **术语表** | 必须包含 40+ 核心概念，中英对照并带有 Wikilink |
| **链接密度** | 每 500 字需包含至少 3-5 个内部链接 |
| **视觉呈现** | 复杂架构必须有 Mermaid 图，数据趋势必须有 Markdown 表格 |
| **Marp 适配** | 综述类文章必须同步生成一份 `visual/` 下的 Slide 文档 |
---
## 5. Q&A 与知识沉淀 (Filing Back)
**当用户针对 Wiki 发起复杂查询时：**
1. **Agent 模式**：LLM 检索全库文档，进行跨文档推理。
2. **回答格式**：回答不仅要解决当前问题，还需提供“参考文档清单”。
3. **自动归档 (Filing)**：若该次 Q&A 具有通用研究价值，LLM 需自动将其整理为一篇新的文章，存入 `wiki/queries/`，并在 `INDEX.md` 中创建入口。
---
## 6. 执行清单 (Checklist)
* [ ] **Raw Check**: `raw/` 目录中是否包含待处理的新素材（图片/文档）？
* [ ] **Asset Sync**: `raw/images/` 下的所有图片是否已同步到 `wiki/assets/`？
* [ ] **Glossary Lock**: 是否已锁定全局术语表，确保翻译不漂移？
* [ ] **Multimodal Sync**: 图片是否已转化为可编辑的文字解析/Mermaid？
* [ ] **文件名规范**: 所有 wiki 页面文件是否使用 kebab-case（连字符分隔）命名？
* [ ] **Wikilink 格式检查**: 所有 `[[文件名|显示文本]]` 链接中的文件名部分是否与实际文件名完全匹配？
* [ ] **Wikilink Check**: 所有的核心概念是否都已变成 `[[可点击的链接]]`？
* [ ] **Marp Check**: 是否为需要汇报的内容生成了幻灯片格式？
* [ ] **Orphan Check**: 是否存在无法从 `INDEX.md` 触达的”孤儿页面”？
---
## 7. 增量编译工作流
### 编译状态文件
项目使用三个核心文件来追踪编译状态：
1. **`wiki/compile-results.tsv`** - 结构化的编译结果（TSV 格式）
- 字段：`raw_path`、`hash`、`last_modified`、`wiki_paths`、`compile_time`、`status`
- 记录每个 raw 文件的编译状态和生成的 wiki 文档
2. **`wiki/compile.log`** - 详细的编译日志
- 记录每次编译的输入、输出、决策过程
- 用于调试、审查和回溯
3. **`wiki/sources.md`** - 来源文档索引
- 记录所有原始来源的标题和 URL
- 格式：`- [标题](URL)` 的无序列表
- 按"学术论文"、"概念文章"、"实践指南"等分类组织
- 每次增量编译后更新
### Wiki 文档元数据
每个 wiki 文档的 YAML frontmatter 都包含 `raw_sources` 字段：
```yaml
---
title: 文档标题
source: [来源名称]
raw_sources:
- path: raw/source-file.md
hash: “sha256:abc123...”
---
```
### 常用命令
```bash
# 查看所有已编译文件
cat wiki/compile-results.tsv
# 查找特定文件的编译状态
grep “raw/xxx.md” wiki/compile-results.tsv
# 查看最近的编译日志
tail -100 wiki/compile.log
# 查看上次编译摘要
grep “=== 编译完成 ===” -A 5 wiki/compile.log
```
### 增量编译检查清单
* [ ] **扫描检查**：运行扫描，检查 `raw/` 目录中是否有新增或修改的文件
* [ ] **哈希对比**：与 `compile-results.tsv` 中的记录对比，确认变更
* [ ] **日志记录**：将检查过程写入 `compile.log`
* [ ] **只编译变更**：仅处理新增或修改的文件
* [ ] **更新 frontmatter**：确保新编译的 wiki 文档包含 `raw_sources`
* [ ] **更新状态文件**：追加/更新 `compile-results.tsv` 中的记录
* [ ] **更新来源索引**：更新 `sources.md`，添加本次新增的来源
## 8. 最佳实践提示
* **手离开键盘**：不要手动修改 `wiki/` 目录下的内容，所有的修改应通过”向 LLM 发出 Lint 任务”或”添加 raw 素材后重新编译”来完成。
* **搜索即创作**：把每一次对知识库的提问看作是一次”知识合成”，务必将高质量的回答存回库中。
* **结构化思考**：在生成任何长篇文档前，先让 LLM 在内存中构建该主题的”概念地图”。
* **利用编译日志**：遇到问题时，先查看 `wiki/compile.log` 了解之前的编译过程。
skills/wikillm/SKILL.md
+37
View File
@@ -0,0 +1,37 @@
---
name: wikillm
description: Compiles raw documents into a structured, cross-linked Chinese Wiki knowledge base. Use when ingesting raw materials, answering questions about the wiki, or maintaining the wiki structure.
license: MIT
metadata:
version: "2.0"
author: WikiLLM Project
---
# WikiLLM Skill
利用 LLM 将原始文档和图像增量"编译"为结构化、交叉链接、高质量的中文 Wiki 知识库。
## 任务路由（首先阅读本节！）
在执行任何操作前，先判断当前任务属于以下哪个场景：
| 场景 | 判断标准 | 跳转至 |
|------|----------|--------|
| **增量编译** | `raw/` 目录有新增或修改的文件需要编译到 `wiki/` | [references/workflows.md](references/workflows.md) |
| **Q&A** | 用户针对 Wiki 内容提出问题（询问、咨询、探讨） | [references/qa.md](references/qa.md) |
| **Linting** | 需要检查 Wiki 的一致性、修复孤岛页面等 | [references/errors.md](references/errors.md) |
## 快速开始
### 核心逻辑
- 人工不直接编写 Wiki，仅负责投放素材和发起查询
- LLM 负责理解、重写、链接与维护
- 适配工具：Obsidian（IDE 前端）
### 详细文档
- **编译工作流**：见 [references/workflows.md](references/workflows.md)
- **Q&A 流程**：见 [references/qa.md](references/qa.md)
- **质量标准**：见 [references/standards.md](references/standards.md)
- **常见错误**：见 [references/errors.md](references/errors.md)
skills/wikillm/references/errors.md
+57
View File
@@ -0,0 +1,57 @@
# 常见错误与避免方法
## 错误 1：将 Q&A 当作编译任务处理
**表现**：用户提问时，直接去创建 `practices/` 或 `concepts/` 下的文档
**避免**：先看"任务路由"，Q&A 应该归档到 `wiki/queries/`
## 错误 2：忘记添加参考文档清单
**表现**：回答了问题，但没有链接到相关 wiki 页面
**避免**：Q&A 回答模板中必须包含"参考文档"部分
## 错误 3：归档后不更新 INDEX.md
**表现**：创建了 `wiki/queries/` 下的文档，但 INDEX.md 中没有入口
**避免**：使用 Q&A 检查清单，确保步骤 5 完成
## 错误 4：大文档只读取开头部分
**表现**：学术论文或长篇技术文章只基于开头部分生成简短摘要
**避免**：使用"大文档处理要求"的检查清单
## 错误 5：Wikilink 格式错误
**表现**：`[[Harness Engineering|Harness 工程]]` 而不是 `[[Harness-Engineering|Harness 工程]]`
**避免**：参考 Wikilink 格式规范
## 总体执行清单
* [ ] **任务路由确认**：已阅读任务路由，确认当前任务属于正确场景
* [ ] **Raw Check**: `raw/` 目录中是否包含待处理的新素材（图片/文档）？
* [ ] **Asset Sync**: `raw/images/` 下的所有图片是否已同步到 `wiki/assets/`？
* [ ] **Glossary Lock**: 是否已锁定全局术语表，确保翻译不漂移？
* [ ] **Multimodal Sync**: 图片是否已转化为可编辑的文字解析/Mermaid？
* [ ] **文件名规范**: 所有 wiki 页面文件是否使用 kebab-case（连字符分隔）命名？
* [ ] **Wikilink 格式检查**: 所有 `[[文件名|显示文本]]` 链接中的文件名部分是否与实际文件名完全匹配？
* [ ] **Wikilink Check**: 所有的核心概念是否都已变成 `[[可点击的链接]]`？
* [ ] **Marp Check**: 是否为需要汇报的内容生成了幻灯片格式？
* [ ] **Orphan Check**: 是否存在无法从 `INDEX.md` 触达的"孤儿页面"？
## Linting 检查清单
- [ ] **一致性检查**：扫描 `wiki/`，发现术语冲突时自动统一
- [ ] **孤岛扫描**：识别没有任何链接指向的页面，强制挂载到导航树
- [ ] **补丁发布**：当 `raw/` 有新版本时，在对应 Wiki 页面顶部发布摘要
## 最佳实践提示
* **手离开键盘**：不要手动修改 `wiki/` 目录下的内容，所有的修改应通过"向 LLM 发出 Lint 任务"或"添加 raw 素材后重新编译"来完成
* **搜索即创作**：把每一次对知识库的提问看作是一次"知识合成"，务必将高质量的回答存回库中
* **结构化思考**：在生成任何长篇文档前，先让 LLM 在内存中构建该主题的"概念地图"
* **利用编译日志**：遇到问题时，先查看 `wiki/compile.log` 了解之前的编译过程
skills/wikillm/references/qa.md
+46
View File
@@ -0,0 +1,46 @@
# Q&A 与知识沉淀详细指南
## Q&A 执行清单（严格按顺序执行）
- [ ] **步骤 1**：确认当前任务是 Q&A 场景（用户在提问，而非要求编译文档）
- [ ] **步骤 2**：Agent 模式 - 检索全库相关文档，进行跨文档推理
- [ ] **步骤 3**：生成回答，包含：
- 对问题的直接解答
- "参考文档清单"（使用 Wikilink 格式）
- [ ] **步骤 4**：判断是否需要归档：
- 是否具有通用研究价值？
- 是否可能被其他人再次查询？
- 如果是 → 继续步骤 5；如果否 → 结束
- [ ] **步骤 5**：自动归档：
- 将 Q&A 整理为一篇新的 markdown 文章
- 存入 `wiki/queries/` 目录
- 文件名使用 kebab-case，如 `How-to-Do-Something.md`
- 在 `INDEX.md` 的"Q&A 归档"部分创建入口
## Q&A 归档文档的元数据格式
```yaml
---
title: "问题标题（用中文）"
source: "WikiLLM Q&A"
date: YYYY-MM-DD
tags:
- "Q&A"
- "其他标签"
question: |
在这里记录原始问题
---
```
## Q&A 场景的子判断
- **简单查询**：可以直接用现有知识回答，无需创建新文档 → 仅回答，不归档
- **复杂查询**：答案具有通用研究价值，可能被其他人再次查询 → 回答 + 归档到 `wiki/queries/`
## 详细流程
**当用户针对 Wiki 发起复杂查询时**：
1. **Agent 模式**：LLM 检索全库文档，进行跨文档推理
2. **回答格式**：回答不仅要解决当前问题，还需提供"参考文档清单"
3. **自动归档 (Filing)**：若该次 Q&A 具有通用研究价值，LLM 需自动将其整理为一篇新的文章，存入 `wiki/queries/`，并在 `INDEX.md` 中创建入口
skills/wikillm/references/standards.md
+94
View File
@@ -0,0 +1,94 @@
# 输出质量标准与文件结构
## 标准文件系统架构
严格遵循 I/O 分离原则，确保知识库的纯净度与可迁移性：
```text
📁 wikillm
├── 📁 raw/ # 【输入层】原始素材（只读）
│ └── 📁 images/ # 原始图片文件（png, jpg, webp, gif, svg 等）
└── 📁 wiki/ # 【输出层】编译器生成的知识产物
├── 📁 concepts/ # 核心概念、原理分析
├── 📁 practices/ # 部署指南、最佳实践
├── 📁 visual/ # Marp 幻灯片、Matplotlib 趋势图
├── 📁 queries/ # 高价值 Q&A 的沉淀归档
├── 📁 assets/ # 图像和资源文件（从 raw/images/ 同步而来）
├── INDEX.md # 动态索引与学习路径
├── Glossary.md # 统一术语表与双链枢纽
└── sources.md # 来源文档索引（原始 URL 列表）
```
## 表达标准
**原则**：读起来像是由该领域的资深专家直接用中文撰写的。
**禁止词汇**：产生、输出（作为动词）、这个、那个（指代不明）
**提倡词汇**：负责构建、驱动、沉淀、权衡（Trade-off）
## 技术标准
| 维度 | 要求 |
| :--- | :--- |
| **术语表** | 必须包含 40+ 核心概念，中英对照并带有 Wikilink |
| **链接密度** | 每 500 字需包含至少 3-5 个内部链接 |
| **视觉呈现** | 复杂架构必须有 Mermaid 图，数据趋势必须有 Markdown 表格 |
| **Marp 适配** | 综述类文章必须同步生成一份 `visual/` 下的 Slide 文档 |
## 编译状态文件
项目使用三个核心文件来追踪编译状态：
### 1. `wiki/compile-results.tsv`
结构化的编译结果（TSV 格式）
- 字段：`raw_path`、`hash`、`last_modified`、`wiki_paths`、`compile_time`、`status`
- 记录每个 raw 文件的编译状态和生成的 wiki 文档
### 2. `wiki/compile.log`
详细的编译日志
- 记录每次编译的输入、输出、决策过程
- 用于调试、审查和回溯
### 3. `wiki/sources.md`
来源文档索引
- 记录所有原始来源的标题和 URL
- 格式：`- [标题](URL)` 的无序列表
- 按"学术论文"、"概念文章"、"实践指南"等分类组织
- 每次增量编译后更新
## Wiki 文档元数据
每个 wiki 文档的 YAML frontmatter 都包含 `raw_sources` 字段：
```yaml
---
title: 文档标题
source: [来源名称]
raw_sources:
- path: raw/source-file.md
hash: "sha256:abc123..."
---
```
## 常用命令
```bash
# 查看所有已编译文件
cat wiki/compile-results.tsv
# 查找特定文件的编译状态
grep "raw/xxx.md" wiki/compile-results.tsv
# 查看最近的编译日志
tail -100 wiki/compile.log
# 查看上次编译摘要
grep "=== 编译完成 ===" -A 5 wiki/compile.log
```
skills/wikillm/references/workflows.md
+144
View File
@@ -0,0 +1,144 @@
# 编译工作流详细指南
## 增量编译检查清单
- [ ] **扫描检查**：运行扫描，检查 `raw/` 目录中是否有新增或修改的文件
- [ ] **哈希对比**：与 `compile-results.tsv` 中的记录对比，确认变更
- [ ] **日志记录**：将检查过程写入 `compile.log`
- [ ] **只编译变更**：仅处理新增或修改的文件
- [ ] **更新 frontmatter**：确保新编译的 wiki 文档包含 `raw_sources`
- [ ] **更新状态文件**：追加/更新 `compile-results.tsv` 中的记录
- [ ] **更新来源索引**：更新 `sources.md`，添加本次新增的来源
## 阶段 0：增量检查
**任务**：检查 `raw/` 目录下哪些文件需要编译。
**步骤**：
1. 读取 `wiki/compile-results.tsv`，获取已编译文件的哈希记录
2. 遍历 `raw/` 目录，计算每个文件的 SHA-256 哈希
3. 对比哈希值，识别：
- **新增文件**：在 `compile-results.tsv` 中不存在的文件
- **修改文件**：哈希值与记录不同的文件
- **未修改文件**：哈希值相同的文件（跳过编译）
4. 将检查过程写入 `wiki/compile.log`
## 阶段 0.5：资源同步
**任务**：将 `raw/images/` 下的所有图片资源同步到 `wiki/assets/`。
**同步范围**：所有图像文件，包括但不限于：
- `png`, `jpg`, `jpeg`, `gif`, `webp`, `svg`
**同步方式**：
- 使用 `cp -r raw/images/* wiki/assets/` 进行完整同步
- `raw/images/` 是权威来源，同名文件直接覆盖
- 保留原始文件名（包括空格和特殊字符）
**验证**：确保 `wiki/assets/` 包含 `raw/images/` 中的所有文件
**时机**：每次编译前必须执行此步骤
## 阶段 1：多模态解构
**任务**：解析 `raw/` 目录下的新增或修改内容。
### 大文档完整阅读要求
对于篇幅较长的文档（学术论文、长篇技术文章），必须完整阅读和分析：
1. **完整内容获取**：
- 使用 Grep 搜索章节标题（如 `^#{1,3} `）了解文档结构
- 分段读取完整内容，确保覆盖所有主要章节
- 特别关注：摘要、引言、方法、实验、讨论、结论、附录等核心章节
2. **深度分析维度**：
- **核心论点**：提取文章的主要主张和关键发现
- **方法细节**：理解技术方案的实现细节和设计决策
- **实验结果**：完整记录所有实验数据、表格、图表信息
- **案例研究**：保留具体的定性示例和应用场景
- **相关工作**：建立与其他研究的联系和对比
3. **输出内容标准**：
- wiki 页面长度应与原文档的重要性和复杂度相匹配
- 学术论文应包含：摘要、核心方法、完整实验结果、详细讨论
- 技术文章应包含：问题背景、完整解决方案、实际应用案例
- 保留所有定量数据（表格、指标、分数等）
4. **例外情况**：
- 仅在以下情况下可生成较短摘要：
- 文档是纯新闻报道或简短公告
- 文档主要是代码或配置（无大量叙事内容）
- 用户明确要求仅生成摘要
### 视觉解析
对图片进行深度 OCR 与逻辑识别。将架构图转化为文字描述及 **Mermaid** 代码块，存入对应 Wiki 页面。
### 元数据提取
为每篇文档生成 YAML Frontmatter（包含：`tags`, `source`, `raw_sources`, `confidence_score`, `last_updated`）。
`raw_sources` 字段格式：
```yaml
raw_sources:
- path: raw/anthropic-harness-design.md
hash: "sha256:abc123..."
```
## 阶段 2：增量编译
**非线性重构**：不进行 1:1 翻译，而是基于源文档的"核心贡献"进行重写。
**中文化增强**：
- 消除翻译腔：使用行业专业术语（如将 "Agent" 译为 "智能体"）
- 添加上下文：为中文读者补充必要的背景知识或行业对比
**可视化输出**：若涉及多步流程或对比，自动生成 **Marp** 格式的幻灯片文件（`.md`），以便在 Obsidian 中演示。
## 阶段 3：网络化链接
### Wikilink 格式规范
- 文件名使用 kebab-case（连字符分隔），例如：`Harness-Engineering.md`
- Wikilink 格式为 `[[文件名|显示文本]]`，其中**文件名部分必须与实际文件名完全匹配**（不带 .md 扩展名）
**正确示例**：`[[Harness-Engineering|Harness 工程]]`（对应文件 `Harness-Engineering.md`）
**错误示例**：`[[Harness Engineering|Harness 工程]]`（文件名带空格，不匹配实际文件）
### 文章列表格式
**错误写法**（表格无法正确解析双链）：
```
| 文章 | 描述 |
|------|------|
| [[Mitchellh-Adoption-Journey|Mitchellh AI 采用之旅]] | HashiCorp 创始人从怀疑论者到深度用户的六个阶段 |
```
**正确写法**（使用无序列表）：
```
- [[Mitchellh-Adoption-Journey|Mitchellh AI 采用之旅]] - HashiCorp 创始人从怀疑论者到深度用户的六个阶段
```
### 其他链接任务
- **双链注入**：全文检索 `Glossary.md` 中的术语，使用 `[[术语名]]` 自动包裹
- **反向链接**：在文末生成 `## 相关研究` 模块，强制链接到 Wiki 内部至少 2 篇关联文档
- **动态索引**：根据新增内容，自动更新 `INDEX.md` 中的"最新研究"与"学习路径"部分
## 阶段 4：健康检查与维护
- **一致性检查**：扫描 `wiki/`，发现术语冲突（如 A 文档叫"智能体"，B 文档叫"代理"）时，自动统一
- **孤岛扫描**：识别没有任何链接指向的页面，强制将其挂载到导航树中
- **补丁发布**：当 `raw/` 有新版本（如论文更新）时，在对应 Wiki 页面顶部发布 `[Update Patch]` 摘要
## 阶段 5：来源索引更新
**任务**：更新 `wiki/sources.md`，记录本次编译涉及的来源文档。
**格式规范**：使用简单无序列表，每项格式为 `- [标题](URL)`
**增量更新**：添加本次新增的来源，保持已有来源不变
**分类组织**：按"学术论文"、"概念文章"、"实践指南"等类别合理分组
wiki/INDEX.md
+4
View File
@@ -64,6 +64,10 @@ last_updated: 2026-04-11
- Harness 工程的六大分析维度
- 多 Agent 架构实践（Planner-Generator-Evaluator 三 Agent 系统）
## Q&A 归档
- [[What-is-Harness-Engineering-in-Simple-Terms|用通俗易懂的方式理解 Harness 工程]] - 科普风格的 Harness 工程简介
## 相关研究
- 认知人工制品理论 (Norman, 1991)
wiki/assets/HarnessEngineering-kepu.jpeg
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 371 KiB

wiki/queries/What-is-Harness-Engineering-in-Simple-Terms.md
+286
View File
@@ -0,0 +1,286 @@
---
title: "用通俗易懂的方式理解 Harness 工程"
source: "WikiLLM Q&A"
date: 2026-04-12
tags:
- "Q&A"
- "Harness工程"
- "科普"
question: |
请以科普专家的方式简介 Harness 工程
---
# 用通俗易懂的方式理解 Harness 工程
![](../assets/HarnessEngineering-kepu.jpeg)
## Harness 工程：给 AI 智能体一个"可靠的家"
想象一下，你有一个非常聪明但有点冲动的助手——它知识渊博、能说会道，但有时候会：
- 忘记五分钟前你们讨论的事情
- 直接执行危险操作而不问你
- 在复杂任务中迷路，绕来绕去
- 做错了事，但你不知道为什么
这就是没有 Harness 的 LLM 智能体。
## 什么是 Harness？
**Harness** 这个词在英文里有"马具"、"安全带"的意思。在 AI 智能体的世界里，它就是那个让智能体既能够发挥能力，又不会失控的"安全脚手架"。
这个隐喻是有意的：
- **马**是 AI 模型——强大、快速，但它自己不知道去哪里
- **Harness**是基础设施——约束、护栏、反馈循环，以富有成效地引导模型的力量
- **骑手**是人类工程师——提供方向，而不是亲自奔跑
用一个更贴近生活的比喻：**Harness 就像是智能体的"驾驶舱 + 安全带 + 导航系统 + 黑匣子"的组合体**。
根据 [[Harness-Engineering|Harness 工程]] 将原始模型能力转化为可靠 Agent 行为的脚手架。实用的 Agent 最好被理解为在 Harness 内部运行的模型，而不是带有外围能力的模型。
## 真实故事：Harness 工程的威力
在我们深入技术细节之前，让我们看看几个真实的例子，了解为什么 Harness 工程如此重要：
### OpenAI 的 100 万行代码实验
OpenAI 团队做了一件令人震惊的事情：他们用 AI 智能体构建了一个**超过 100 万行代码**的生产应用，而且**零行代码是人工手写的**！
- **5 个月**的开发时间
- **约为人类所需时间的 1/10**
- 产品有**内部日常用户和外部 alpha 测试者**
- 它**交付、部署、崩溃并得到修复**——所有这些都由 Harness 内的智能体完成
工程师的工作不是编写代码，而是**设计 Harness**：指定意图、提供反馈、构建让 AI 可靠编写代码的系统。
### LangChain 的神奇一跃
LangChain 团队证明了一个令人不安的事实：**底层模型的重要性不如其周围的系统。**
他们的编码智能体在 Terminal Bench 2.0 上从 **52.8% 提升到 66.5%**——从**前 30 名跃升至前 5 名**——**只改变了 Harness，模型本身没有任何变化**！
他们做了什么？
- 添加了自我验证循环
- 优化了上下文工程
- 实现了循环检测
- 使用了"推理三明治"策略（规划/验证使用高推理，实现使用中推理）
**相同的模型。不同的 Harness。显著更好的结果。**
### Stripe 的 Minions 大军
Stripe 的内部编码智能体，称为 **Minions**，现在每周产生**超过 1,000 个合并的拉取请求**：
1. 开发者在 Slack 中发布任务
2. Minion 编写代码
3. Minion 通过 CI
4. Minion 打开 PR
5. 人类审查并合并
第 1 步和第 5 步之间没有开发者交互。Harness 处理一切。
## Harness 工程的六大核心维度
让我们用"自动驾驶汽车"来类比，看看 Harness 工程到底做了什么：
### 1️⃣ 智能体循环和控制流 —— "自动驾驶的行车电脑"
就像汽车有油门、刹车、限速器一样，Harness 控制智能体：
- 最多可以走多少步
- 每一步花多少钱
- 什么时候必须停下来
智能体循环是 Harness 的时间骨干，实现感知-检索-计划-行动-观察周期。
### 2️⃣ 沙箱和执行隔离 —— "安全试驾场地"
你不会让新手直接开上高速公路，对吧？Harness 给智能体提供：
- 封闭的测试环境
- 分级的权限控制
- 出了问题可以"回滚"
沙箱的双重作用：
1. 安全围栏 - 限制危险操作
2. 认知边界 - 通过移除不相关状态简化 Agent 的操作环境
### 3️⃣ 人工监督和审批门 —— "副驾驶的刹车"
完全自动驾驶目前还不靠谱，Harness 会在关键时刻让人类介入：
- 执行前："这个操作危险，确认吗？"
- 执行后："我做完了，你检查一下？"
- 异常时："情况不对，你来看看？"
### 4️⃣ 可观测性和结构化反馈 —— "飞机的黑匣子"
如果智能体做错了事，你需要知道为什么。Harness 记录：
- 每一次思考
- 每一个操作
- 每一个结果
可观测性有双重目的：
1. **外部** - 支持调试、合规审计和事件后分析
2. **内部** - 关闭将执行结果连接回产生它们的模块的反馈循环
### 5️⃣ 配置、权限和策略编码 —— "交通规则"
不同的场景有不同的规矩，Harness 会设置：
- 这个智能体能用哪些工具？
- 它能访问哪些文件？
- 什么情况下需要批准？
配置通常分为三层：用户级设置、项目级设置、组织级设置。
### 6️⃣ 上下文预算管理 —— "智能体的记忆力管理"
LLM 的"记忆力"是有限的，Harness 要精打细算：
- 旧的对话压缩成摘要
- 不重要的信息往后放
- 需要时才加载详细指导
上下文窗口仍然是任何 Agent 系统中最稀缺的共享资源。
## Harness 工程的三大支柱
根据 [[Harness-Engineering-Complete-Guide|Harness 工程完整指南]]，OpenAI 的框架将 Harness 工程组织为三个核心类别：
### 支柱 1：上下文工程 —— "智能体需要知道什么？"
上下文工程是关于确保智能体在正确的时间拥有正确的信息。
**静态上下文**：
- 存储库本地文档（架构规范、API 契约、风格指南）
- 编码项目特定规则的 `AGENTS.md` 或 `CLAUDE.md` 文件
- 由 linter 验证的交叉链接设计文档
**动态上下文**：
- 智能体可访问的可观测性数据（日志、指标、追踪）
- 智能体启动时的目录结构映射
- CI/CD 管道状态和测试结果
**关键规则**：从智能体的角度来看，它无法在上下文中访问的任何内容都不存在。Google Docs、Slack 线程或人们头脑中的知识对系统是不可见的。**存储库必须是唯一的真实来源。**
### 支柱 2：架构约束 —— "机械地强制执行好代码的样子"
这是 Harness 工程与传统 AI 提示最显著不同的地方。与其告诉智能体"编写好的代码"，不如**机械地强制执行好代码的样子。**
**依赖分层**：
```
Types → Config → Repo → Service → Runtime → UI
```
每一层只能从其左侧的层导入。这不是建议——它由结构测试和 CI 验证强制执行。
**约束强制执行工具**：
- **确定性 linter**——自动标记违规的自定义规则
- **基于 LLM 的审计器**——审查其他智能体代码的架构合规性的智能体
- **结构测试**——像 ArchUnit，但用于 AI 生成的代码
- **预提交钩子**——任何代码提交前的自动检查
**为什么约束可以改善输出**：矛盾的是，约束解决方案空间使智能体**更有生产力**，而不是更少。当智能体可以生成任何东西时，它会浪费 token 探索死胡同。当 Harness 定义清晰的边界时，智能体会更快地收敛到正确的解决方案。
### 支柱 3：熵管理 —— "定期清理智能体"
这是最被低估的组件。随着时间的推移，AI 生成的代码库会积累熵——文档与现实脱节、命名约定发散、死代码积累。
Harness 工程通过**定期清理智能体**来解决这个问题：
- **文档一致性智能体**——验证文档与当前代码匹配
- **约束违规扫描器**——找到通过早期检查的代码
- **模式强制执行智能体**——识别并修复与既定模式的偏差
- **依赖审计器**——跟踪并解决循环或不必要的依赖
这些智能体按计划运行——每天、每周或由特定事件触发——保持代码库对人类审查者和未来 AI 智能体都健康。
## 前馈指南和反馈传感器：Harness 的双重目标
根据 [[Harness-Engineering-for-Coding-Agent-Users|面向编码智能体用户的 Harness 工程]]，一个构建良好的 Harness 服务于两个目标：
1. **提高智能体第一次就做对的概率**（前馈指南）
2. **提供一个反馈循环，在问题到达人眼之前自我纠正尽可能多的问题**（反馈传感器）
### 计算型 vs 推理型
指南和传感器有两种执行类型：
| 类型 | 描述 | 示例 | 速度 | 可靠性 |
|------|------|------|------|--------|
| **计算型（Computational）** | 确定性且快速，由 CPU 运行 | 测试、lint、类型检查器、结构分析 | 毫秒到秒 | 可靠 |
| **推理型（Inferential）** | 语义分析、AI 代码审查、"LLM 作为法官" | 语义分析、AI 代码审查 | 更慢更昂贵 | 更不确定 |
**前馈指南**在智能体行动之前提供：原则、规则、参考文档、操作指南等，增加智能体第一次就做对的概率。
**反馈传感器**在智能体行动之后提供验证：静态分析、日志、浏览器测试、代码审查智能体等，用于自我纠正问题。
## 构建你的第一个 Harness：从简单开始
你不需要一开始就构建完整的生产级 Harness。根据 [[Harness-Engineering-Complete-Guide|Harness 工程完整指南]]，你可以分三个级别逐步构建：
### 级别 1：基础 Harness（单个开发者）
如果你正在使用 Claude Code、Cursor 或 Codex 进行个人项目：
**需要设置什么**：
- 带有项目约定的 `CLAUDE.md` 或 `.cursorrules` 文件
- 用于 linting 和格式化的预提交钩子
- 智能体可以运行以自我验证的测试套件
- 具有一致命名的清晰目录结构
**设置时间**：1-2 小时 **影响**：防止最常见的智能体错误
### 级别 2：团队 Harness（小团队）
对于 3-10 个共享代码库的开发者团队：
**添加到级别 1**：
- 带有团队范围约定的 `AGENTS.md`
- 由 CI 强制执行的架构约束
- 常见任务的共享提示模板
- 由 linter 验证的文档即代码
- 专门针对智能体生成 PR 的代码审查检查清单
**设置时间**：1-2 天 **影响**：跨团队一致的智能体行为
### 级别 3：生产 Harness（工程组织）
对于运行数十个并发智能体的组织：
**添加到级别 2**：
- 自定义中间件层（循环检测、推理优化）
- 可观测性集成（智能体读取日志和指标）
- 计划运行的熵管理智能体
- Harness 版本控制和 A/B 测试
- 智能体性能监控仪表板
- 智能体卡住时的升级策略
**设置时间**：1-2 周 **影响**：智能体作为自主贡献者运作
## 为什么 Harness 工程很重要？
让我们回到 [[Externalization-in-LLM-Agents|LLM Agent 中的外部化]]理论——从语言、文字、印刷术到计算机，每一次进步都是将认知负担从大脑外部化。
Harness 工程就是在为 AI 做同样的事情：
- 不是让模型变得更"大"，而是让它变得更"稳"
- 不是用更多参数去硬扛，而是用外部结构去辅助
- 不是让智能体"假装"可靠，而是让它在一个设计好的环境中"真的"可靠
## 核心洞见
**实用的智能体 = 模型 + Harness**
这就像说：
- 实用的汽车 = 发动机 + 整车（刹车、方向盘、仪表盘...）
- 实用的飞机 = 引擎 + 机身（控制系统、起落架、黑匣子...）
发动机很重要，但没有整车，它只是一个会转的铁块。
同样，LLM 很重要，但没有 Harness，它只是一个会说话的模型。
如果说 2025 年是 AI 智能体证明它们可以编写代码的一年，那么 2026 年就是我们认识到**智能体不是难点——Harness 才是**的一年。
## 参考文档
- [[Harness-Engineering|Harness 工程]] - 核心概念与六大分析维度
- [[Externalization-in-LLM-Agents|LLM Agent 中的外部化]] - 外部化作为组织原则
- [[Harness-Engineering-Complete-Guide|Harness 工程完整指南]] - NxCode 的完整 Harness 工程指南
- [[Harness-Engineering-for-Coding-Agent-Users|面向编码智能体用户的 Harness 工程]] - Martin Fowler 的指南与传感器框架
- [[OpenAI-Codex-Harness-Engineering|OpenAI Codex Harness 工程]] - 完全由智能体生成代码的产品开发实践
- [[LangChain-Harness-Engineering|LangChain Harness 工程实践]] - 从 Top 30 到 Top 5 的 Harness 优化经验
- [[Long-Running-Harness-Design|长运行应用的 Harness 设计]] - Anthropic 团队的多 Agent 架构实践
- [[Glossary|术语表]] - 核心概念定义与对照