diff --git a/README.md b/README.md index fbe57c2..795418f 100644 --- a/README.md +++ b/README.md @@ -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) ## 快速开始 diff --git a/skills/SKILL.md b/skills/SKILL.md deleted file mode 100644 index 76dd21b..0000000 --- a/skills/SKILL.md +++ /dev/null @@ -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` 了解之前的编译过程。 diff --git a/skills/wikillm/SKILL.md b/skills/wikillm/SKILL.md new file mode 100644 index 0000000..48aee7d --- /dev/null +++ b/skills/wikillm/SKILL.md @@ -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) diff --git a/skills/wikillm/references/errors.md b/skills/wikillm/references/errors.md new file mode 100644 index 0000000..98889ce --- /dev/null +++ b/skills/wikillm/references/errors.md @@ -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` 了解之前的编译过程 diff --git a/skills/wikillm/references/qa.md b/skills/wikillm/references/qa.md new file mode 100644 index 0000000..bcf3569 --- /dev/null +++ b/skills/wikillm/references/qa.md @@ -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` 中创建入口 diff --git a/skills/wikillm/references/standards.md b/skills/wikillm/references/standards.md new file mode 100644 index 0000000..1a58c1a --- /dev/null +++ b/skills/wikillm/references/standards.md @@ -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 +``` diff --git a/skills/wikillm/references/workflows.md b/skills/wikillm/references/workflows.md new file mode 100644 index 0000000..a2e958b --- /dev/null +++ b/skills/wikillm/references/workflows.md @@ -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)` + +**增量更新**：添加本次新增的来源，保持已有来源不变 + +**分类组织**：按"学术论文"、"概念文章"、"实践指南"等类别合理分组 diff --git a/wiki/INDEX.md b/wiki/INDEX.md index cc7f2b4..bb14d29 100644 --- a/wiki/INDEX.md +++ b/wiki/INDEX.md @@ -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) diff --git a/wiki/assets/HarnessEngineering-kepu.jpeg b/wiki/assets/HarnessEngineering-kepu.jpeg new file mode 100644 index 0000000..87d4323 Binary files /dev/null and b/wiki/assets/HarnessEngineering-kepu.jpeg differ diff --git a/wiki/queries/What-is-Harness-Engineering-in-Simple-Terms.md b/wiki/queries/What-is-Harness-Engineering-in-Simple-Terms.md new file mode 100644 index 0000000..a80d86b --- /dev/null +++ b/wiki/queries/What-is-Harness-Engineering-in-Simple-Terms.md @@ -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|术语表]] - 核心概念定义与对照