用 Deep Agents 与 LangSmith Hub 构建持久化 LLM Wikiinit / ingest / query / lint 全流程实战【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents本篇指南基于deepagents仓库中的 script-first 示例 examples/llm-wiki讲解如何让一个研究型 Agent 在 LangSmith Sandbox 中持续维护一个可复用的主题 Wiki并借助langsmith hub命令把每个阶段的成果作为 Context Hub 版本同步给团队。读完你将掌握四个 CLI 模式init、ingest、query、lint的完整用法、wiki/与log.md的持久化结构以及 Agent 文件系统权限、沙箱快照等底层实现细节。项目定位为什么需要一个会自维护的 Wikiexamples/llm-wiki是 Deep Agents 生态中的一个脚本优先script-first示例它把研究一个主题 → 沉淀为可复用知识这条流水线交给 Agent 自动执行而不是每次从头开始。其核心工作方式在 README 中描述如下该示例实现了一个工作流Agent 研究一个主题并把结果写入一个 Context Hub 条目。Agent 被给定源材料与问题然后收集信息、组织信息并增量构建一个未来 Agent 可以参考的、可复用的 Wiki。随着时间的推移Wiki 通过 ingest、query 和 lint 三轮流水线持续演化而不是在每次运行时从零重建。换句话说这个示例回答了一个工程问题如何让 LLM 的输出具备积累性。ingest吸收、query检索问答和lint健康检查都运行在由create_deep_agent创建的 Deep Agent 上执行环境是 LangSmith Sandboxquery阶段先读取当前 Wiki 状态针对相关页面做推理产出有依据的答案当答案具有长期复用价值时Agent 会把结果固化回wiki/query/目录每次运行结束后所有变更都会通过hub命令推送到 Context Hub团队成员可以审阅、评论并提升版本。工程结构一个模式一个模块整个示例的文件组织非常脚本优先README 中的 Structure 一节给出了每个文件的职责文件职责runner.py薄薄的 CLI 入口负责解析参数、捕获WikiError、打印答案与 Hub 链接helpers.py共享助手CLI 解析、模式编排、langsmithCLI 包装、沙箱后端创建、安全文件写入index.pywiki/index.md内容目录生成器与页面分类逻辑log.pylog.md追加式时间线的格式器与写入器models.py共享配置 / 依赖 / 结果数据类RunnerConfig、CliDeps、RunResultinit.pyinit模式工作流与 internal source 强制校验ingest.pyingest模式的源文件展开 审阅/应用流程query.pyquery模式的分析 可选固化流程lint.pylint模式的健康检查与对账流程pyproject.toml示例自身的依赖配置deepagents与langsmith[sandbox]tests/unit_tests/test_helpers.py针对参数解析、Hub 命令兼容性、内部源校验、三阶段工作流的单元测试从 models.py 的Mode Literal[init, ingest, query, lint]可以看出四种模式共用同一个RunnerConfigCliDeps则把所有副作用run_langsmith_cli、run_agent_mode、run_agent_review_mode、ask_user、tempdir_factory抽象为可注入依赖这也是测试能够用假实现替换真实调用的关键设计见 test_helpers.py 中的_make_deps。工作区布局Wiki 的物理形态init模式会在本地生成如下顶层布局这也是 Context Hub 仓库中的目录规范AGENTS.md—— Wiki 的 schema/配置与工作流规则Agent 在 ingest/query/lint 时遵循它。init在缺失时创建重复运行时保留既有编辑对应_write_if_missing的仅缺失时写入语义见 helpers.py。默认内容由_agents_md()生成强调/raw/只读、/log.md追加式、/wiki/index.md是权威导航等规则。raw/—— 不可变的源文件文章、笔记、数据集由 ingest 阶段放入Agent 被系统提示与文件权限双重约束为只读。wiki/—— LLM 维护的知识页面实体、概念、摘要、综合。默认偏好扁平结构仅当目录确实能改善组织时才允许子目录该规则同时写进了AGENTS.md模板与 ingest 提示词。wiki/index.md—— 面向内容的目录页为 Wiki 导航与检索服务分好类的页面链接 一行摘要 可选元数据如日期/源数量。query 流程首先读取它。log.md—— 追加式的按时间顺序交互日志。每次 ingest/query/lint 阶段都会追加一个可解析的标题## [YYYY-MM-DD] mode.phase | outcome...配以时间戳与摘要条目。index.py 展示了 index 的分类逻辑_INDEX_CATEGORY_ORDER固定为 Entities、Concepts、Sources、Timelines、Queries、Syntheses、Other Pages 七类按目录名自动归类entity/、concept/、query/等子目录分别映射到对应分类每个条目从页面内容提取标题首个#标题、一行摘要首个非标题非代码块的正文行超过 150 字符截断与元数据页面中出现的最后日期、/raw/源引用计数。环境要求与安装README 列出的硬性要求如下Python 3.11与 pyproject.toml 中requires-python 3.11一致langsmith[sandbox]且提供可用的hub命令uv sync时随示例环境一起安装LANGSMITH_API_KEYingest、query、lint三个模式必须设置因为 Agent 运行在langsmith.sandbox中init模式不需要。依赖版本声明位于 pyproject.toml[project] name llm-wiki-example version 0.1.0 description LLM wiki using Deep Agents LangSmith CLI requires-python 3.11 dependencies [ deepagents0.6.12, langsmith[sandbox]0.9.3, ] [tool.uv.sources] deepagents { path ../../libs/deepagents, editable true }注意最后一段deepagents以 editable 方式指向仓库内的 libs/deepagents因此示例始终使用当前仓库源码而不是 PyPI 上的发布版本。安装与预检命令在 deepagents 仓库根目录执行# 1. 安装示例依赖创建 examples/llm-wiki 的独立虚拟环境 uv sync --project examples/llm-wiki # 2. 验证示例环境中可用的 Hub 命令 uv run --project examples/llm-wiki langsmith hub --help # 3. 验证沙箱模式所需的认证环境变量输出 set 即已配置 echo ${LANGSMITH_API_KEY:set}从源码看预检背后有两道防线helpers.py_resolve_langsmith_binary()在PATH上查找langsmith二进制找不到直接抛WikiError并提示先安装_ensure_hub_command_support()运行langsmith hub --help若退出码非 0 则判定该 CLI 不支持hub子命令并给出可操作报错测试用例test_ensure_hub_command_support_raises_for_incompatible_cli验证了这一点。CLI 使用全解四个模式一条命令runner.py是唯一入口所有模式统一通过--mode选择。README 给出了完整示例# 1. 初始化 Wiki 并发布首个 Context Hub 版本 uv run --project examples/llm-wiki \ python examples/llm-wiki/runner.py \ --mode init \ --repo ada-lovelace-wiki # 2. 把源笔记吸收为规范的 Wiki 页面同时支持单文件与文件夹 uv run --project examples/llm-wiki \ python examples/llm-wiki/runner.py \ --mode ingest \ --repo ada-lovelace-wiki \ --source ./notes/ada.md \ --source ./notes/speeches/ # 3. 基于维护中的 Wiki 提出有依据的问题 uv run --project examples/llm-wiki \ python examples/llm-wiki/runner.py \ --mode query \ --repo ada-lovelace-wiki \ --question What did Ada contribute to computing? # 4. 执行一次 Wiki 维护并发布更新的 Context Hub 版本 # 修复链接、去重页面、刷新 index.md、追加 log.md 条目 uv run --project examples/llm-wiki \ python examples/llm-wiki/runner.py \ --mode lint \ --repo ada-lovelace-wiki可选参数一览参数适用模式说明--owner acme全部当仓库位于显式 owner 下时指定也支持把--repo写成owner/repo形式两者同时提供时必须以--repo中的 owner 为准冲突会直接报错--review仅 ingest开启审阅后应用的两阶段操作者介入流程--description ...仅 init设置 Hub 仓库描述仅当 CLI 支持对应 flag 时生效--source path仅 ingest可重复传入文件或目录皆可目录会被递归展开--question ...仅 query要回答的问题必填--note ...ingest / lint注入到提示词中的附加操作者说明--model ...全部覆盖create_deep_agent使用的模型--topic-dir path仅 init指定本地 Wiki 目录默认是./wikis/topic-slugtopic 由 repo 名自动派生例如ada-lovelace-wiki→Ada Lovelace Wiki参数校验规则在parse_config()helpers.py中强制ingest模式必须有--sourcequery模式必须有--question--repo不能为空、至多包含一个/段。runner.py的main()把所有异常收敛为一行error: ...并以退出码 1 返回。init的隐藏逻辑internal source 强制校验README 特别强调init会自动从hub init --help输出中探测可用的 internal-source 参数--repo-source internal、--source internal或--internal按优先级取第一个匹配见 init.py 的_resolve_internal_source_flag_from_help在首次 push 之前还会通过/api/v1/repos预创建/校验仓库并设置sourceinternal。如果已有仓库不是 internal 源init会快速失败并给出可操作的错误信息。实现上ensure_internal_repo_default()先对/api/v1/repos/{owner}/{repo}发 GET 请求404 时用 POST/api/v1/repos创建repo_typeagent、is_publicfalse、sourceinternal存在时则解析source/repo_source/嵌套repo.source元数据非internal一律拒绝。verify_internal_repo_source()在 push 后再次通过hub get --format json复核必要时回退到 repos API。这解释了为什么测试test_run_init_creates_internal_repo_when_missing会断言 POST body 中同时包含source: internal。Ingest 工作流从原始素材到规范页面默认情况下ingest直接应用README 原文ingest applies directly by default。它的实际执行路径是expand_sources()ingest.py把--source参数展开为确定的文件列表文件直接收下目录递归收集符号链接一律拒绝空目录报错_stage_sources()helpers.py把源文件去重、拷贝进工作区的raw/同名文件自动改名为name-2.md之类避免覆盖并对每个文件做后缀白名单.md、.txt、.json、.yaml、.yml、.csv与 UTF-8 可解码校验Agent 读取/raw/中的素材把非结构化的笔记收敛为规范的概念/实体/主题页面并整合跨源综合结论而非逐源摘要runner 刷新wiki/index.md并在log.md追加ingest.apply | outcomeapplied条目。--review操作者介入的两阶段流程传入--review后ingest 变为两阶段Review 阶段只读模型读取暂存的源文件返回关键要点、建议的 Wiki 更新、矛盾点与 index 更新方案build_ingest_review_prompt强制输出六个章节逐源提取、提议的 Wiki 变更集、跨源综合、矛盾与未决声明、index 更新与 recency 说明、缺口与后续问题Apply 阶段写入你确认后模型把规范的概念/实体/主题更新写入页面并把证据直接整合进页面runner 刷新wiki/index.md追加结构化的ingest.review/ingest.apply时间线条目拒绝确认时跳过 Wiki 编辑但仍追加ingest.apply | outcomecanceled条目并照常 push保证时间线完整测试test_run_ingest_workspace_cancelled_skips_apply断言了calls [review]且 log 中同时出现outcomecompleted与outcomecanceled。此外ingest默认支持批量一次运行可以同时处理多个文件和目录README 原文 Batch ingest is the default. A single run can process multiple files and directories.。Query 工作流检索、作答、按需固化query自动运行两个阶段分析阶段只读模型按固定顺序检索——先读/wiki/index.md其分类摘要与元数据用于选择候选页面再读最近约 10 条log.md标题以获取 recency 上下文然后优先检查既往wiki/query/*.md页面做发现/路由据此定位规范页面展开后给出带引用的答案并判断结果是否值得固化。README 明确了两类证据的等级query 页面只是路由提示routing hints不是主要证据log.md只是操作上下文不是事实依据。最终答案要求以ANSWER:、FILING_DECISION: file|skip、FILING_REASON:三个精确键输出。固化阶段写入条件性若答案具有持久复用价值should_file truerunner 把它写入wiki/query/question-slug.mdslug 由问题文本截取前 80 字符生成见query_slug()并刷新wiki/index.md。固化页面必须包含Question、Answer、Sources三个章节。runner 总会把query.reviewoutcomefile或outcomeskip和可选的query.applyoutcomefiled追加到log.md并 push——即便决策是 skip查询历史也会保留测试test_run_query_workspace_skip_keeps_query_read_only验证了 skip 时不运行写阶段、不产生query.apply条目。parse_query_decision()query.py用正则解析决策标记标记缺失时安全默认skip避免破坏性写入。Lint 工作流单趟对账lint是单趟single-pass并立即应用健康检查阶段写入模型先读最近约 10 条log.md标题获取 recency 上下文然后直接在/wiki/中就地修正调和跨页矛盾未决时保留显式不确定性、更新被新证据取代的过时声明、检测无入链的孤儿页面并修复/合并、补齐相关页面之间的交叉引用、为缺失的重要概念创建规范页面并加链、识别数据缺口。build_lint_promptlint.py特别指出不得单独创建 lint 报告目录若模型运行时没有可用的网络检索能力就不得编造结论而应把缺口标记为未决并列出待核实项。缺口报告阶段仅响应模型返回一份简洁摘要包含已对账变更、剩余缺口、建议的后续问题与来源固定三个章节## Reconciled Changes、## Remaining Gaps、## Suggested Next Questions and Sources。runner 刷新wiki/index.md追加lint.apply | outcomeapplied条目并 push。Log 时间线可被 shell 工具解析的审计日志log.md由 runner 管理、只追加且刻意设计成可用简单 shell 工具解析。关键约定README log.pyAgent 不得直接编辑log.md条目由 runner 追加每次交互都会记录ingest.review开启--review时、ingest.applyoutcomeapplied或outcomecanceled、query.reviewoutcomefile或outcomeskip、query.apply仅固化时outcomefiled、lint.applyoutcomeapplied条目形态标题## [YYYY-MM-DD] mode.phase | outcome... keyvalue ...header 最多 220 字符metadata 按键排序含空格的取值用双引号包裹正文timestampUTC格式YYYY-MM-DDTHH:MM:SSZ与summary最多 320 字符两条 bullet# 查看最近 5 条时间线条目 grep ^## \\[ log.md | tail -5 # 查看最近 10 条 query review 的 outcome grep ^## \\[.*\\] query.review \\| log.md | tail -10单元测试test_append_log_entry_normalizes_and_truncates_fields验证了标题保持单行、多行内容被归一化、特殊字符被引号包裹等行为——这正是grep 友好的保证。底层实现沙箱、路由与文件权限所有 Agent 模式ingest/query/lint都在 LangSmith Sandbox 中执行helpers.py 的_create_langsmith_sandbox_backend检查LANGSMITH_API_KEY并惰性导入langsmith.sandbox.SandboxClient缺失时报错提示pip install langsmith[sandbox]从环境变量解析快照与镜像配置全部有默认值环境变量默认值作用WIKI_SANDBOX_SNAPSHOTdeepagents-wiki沙箱快照名称WIKI_SANDBOX_IMAGEpython:3快照的 Docker 镜像WIKI_SANDBOX_FS_CAPACITY_BYTES1717986918416 GiB快照文件系统容量上限快照不存在或未ready时自动创建随后创建沙箱用yield注入LangSmithSandbox后端结束时在finally中删除沙箱Agent 由create_deep_agent(model, backend, permissions, system_prompt)构建其中backend是CompositeBackend默认走沙箱而/raw/、/wiki/、/log.md、/AGENTS.md四个路由转发到本地工作区的FilesystemBackendvirtual_modeTrue。_BASE_SYSTEM_PROMPT定义了 Agent 的长期行为准则把/raw/视为不可变证据、优先按结构压缩而非按删减压缩、保持不确定性显式、维护规范页面而非碎片化页面、让/wiki/index.md保持权威。文件系统策略则由FilesystemPermission硬性约束_permissions()FilesystemPermission(operations[write], paths[/raw/**], modedeny), FilesystemPermission(operations[write], paths[/AGENTS.md], modedeny), FilesystemPermission(operations[write], paths[/wiki/**], modeallow), FilesystemPermission(operations[write], paths[/log.md], modedeny),即Agent 只能写/wiki/**raw/、AGENTS.md、log.md一律只读而_review_permissions()把所有路径都设为 deny把审阅阶段严格锁定为只读。这一权限兜底 提示词约束的双层设计是防止 Agent 越权修改不可变素材或审计日志的关键。此外还有一层文件系统安全整个工作区禁止符号链接_ensure_no_symlinks所有写入走_safe_write_text用O_NOFOLLOW拒绝符号链接目标防止把内容写到工作区之外push 前执行_validate_text_only_directory仅允许五种文本后缀且必须 UTF-8 可解码否则报错 Binary uploads are not supported in v1。这些细节在测试中被逐一验证例如test_ensure_no_symlinks_rejects_workspace_symlink与test_stage_sources_avoids_symlink_destination。一次完整的运行闭环把四个模式串起来一个典型的维护周期是init创建本地工作区骨架raw/、wiki/、wiki/index.md、log.md、AGENTS.md在 Context Hub 预创建/校验 internal 仓库hub inithub push发布首个版本ingest建议配合--review把--source指定的素材展开、暂存进raw/审阅后让 Agent 将证据整合为规范页面runner 刷新 index、追加日志并 pushquery随时基于当前 Wiki 提问得到带页面引用的答案高复用价值的问答被固化到wiki/query/并进入 indexlint定期单趟对账修正矛盾、过时声明、孤儿页面与缺失交叉引用产出缺口报告并 push。整个过程中log.md作为追加式审计线索贯穿始终wiki/index.md作为内容目录持续保持最新而 Context Hub 承担版本化与协作职责——这正是团队可以审阅变更、评论并提升版本这一设计目标的落点。仓库还提供了完整的单元测试套件examples/llm-wiki/tests/unit_tests/test_helpers.py覆盖 CLI 解析、Hub 兼容性、internal source 校验、ingest 审阅/取消/直落、query 固化/skip、lint 单趟等 40 场景可以作为你改造或扩展该示例时的行为基线。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 Deep Agents 与 LangSmith Hub 构建持久化 LLM Wiki：init / ingest / query / lint 全流程实战
用 Deep Agents 与 LangSmith Hub 构建持久化 LLM Wikiinit / ingest / query / lint 全流程实战【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents本篇指南基于deepagents仓库中的 script-first 示例 examples/llm-wiki讲解如何让一个研究型 Agent 在 LangSmith Sandbox 中持续维护一个可复用的主题 Wiki并借助langsmith hub命令把每个阶段的成果作为 Context Hub 版本同步给团队。读完你将掌握四个 CLI 模式init、ingest、query、lint的完整用法、wiki/与log.md的持久化结构以及 Agent 文件系统权限、沙箱快照等底层实现细节。项目定位为什么需要一个会自维护的 Wikiexamples/llm-wiki是 Deep Agents 生态中的一个脚本优先script-first示例它把研究一个主题 → 沉淀为可复用知识这条流水线交给 Agent 自动执行而不是每次从头开始。其核心工作方式在 README 中描述如下该示例实现了一个工作流Agent 研究一个主题并把结果写入一个 Context Hub 条目。Agent 被给定源材料与问题然后收集信息、组织信息并增量构建一个未来 Agent 可以参考的、可复用的 Wiki。随着时间的推移Wiki 通过 ingest、query 和 lint 三轮流水线持续演化而不是在每次运行时从零重建。换句话说这个示例回答了一个工程问题如何让 LLM 的输出具备积累性。ingest吸收、query检索问答和lint健康检查都运行在由create_deep_agent创建的 Deep Agent 上执行环境是 LangSmith Sandboxquery阶段先读取当前 Wiki 状态针对相关页面做推理产出有依据的答案当答案具有长期复用价值时Agent 会把结果固化回wiki/query/目录每次运行结束后所有变更都会通过hub命令推送到 Context Hub团队成员可以审阅、评论并提升版本。工程结构一个模式一个模块整个示例的文件组织非常脚本优先README 中的 Structure 一节给出了每个文件的职责文件职责runner.py薄薄的 CLI 入口负责解析参数、捕获WikiError、打印答案与 Hub 链接helpers.py共享助手CLI 解析、模式编排、langsmithCLI 包装、沙箱后端创建、安全文件写入index.pywiki/index.md内容目录生成器与页面分类逻辑log.pylog.md追加式时间线的格式器与写入器models.py共享配置 / 依赖 / 结果数据类RunnerConfig、CliDeps、RunResultinit.pyinit模式工作流与 internal source 强制校验ingest.pyingest模式的源文件展开 审阅/应用流程query.pyquery模式的分析 可选固化流程lint.pylint模式的健康检查与对账流程pyproject.toml示例自身的依赖配置deepagents与langsmith[sandbox]tests/unit_tests/test_helpers.py针对参数解析、Hub 命令兼容性、内部源校验、三阶段工作流的单元测试从 models.py 的Mode Literal[init, ingest, query, lint]可以看出四种模式共用同一个RunnerConfigCliDeps则把所有副作用run_langsmith_cli、run_agent_mode、run_agent_review_mode、ask_user、tempdir_factory抽象为可注入依赖这也是测试能够用假实现替换真实调用的关键设计见 test_helpers.py 中的_make_deps。工作区布局Wiki 的物理形态init模式会在本地生成如下顶层布局这也是 Context Hub 仓库中的目录规范AGENTS.md—— Wiki 的 schema/配置与工作流规则Agent 在 ingest/query/lint 时遵循它。init在缺失时创建重复运行时保留既有编辑对应_write_if_missing的仅缺失时写入语义见 helpers.py。默认内容由_agents_md()生成强调/raw/只读、/log.md追加式、/wiki/index.md是权威导航等规则。raw/—— 不可变的源文件文章、笔记、数据集由 ingest 阶段放入Agent 被系统提示与文件权限双重约束为只读。wiki/—— LLM 维护的知识页面实体、概念、摘要、综合。默认偏好扁平结构仅当目录确实能改善组织时才允许子目录该规则同时写进了AGENTS.md模板与 ingest 提示词。wiki/index.md—— 面向内容的目录页为 Wiki 导航与检索服务分好类的页面链接 一行摘要 可选元数据如日期/源数量。query 流程首先读取它。log.md—— 追加式的按时间顺序交互日志。每次 ingest/query/lint 阶段都会追加一个可解析的标题## [YYYY-MM-DD] mode.phase | outcome...配以时间戳与摘要条目。index.py 展示了 index 的分类逻辑_INDEX_CATEGORY_ORDER固定为 Entities、Concepts、Sources、Timelines、Queries、Syntheses、Other Pages 七类按目录名自动归类entity/、concept/、query/等子目录分别映射到对应分类每个条目从页面内容提取标题首个#标题、一行摘要首个非标题非代码块的正文行超过 150 字符截断与元数据页面中出现的最后日期、/raw/源引用计数。环境要求与安装README 列出的硬性要求如下Python 3.11与 pyproject.toml 中requires-python 3.11一致langsmith[sandbox]且提供可用的hub命令uv sync时随示例环境一起安装LANGSMITH_API_KEYingest、query、lint三个模式必须设置因为 Agent 运行在langsmith.sandbox中init模式不需要。依赖版本声明位于 pyproject.toml[project] name llm-wiki-example version 0.1.0 description LLM wiki using Deep Agents LangSmith CLI requires-python 3.11 dependencies [ deepagents0.6.12, langsmith[sandbox]0.9.3, ] [tool.uv.sources] deepagents { path ../../libs/deepagents, editable true }注意最后一段deepagents以 editable 方式指向仓库内的 libs/deepagents因此示例始终使用当前仓库源码而不是 PyPI 上的发布版本。安装与预检命令在 deepagents 仓库根目录执行# 1. 安装示例依赖创建 examples/llm-wiki 的独立虚拟环境 uv sync --project examples/llm-wiki # 2. 验证示例环境中可用的 Hub 命令 uv run --project examples/llm-wiki langsmith hub --help # 3. 验证沙箱模式所需的认证环境变量输出 set 即已配置 echo ${LANGSMITH_API_KEY:set}从源码看预检背后有两道防线helpers.py_resolve_langsmith_binary()在PATH上查找langsmith二进制找不到直接抛WikiError并提示先安装_ensure_hub_command_support()运行langsmith hub --help若退出码非 0 则判定该 CLI 不支持hub子命令并给出可操作报错测试用例test_ensure_hub_command_support_raises_for_incompatible_cli验证了这一点。CLI 使用全解四个模式一条命令runner.py是唯一入口所有模式统一通过--mode选择。README 给出了完整示例# 1. 初始化 Wiki 并发布首个 Context Hub 版本 uv run --project examples/llm-wiki \ python examples/llm-wiki/runner.py \ --mode init \ --repo ada-lovelace-wiki # 2. 把源笔记吸收为规范的 Wiki 页面同时支持单文件与文件夹 uv run --project examples/llm-wiki \ python examples/llm-wiki/runner.py \ --mode ingest \ --repo ada-lovelace-wiki \ --source ./notes/ada.md \ --source ./notes/speeches/ # 3. 基于维护中的 Wiki 提出有依据的问题 uv run --project examples/llm-wiki \ python examples/llm-wiki/runner.py \ --mode query \ --repo ada-lovelace-wiki \ --question What did Ada contribute to computing? # 4. 执行一次 Wiki 维护并发布更新的 Context Hub 版本 # 修复链接、去重页面、刷新 index.md、追加 log.md 条目 uv run --project examples/llm-wiki \ python examples/llm-wiki/runner.py \ --mode lint \ --repo ada-lovelace-wiki可选参数一览参数适用模式说明--owner acme全部当仓库位于显式 owner 下时指定也支持把--repo写成owner/repo形式两者同时提供时必须以--repo中的 owner 为准冲突会直接报错--review仅 ingest开启审阅后应用的两阶段操作者介入流程--description ...仅 init设置 Hub 仓库描述仅当 CLI 支持对应 flag 时生效--source path仅 ingest可重复传入文件或目录皆可目录会被递归展开--question ...仅 query要回答的问题必填--note ...ingest / lint注入到提示词中的附加操作者说明--model ...全部覆盖create_deep_agent使用的模型--topic-dir path仅 init指定本地 Wiki 目录默认是./wikis/topic-slugtopic 由 repo 名自动派生例如ada-lovelace-wiki→Ada Lovelace Wiki参数校验规则在parse_config()helpers.py中强制ingest模式必须有--sourcequery模式必须有--question--repo不能为空、至多包含一个/段。runner.py的main()把所有异常收敛为一行error: ...并以退出码 1 返回。init的隐藏逻辑internal source 强制校验README 特别强调init会自动从hub init --help输出中探测可用的 internal-source 参数--repo-source internal、--source internal或--internal按优先级取第一个匹配见 init.py 的_resolve_internal_source_flag_from_help在首次 push 之前还会通过/api/v1/repos预创建/校验仓库并设置sourceinternal。如果已有仓库不是 internal 源init会快速失败并给出可操作的错误信息。实现上ensure_internal_repo_default()先对/api/v1/repos/{owner}/{repo}发 GET 请求404 时用 POST/api/v1/repos创建repo_typeagent、is_publicfalse、sourceinternal存在时则解析source/repo_source/嵌套repo.source元数据非internal一律拒绝。verify_internal_repo_source()在 push 后再次通过hub get --format json复核必要时回退到 repos API。这解释了为什么测试test_run_init_creates_internal_repo_when_missing会断言 POST body 中同时包含source: internal。Ingest 工作流从原始素材到规范页面默认情况下ingest直接应用README 原文ingest applies directly by default。它的实际执行路径是expand_sources()ingest.py把--source参数展开为确定的文件列表文件直接收下目录递归收集符号链接一律拒绝空目录报错_stage_sources()helpers.py把源文件去重、拷贝进工作区的raw/同名文件自动改名为name-2.md之类避免覆盖并对每个文件做后缀白名单.md、.txt、.json、.yaml、.yml、.csv与 UTF-8 可解码校验Agent 读取/raw/中的素材把非结构化的笔记收敛为规范的概念/实体/主题页面并整合跨源综合结论而非逐源摘要runner 刷新wiki/index.md并在log.md追加ingest.apply | outcomeapplied条目。--review操作者介入的两阶段流程传入--review后ingest 变为两阶段Review 阶段只读模型读取暂存的源文件返回关键要点、建议的 Wiki 更新、矛盾点与 index 更新方案build_ingest_review_prompt强制输出六个章节逐源提取、提议的 Wiki 变更集、跨源综合、矛盾与未决声明、index 更新与 recency 说明、缺口与后续问题Apply 阶段写入你确认后模型把规范的概念/实体/主题更新写入页面并把证据直接整合进页面runner 刷新wiki/index.md追加结构化的ingest.review/ingest.apply时间线条目拒绝确认时跳过 Wiki 编辑但仍追加ingest.apply | outcomecanceled条目并照常 push保证时间线完整测试test_run_ingest_workspace_cancelled_skips_apply断言了calls [review]且 log 中同时出现outcomecompleted与outcomecanceled。此外ingest默认支持批量一次运行可以同时处理多个文件和目录README 原文 Batch ingest is the default. A single run can process multiple files and directories.。Query 工作流检索、作答、按需固化query自动运行两个阶段分析阶段只读模型按固定顺序检索——先读/wiki/index.md其分类摘要与元数据用于选择候选页面再读最近约 10 条log.md标题以获取 recency 上下文然后优先检查既往wiki/query/*.md页面做发现/路由据此定位规范页面展开后给出带引用的答案并判断结果是否值得固化。README 明确了两类证据的等级query 页面只是路由提示routing hints不是主要证据log.md只是操作上下文不是事实依据。最终答案要求以ANSWER:、FILING_DECISION: file|skip、FILING_REASON:三个精确键输出。固化阶段写入条件性若答案具有持久复用价值should_file truerunner 把它写入wiki/query/question-slug.mdslug 由问题文本截取前 80 字符生成见query_slug()并刷新wiki/index.md。固化页面必须包含Question、Answer、Sources三个章节。runner 总会把query.reviewoutcomefile或outcomeskip和可选的query.applyoutcomefiled追加到log.md并 push——即便决策是 skip查询历史也会保留测试test_run_query_workspace_skip_keeps_query_read_only验证了 skip 时不运行写阶段、不产生query.apply条目。parse_query_decision()query.py用正则解析决策标记标记缺失时安全默认skip避免破坏性写入。Lint 工作流单趟对账lint是单趟single-pass并立即应用健康检查阶段写入模型先读最近约 10 条log.md标题获取 recency 上下文然后直接在/wiki/中就地修正调和跨页矛盾未决时保留显式不确定性、更新被新证据取代的过时声明、检测无入链的孤儿页面并修复/合并、补齐相关页面之间的交叉引用、为缺失的重要概念创建规范页面并加链、识别数据缺口。build_lint_promptlint.py特别指出不得单独创建 lint 报告目录若模型运行时没有可用的网络检索能力就不得编造结论而应把缺口标记为未决并列出待核实项。缺口报告阶段仅响应模型返回一份简洁摘要包含已对账变更、剩余缺口、建议的后续问题与来源固定三个章节## Reconciled Changes、## Remaining Gaps、## Suggested Next Questions and Sources。runner 刷新wiki/index.md追加lint.apply | outcomeapplied条目并 push。Log 时间线可被 shell 工具解析的审计日志log.md由 runner 管理、只追加且刻意设计成可用简单 shell 工具解析。关键约定README log.pyAgent 不得直接编辑log.md条目由 runner 追加每次交互都会记录ingest.review开启--review时、ingest.applyoutcomeapplied或outcomecanceled、query.reviewoutcomefile或outcomeskip、query.apply仅固化时outcomefiled、lint.applyoutcomeapplied条目形态标题## [YYYY-MM-DD] mode.phase | outcome... keyvalue ...header 最多 220 字符metadata 按键排序含空格的取值用双引号包裹正文timestampUTC格式YYYY-MM-DDTHH:MM:SSZ与summary最多 320 字符两条 bullet# 查看最近 5 条时间线条目 grep ^## \\[ log.md | tail -5 # 查看最近 10 条 query review 的 outcome grep ^## \\[.*\\] query.review \\| log.md | tail -10单元测试test_append_log_entry_normalizes_and_truncates_fields验证了标题保持单行、多行内容被归一化、特殊字符被引号包裹等行为——这正是grep 友好的保证。底层实现沙箱、路由与文件权限所有 Agent 模式ingest/query/lint都在 LangSmith Sandbox 中执行helpers.py 的_create_langsmith_sandbox_backend检查LANGSMITH_API_KEY并惰性导入langsmith.sandbox.SandboxClient缺失时报错提示pip install langsmith[sandbox]从环境变量解析快照与镜像配置全部有默认值环境变量默认值作用WIKI_SANDBOX_SNAPSHOTdeepagents-wiki沙箱快照名称WIKI_SANDBOX_IMAGEpython:3快照的 Docker 镜像WIKI_SANDBOX_FS_CAPACITY_BYTES1717986918416 GiB快照文件系统容量上限快照不存在或未ready时自动创建随后创建沙箱用yield注入LangSmithSandbox后端结束时在finally中删除沙箱Agent 由create_deep_agent(model, backend, permissions, system_prompt)构建其中backend是CompositeBackend默认走沙箱而/raw/、/wiki/、/log.md、/AGENTS.md四个路由转发到本地工作区的FilesystemBackendvirtual_modeTrue。_BASE_SYSTEM_PROMPT定义了 Agent 的长期行为准则把/raw/视为不可变证据、优先按结构压缩而非按删减压缩、保持不确定性显式、维护规范页面而非碎片化页面、让/wiki/index.md保持权威。文件系统策略则由FilesystemPermission硬性约束_permissions()FilesystemPermission(operations[write], paths[/raw/**], modedeny), FilesystemPermission(operations[write], paths[/AGENTS.md], modedeny), FilesystemPermission(operations[write], paths[/wiki/**], modeallow), FilesystemPermission(operations[write], paths[/log.md], modedeny),即Agent 只能写/wiki/**raw/、AGENTS.md、log.md一律只读而_review_permissions()把所有路径都设为 deny把审阅阶段严格锁定为只读。这一权限兜底 提示词约束的双层设计是防止 Agent 越权修改不可变素材或审计日志的关键。此外还有一层文件系统安全整个工作区禁止符号链接_ensure_no_symlinks所有写入走_safe_write_text用O_NOFOLLOW拒绝符号链接目标防止把内容写到工作区之外push 前执行_validate_text_only_directory仅允许五种文本后缀且必须 UTF-8 可解码否则报错 Binary uploads are not supported in v1。这些细节在测试中被逐一验证例如test_ensure_no_symlinks_rejects_workspace_symlink与test_stage_sources_avoids_symlink_destination。一次完整的运行闭环把四个模式串起来一个典型的维护周期是init创建本地工作区骨架raw/、wiki/、wiki/index.md、log.md、AGENTS.md在 Context Hub 预创建/校验 internal 仓库hub inithub push发布首个版本ingest建议配合--review把--source指定的素材展开、暂存进raw/审阅后让 Agent 将证据整合为规范页面runner 刷新 index、追加日志并 pushquery随时基于当前 Wiki 提问得到带页面引用的答案高复用价值的问答被固化到wiki/query/并进入 indexlint定期单趟对账修正矛盾、过时声明、孤儿页面与缺失交叉引用产出缺口报告并 push。整个过程中log.md作为追加式审计线索贯穿始终wiki/index.md作为内容目录持续保持最新而 Context Hub 承担版本化与协作职责——这正是团队可以审阅变更、评论并提升版本这一设计目标的落点。仓库还提供了完整的单元测试套件examples/llm-wiki/tests/unit_tests/test_helpers.py覆盖 CLI 解析、Hub 兼容性、internal source 校验、ingest 审阅/取消/直落、query 固化/skip、lint 单趟等 40 场景可以作为你改造或扩展该示例时的行为基线。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考