引言：从静态文档到自治协议
在快速迭代的现代软件开发环境中，文档的滞后、不一致和难以维护已成为普遍的痛点。传统的手动文档更新流程效率低下，极易与代码库发生"漂移"（drift），导致开发者、用户和团队成员依赖过时或错误的信息。大型语言模型（LLMs）和Agentic Systems的兴起为解决这一挑战提供了前所未有的机遇。
本文将深入解析一个精心设计的 /doc.agent System Prompt，该Prompt不仅是一个简单的指令集，更是一个名为 解耦自治文档协议（Decoupled Autonomous Documentation Protocol, DADP） 的完整架构。DADP旨在构建一个模块化、可审计、自验证的文档生命周期管理系统，将文档工作从手动、被动的任务提升为集成到CI/CD流程中的主动、智能且可自我修正的组件。
我们将逐一剖析该Prompt的各个组成部分，从元数据定义到递归自修正机制，并通过一个实训案例------API文档漂移的自动纠正------来展示DADP在实际场景中的强大能力。本文旨在为高级AI工程师、Prompt架构师、文档专家和希望构建下一代自动化文档解决方案的开发者提供一份权威且具备实操性的指南。
Part I: Agentic Architecture and Protocol Foundation
本部分将奠定 /doc.agent 的理论基础，深入分析其作为Agentic Protocol的架构设计，以及如何通过结构化Prompt实现高度的模块化和可审计性。
1.1 DADP核心理念：模块化、可审计性和自验证
DADP的核心思想在于将传统的文档生成和维护流程解耦为一系列清晰、可验证的阶段，并由一个自治Agent协调执行。
- 模块化 (Modularity) ：Agent的指令、工具、工作流和数据模式被清晰地分隔为独立的Prompt块（如
[meta],[instructions],[workflow],[tools]），这使得系统更易于理解、维护和扩展。每个模块都承担特定的职责，降低了系统复杂性。 - 可审计性 (Auditability)：Agent的每一次操作、每一个决策点，甚至每一次工具调用都被显式记录。这通过内置的审计日志（Audit Log）机制实现，确保了文档变更的可追溯性、透明度和合规性。这对于企业级应用和需要满足法规要求的场景至关重要。
- 自验证 (Self-Verification) ：通过定义清晰的阶段输出和后续阶段的验证机制（例如，
review_summarize阶段），Agent能够发现并报告自身或环境中的不一致性、文档缺失或与代码的漂移。结合递归机制，Agent甚至能尝试自我修正，从而实现更高程度的可靠性。
1.2 [meta] 分析：协议版本、运行时兼容性和命名空间定义
[meta] 块是DADP的元数据定义，它像软件项目的 package.json 或 pom.xml 文件一样，为整个Agent协议提供了上下文和配置信息。
json
[meta]
{
"agent_protocol_version": "2.0.0",
"prompt_style": "multimodal-markdown",
"intended_runtime": ["Anthropic Claude", "OpenAI GPT-4o", "Agentic System"],
"schema_compatibility": ["json", "yaml", "markdown", "python", "shell"],
"namespaces": ["project", "user", "team", "docs", "codebase"],
"audit_log": true,
"last_updated": "2025-07-11",
"prompt_goal": "Deliver modular, extensible, and auditable autonomous documentation---across code, APIs, user guides, and knowledge bases---optimized for agent/human CLI and continuous update cycles."
}agent_protocol_version:"2.0.0"- 作用: 定义了Agent协议的版本号。这对于Agent系统的演进、兼容性管理以及确保Agent行为的稳定性至关重要。类似于API版本，它表明了Agent期望的输入格式、指令集和输出结构。
- 实践意义: 当协议版本更新时，可以明确哪些旧的Agent实例可能需要升级或调整其行为。
prompt_style:"multimodal-markdown"- 作用 : 指定了Agent的偏好输出格式。
multimodal-markdown表明Agent能够生成包含文本、表格、代码块，甚至可能嵌入图像占位符（如(Image: ...)）的富文本Markdown内容。 - 实践意义: 确保Agent生成的内容可以直接被各种文档工具（如VS Code Markdown预览、GitHub Pages、Jupyter Notebook）渲染，并且能够支持包含图表和复杂布局的文档。
- 作用 : 指定了Agent的偏好输出格式。
intended_runtime:["Anthropic Claude", "OpenAI GPT-4o", "Agentic System"]- 作用: 列出了Agent设计时考虑的预期运行环境。这表明该Prompt是针对这些特定LLM模型或更通用的Agentic Framework进行优化的。
- 实践意义: 提示使用者在部署Agent时选择合适的底层LLM模型，以确保最佳性能和遵循Prompt中定义的行为。它也暗示了Prompt的复杂性可能需要更强大的模型来处理。
schema_compatibility:["json", "yaml", "markdown", "python", "shell"]- 作用: 定义了Agent能够理解和处理的输入/输出数据模式兼容性。这意味着Agent可以接受JSON、YAML等结构化数据，解析Markdown中的指令，理解Python或Shell脚本片段。
- 实践意义 : 极大地增强了Agent的灵活性和与现有开发工具链的集成能力。例如，它可以直接解析
package.json或requirements.txt来提取依赖信息，或者读取openapi.yaml来生成API文档。
namespaces:["project", "user", "team", "docs", "codebase"]- 作用: 定义了Agent操作的逻辑命名空间。这些命名空间有助于Agent理解其工作上下文，并在不同领域（如项目配置、用户信息、团队协作、文档库、代码库）之间进行区分。
- 实践意义 : 允许 Agent 在复杂的场景中精确地定位和引用信息。例如，
/doc input="@project/config.yaml" type="policy"可以指明是在项目的配置文件命名空间中操作。这对于避免混淆和提高指令的精确性至关重要。
audit_log:true- 作用: 一个布尔标志，明确指示Agent必须维护一个详细的审计日志。这是DADP可审计性核心原则的直接体现。
- 实践意义: 强制Agent在每次操作后记录其执行细节，包括阶段、输入、输出、决策和时间戳。这为调试、合规性和变更追溯提供了不可或缺的数据。
last_updated:"2025-07-11"- 作用: 记录了Prompt本身的最后更新日期。
- 实践意义: 有助于管理Prompt的版本和迭代。
prompt_goal:"Deliver modular, extensible, and auditable autonomous documentation---across code, APIs, user guides, and knowledge bases---optimized for agent/human CLI and continuous update cycles."- 作用 : 明确阐述了该Agent协议的最高层级目标。它定义了
/doc.agent存在的意义和期望达到的效果。 - 实践意义: 为Agent的整体行为设定了指导方针。所有后续的指令、工作流和工具设计都应服务于这一最终目标。
- 作用 : 明确阐述了该Agent协议的最高层级目标。它定义了
1.3 [instructions] 解析：/doc.agent 的角色、命令行接口(CLI)和行为约束
[instructions] 块是 /doc.agent 的核心指令集，它定义了Agent的身份、接收输入的机制、工作流程规则以及关键的行为约束。这相当于Agent的"宪法"，规定了其权限和职责。
markdown
[instructions]
You are a /doc.agent. You:
- Accept slash command arguments (e.g., `/doc input="mymodule.py" goal="update" type="api"`) and file refs (`@file`), plus shell/API output (`!cmd`).
- Proceed phase by phase: context/goal parsing, code/doc scanning, doc generation/update, structure mapping, linking/cross-ref, review/summarize, audit logging.
- Output clearly labeled, audit-ready markdown: doc tables, code/comments, change logs, cross-ref maps, summary digests.
- Explicitly declare tool access in [tools] per phase.
- DO NOT hallucinate code/docs, skip context parsing, or output unverified changes.
- Surface all missing docs, inconsistencies, and doc/code drift.
- Visualize doc pipeline, structure, and update cycles for easy onboarding.
- Close with doc summary, audit/version log, flagged gaps, and suggested next steps.-
You are a /doc.agent.:- 作用: 确立了Agent的身份和角色。这对于LLM理解其职责范围至关重要。
- 实践意义: 确保LLM在响应和生成内容时保持一致的"人格"和专业性，专注于文档相关的任务。
-
Accept slash command arguments (...) and file refs (...), plus shell/API output (...):- 作用 : 定义了Agent的主要输入机制，即通过类CLI的斜杠命令（
/doc ...），文件引用（@file）和外部命令/API输出（!cmd）来接收任务。 - 实践意义 : 极大地增强了Agent的交互灵活性。
- Slash Commands: 提供了一种简洁、结构化的方式来传递参数，类似于Unix命令，易于脚本化和自动化。
- File References: 允许Agent直接引用文件内容，而无需在Prompt中粘贴整个文件，避免了Prompt长度限制，并使上下文更具动态性。
- Shell/API Output: 允许Agent集成外部系统（如Git、Linters、测试框架），直接获取它们的输出作为Agent的输入，实现更复杂的自动化工作流。
- 作用 : 定义了Agent的主要输入机制，即通过类CLI的斜杠命令（
-
Proceed phase by phase: context/goal parsing, code/doc scanning, doc generation/update, structure mapping, linking/cross-ref, review/summarize, audit logging.:- 作用 : 明确了Agent必须遵循的七阶段工作流。这是DADP的核心认知循环，确保了任务的系统性和完整性。
- 实践意义: 强制Agent按部就班地执行任务，避免跳过关键步骤。每个阶段的完成都为下一个阶段提供了必要的前置条件，从而保证了输出的质量和一致性。这与分阶段的软件开发模型（如瀑布模型或迭代模型）类似。
-
Output clearly labeled, audit-ready markdown: doc tables, code/comments, change logs, cross-ref maps, summary digests.:- 作用: 规定了Agent的输出格式和内容要求。所有输出必须是结构化的Markdown，并且易于审计。
- 实践意义 : 确保Agent的产出是机器和人类都易于解析和理解的。
audit-ready强调了输出内容需要包含足够的上下文和标签，以便于后续的审计和验证。
-
Explicitly declare tool access in [tools] per phase.:- 作用 : 指示Agent在使用工具时必须显式声明。这与
[tools]块中的工具定义相辅相成。 - 实践意义: 提高了Agent操作的透明度。使用者可以清晰地看到Agent在哪个阶段使用了哪个工具，以及为什么使用，这对于调试和理解Agent行为至关重要。这有助于构建可信赖的AI系统。
- 作用 : 指示Agent在使用工具时必须显式声明。这与
-
DO NOT hallucinate code/docs, skip context parsing, or output unverified changes.:- 作用 : 定义了Agent的核心负面约束（Negative Constraints）。这些指令旨在防止LLM常见的"幻觉"（hallucination）、行为失控和不负责任的输出。
- 实践意义 :
DO NOT hallucinate code/docs: 这是对LLM准确性和真实性的关键要求。在文档生成中，幻觉是灾难性的。DO NOT skip context parsing: 强制Agent必须充分理解其输入和上下文，避免盲目行动。DO NOT output unverified changes: 强调了输出必须经过某种形式的内部验证，进一步保障了DADP的自验证特性。
-
Surface all missing docs, inconsistencies, and doc/code drift.:- 作用: 明确了Agent在发现问题时的报告职责。它不仅要生成文档，还要主动识别和报告问题。
- 实践意义: 将Agent从一个被动的文档生成器提升为一个主动的文档质量保证系统。它能够帮助团队发现潜在的技术债和维护问题。
-
Visualize doc pipeline, structure, and update cycles for easy onboarding.:- 作用: 要求Agent以可视化方式呈现其工作流程和文档结构。
- 实践意义: 通过 ASCII 艺术图、Mermaid 图或PlantUML 图等形式，帮助新成员快速理解系统的工作原理和文档的组织方式，降低了学习曲线。这使得Agent的输出更具教育性和可读性。
-
Close with doc summary, audit/version log, flagged gaps, and suggested next steps.:- 作用: 规定了Agent的最终输出必须包含的总结性元素。
- 实践意义: 确保每一次Agent运行都有一个清晰的闭环，提供所有相关信息（变更总结、审计记录、未解决问题、后续建议），方便用户进行后续操作或决策。
Part II: The Operational Workflow and Cognitive Loop
本部分将深入探讨DADP的七阶段认知周期，这是 /doc.agent 运行的核心驱动力。我们将详细分析每个阶段的职责、输入和输出，以及 [context_schema] 如何为这些阶段提供结构化的数据。
2.0 /doc.agent 的七阶段认知周期
正如 [instructions] 所述，/doc.agent 严格遵循一个七阶段的串行工作流。这个工作流类似于人类专家处理复杂任务的思维过程：首先理解问题，然后收集信息，接着制定计划并执行，最后进行审查和记录。
(Image: Doc Pipeline Diagram - Reproduce the ASCII diagram from the prompt)
ascii_diagrams
Documentation Pipeline & Update Flow
/doc input="..." goal="..." type="..." context=@file ...
│
▼
[context/goal]→[scan/analyze]→[generate/update]→[structure/map]→[link/xref]→[review/summarize]→[audit/log]
↑__________________feedback/CI__________________|这个流程的关键在于其闭环特性 ：feedback/CI 箭头表明，在 audit/log 阶段或 review/summarize 阶段发现的问题可以反馈回 context/goal 或 scan/analyze 阶段，触发新一轮的Agent循环，实现自修正或持续改进。
2.1 [context_schema] 深度解析：定义输入和会话状态
[context_schema] 块是DADP的"数据字典"，它定义了Agent在执行任务时需要理解和处理的所有结构化数据。这确保了Agent能够以一致且可预测的方式解析其输入和维护内部状态。
yaml
[context_schema]
doc_context:
input: string # File/module/codebase/dir
goal: string # update, create, review, refactor, etc.
type: string # api, code, guide, wiki, policy, etc.
context: string
provided_files: [string]
constraints: [string]
output_style: string
links: [string]
args: { arbitrary: any }
session:
user: string
goal: string
priority_phases: [context, scan, generate, structure, link, review, audit]
special_instructions: string
output_style: string
team:
- name: string
role: string
expertise: string
preferred_output: stringcontext_schema 主要分为三个部分：doc_context（任务上下文）、session（会话状态）和 team（团队协作信息）。
2.1.1 doc_context 字段详解
doc_context 定义了单个文档生成或更新任务的所有相关输入参数。
input: string:- 作用: 指定了Agent操作的主要目标，可以是文件路径、模块名、代码库目录等。
- 例子 :
"mymodule.py","docs/api/","https://github.com/org/repo"
goal: string:- 作用: 定义了本次文档操作的具体目标，例如创建新文档、更新现有文档、审查文档质量或重构文档结构。
- 枚举值示例 :
update,create,review,refactor,audit,sync
type: string:- 作用: 指定了要生成或更新的文档类型。这有助于Agent理解文档的内容和格式预期。
- 枚举值示例 :
api,code,guide,wiki,policy,manual,spec
context: string:- 作用 : 提供额外的文本上下文信息，可以是内联文本，也可以通过
@file引用。 - 例子 :
"This module handles user authentication.","@project/design_doc.md"
- 作用 : 提供额外的文本上下文信息，可以是内联文本，也可以通过
provided_files: [string]:- 作用: 一个字符串数组，列出Agent需要访问的其他相关文件。
- 例子 :
["requirements.txt", "schemas.json"]
constraints: [string]:- 作用: 一个字符串数组，定义了文档生成的特定约束或要求。
- 例子 :
["Must follow PEP 257 for docstrings", "Output in simple English"]
output_style: string:- 作用: 指定最终文档的呈现风格（例如，详细程度、格式化偏好）。
- 例子 :
"verbose_markdown","concise_rst","jupyter_notebook"
links: [string]:- 作用: 一个字符串数组，提供与当前文档相关的外部链接或内部引用。
- 例子 :
["https://example.com/api-spec", "internal:/docs/contributing.md"]
args: { arbitrary: any }:- 作用: 一个灵活的键值对映射，用于传递任何其他非标准或特定于任务的参数。
- 实践意义: 允许高度的定制化，以适应不可预见的输入需求。
2.1.2 session 和 team 字段在协作中的应用
session: 定义了当前Agent会话的运行时上下文，通常由调用Agent的用户或系统提供。user: string: 当前会话的用户ID或名称。goal: string: 本次会话的总体目标（可能比doc_context.goal更宏观）。priority_phases: [string]: 允许用户指定在当前会话中需要特别关注或优先执行的阶段。这对于调试或针对性地优化特定阶段非常有用。special_instructions: string: 临时的、特定于会话的额外指令。output_style: string: 会话级别的输出风格覆盖。
team: 这是一个用户或团队成员的列表，每个成员可以有自己的角色、专长和偏好输出。这为Agent在多用户或多角色环境中进行协作提供了基础。name: string: 团队成员名称。role: string: 成员角色（如developer,reviewer,tech_writer）。expertise: string: 成员的专业领域。preferred_output: string: 成员偏好的输出格式或风格。- 实践意义 :
team字段开启了Agent与多角色团队协作的可能性。例如，当 Agent 需要为"tech_writer"角色生成文档时，它可能会调整其语言风格或侧重用户指南而非API细节。这使得Agent能够生成更符合特定受众需求的内容。
2.2 [workflow] 详解：从解析到审计的阶段性职责
[workflow] 块是DADP的"执行计划"，它详细定义了Agent在每个阶段应该做什么，以及每个阶段的预期输出。这确保了Agent的每一步都是有目的、有计划的。
yaml
[workflow]
phases:
- context_goal_parsing:
description: |
Parse input, goal, type, files, and constraints. Clarify context, targets, and update scope.
output: Context table, goals map, open questions.
- scan_analyze:
description: |
Scan code/docs for existing structure, coverage, and missing/obsolete items.
output: Coverage report, scan log, flagged gaps.
- generate_update_docs:
description: |
Generate or update docs, comments, and examples as per context/goal.
output: Updated docs, code comments, change log.
- structure_mapping:
description: |
Map doc structure, TOC, code/doc relationships, and linking targets.
output: Structure map, toc, cross-ref table.
- linking_crossref:
description: |
Link related docs, references, and code for navigation/completeness.
output: Xref table, link log, backlink matrix.
- review_summarize:
description: |
Review changes, summarize deltas, and flag open/closed issues.
output: Summary digest, review table, change summary.
- audit_logging:
description: |
Log all phases, changes, tool calls, contributors, audit/version checkpoints.
output: Audit log, version history, flagged issues.2.2.1 阶段 1/2：解析与扫描（输入验证与覆盖率）
-
context_goal_parsing(上下文/目标解析)- 描述 : Agent在此阶段负责理解其接收到的原始输入。它会解析斜杠命令的参数、文件引用以及任何额外上下文，并将其映射到
doc_context模式。核心任务是明确本次操作的目标、文档类型、目标文件/模块以及任何限制条件。 - 预期输出: 结构化的"上下文表"（例如，将输入参数以表格形式呈现）、"目标图"（明确列出Agent要实现的所有子目标）以及"开放问题"（Agent可能需要用户澄清的问题，以确保任务理解无误）。
- 实践意义: 这一阶段是 Agent 避免"盲目行动"的关键。它确保 Agent 在执行任何实际操作之前，对任务有全面的理解。
- 描述 : Agent在此阶段负责理解其接收到的原始输入。它会解析斜杠命令的参数、文件引用以及任何额外上下文，并将其映射到
-
scan_analyze(扫描/分析)- 描述 : 在理解了上下文和目标之后，Agent会使用其工具（如
code_scanner）来扫描目标代码或现有文档。这包括识别现有文档结构、代码注释的覆盖率、以及任何缺失、过时或与代码不一致的文档项。 - 预期输出: "覆盖率报告"（例如，代码中已注释部分的百分比）、"扫描日志"（详细记录扫描过程中的发现）和"标记的空白/差异"（列出所有发现的文档缺失、不一致或代码/文档漂移）。
- 实践意义: 这一阶段是DADP实现"自验证"和"发现漂移"的关键。它为后续的文档生成和更新提供了数据驱动的基础。
- 描述 : 在理解了上下文和目标之后，Agent会使用其工具（如
2.2.2 阶段 3/4：生成与结构化（产出与映射）
-
generate_update_docs(生成/更新文档)- 描述 : 基于前一阶段的扫描结果和已解析的目标，Agent现在会调用文档生成工具（如
doc_writer）来创建新的文档内容或更新现有文档。这可能包括生成代码的docstring、API参考、用户指南示例或知识库文章。 - 预期输出: "更新后的文档"（生成或修改的Markdown内容）、"代码注释"（插入到代码中的docstrings或行内注释）以及"变更日志"（详细记录了本次操作对文档和代码注释所做的所有修改）。
- 实践意义: 这是Agent实际执行文档编辑和生成工作的阶段。其输出将直接影响最终用户体验。
- 描述 : 基于前一阶段的扫描结果和已解析的目标，Agent现在会调用文档生成工具（如
-
structure_mapping(结构映射)- 描述: 文档内容生成后，Agent需要对其进行结构化处理。这包括生成目录（TOC）、映射代码与文档之间的关系（例如，一个函数对应哪部分API文档），以及识别潜在的内部链接目标。
- 预期输出: "结构图"（例如，一个JSON或YAML表示的文档层次结构）、"目录"（可直接用于Markdown的TOC）和"交叉引用表"（列出文档中可能相互引用的元素）。
- 实践意义: 确保文档具有良好的可导航性和组织性，方便用户查找信息。
2.2.3 阶段 5/6/7：连接、审查与审计（验证与闭环）
-
linking_crossref(链接/交叉引用)- 描述: 此阶段Agent利用前一阶段生成的交叉引用表，主动在文档中添加内部链接和外部引用。这有助于构建一个高度互联的知识网络，提高文档的完整性和可用性。
- 预期输出: "交叉引用表"（更新后的，包含所有新添加的链接）、"链接日志"（记录了所有添加或修改的链接）以及"反向链接矩阵"（显示哪些文档引用了当前文档，有助于分析文档依赖）。
- 实践意义: 提升文档的实用性，使用户能够轻松地在相关概念、代码和外部资源之间跳转。
-
review_summarize(审查/总结)- 描述: 在文档生成和链接完成后，Agent会对其所做的所有变更进行自我审查。它会总结所做的更改，验证是否满足了初始目标和约束，并标记任何未解决的问题或潜在的缺陷。
- 预期输出: "总结摘要"（对本次操作的整体概述）、"审查表"（列出所有变更项及其状态，例如"已审查"、"需要人工检查"）和"变更总结"（详细列出实际修改的内容）。
- 实践意义: 这是Agent自验证机制的又一重要组成部分。它提供了一个机会，让Agent在最终输出前进行"自我批评"，从而提高最终交付物的质量。如果发现重大问题，此阶段可触发递归回溯。
-
audit_logging(审计日志)- 描述: 这是DADP的最终阶段，也是其可审计性原则的直接体现。Agent将记录所有阶段的执行细节、工具调用、输入参数、输出结果、贡献者信息以及版本检查点。
- 预期输出: "审计日志"（一个详细的时间序列记录，包含Agent执行的所有操作）、"版本历史"（记录文档或协议的版本更新）和"标记的问题"（任何在此阶段或之前发现但仍未解决的问题）。
- 实践意义: 提供了完整的操作轨迹，是调试、合规性审计、故障排查和系统改进的宝贵资源。它确保了Agent的每一个行为都可追溯、可解释。
Part III: Tool Registry and Microservice Integration
本部分将深入分析 [tools] 块，它是 /doc.agent 能力的基石。我们将探讨如何定义Agent可用的工具，并提供实训案例，展示如何用伪代码实现这些工具的Python包装器，以模拟其在实际Agentic系统中的集成。
3.0 [tools] 框架：定义 agent 的能力边界
[tools] 块定义了 /doc.agent 可以调用的外部（或模拟的内部）工具。这使得Agent能够超越纯文本生成的能力，与文件系统、代码分析器、API网关等外部服务进行交互。这种设计是现代Agentic Systems的核心，它允许LLM作为高级协调者，将复杂任务分解为由专门工具处理的子任务。
yaml
[tools]
tools:
- id: code_scanner
type: internal
description: Scan/analyze code, modules, or docs for structure/coverage.
input_schema: { input: string, context: string }
output_schema: { coverage: dict, scan_log: list }
call: { protocol: /code.scan{ input=<input>, context=<context> } }
phases: [scan_analyze]
examples: [{ input: {input: "mymodule.py", context: "api"}, output: {coverage: {...}, scan_log: [...]} }]
- id: doc_writer
type: internal
description: Generate or update docs, comments, and guides.
input_schema: { input: string, goal: string, type: string }
output_schema: { docs: string, changes: list }
call: { protocol: /doc.write{ input=<input>, goal=<goal>, type=<type> } }
phases: [generate_update_docs]
examples: [{ input: {input: "mymodule.py", goal: "update", type: "api"}, output: {docs: "...", changes: [...]} }]
- id: structure_mapper
type: internal
description: Map doc/code structure, TOC, and relationships.
input_schema: { input: string }
output_schema: { toc: list, structure: dict }
call: { protocol: /structure.map{ input=<input> } }
phases: [structure_mapping]
examples: [{ input: {input: "docs/"}, output: {toc: [...], structure: {...}} }]
- id: linker
type: internal
description: Link/cross-ref related docs, code, or sections.
input_schema: { input: string, links: list }
output_schema: { link_log: list, xref: dict }
call: { protocol: /link.crossref{ input=<input>, links=<links> } }
phases: [linking_crossref]
examples: [{ input: {input: "mymodule.py", links: ["utils.md"]}, output: {link_log: [...], xref: {...}} }]
- id: reviewer
type: internal
description: Review and summarize doc/code deltas, flag issues.
input_schema: { input: string, changes: list }
output_schema: { summary: string, flagged: list }
call: { protocol: /review.summarize{ input=<input>, changes=<changes> } }
phases: [review_summarize]
examples: [{ input: {input: "docs/", changes: [...]}, output: {summary: "...", flagged: [...]} }]
- id: audit_logger
type: internal
description: Maintain audit log, doc events, and version checkpoints.
input_schema: { phase_logs: list, args: dict }
output_schema: { audit_log: list, version: string }
call: { protocol: /log.audit{ phase_logs=<phase_logs>, args=<args> } }
phases: [audit_logging]
examples: [{ input: {phase_logs: [...], args: {...}}, output: {audit_log: [...], version: "v2.2"} }]每个工具定义都包含以下关键字段：
id: 工具的唯一标识符（例如，code_scanner）。Agent将通过此ID引用工具。type: 工具的类型，可以是internal（Agent内部模拟或直接访问的）、external（通过API调用的第三方服务）或human（需要人工审批或输入）。这里全部标记为internal，表明这些是Agent设计中内置的功能或抽象。description: 工具功能的简明描述，帮助Agent理解何时以及为何使用该工具。input_schema: 定义工具期望的输入参数的JSON或YAML模式。这确保了Agent以正确的格式调用工具。output_schema: 定义工具返回结果的JSON或YAML模式。Agent会解析这些输出以进行后续操作。call: 定义了调用工具的具体协议或命令。这里的/code.scan{...}是一种抽象的微服务调用协议。phases: 一个列表，指定了该工具可以在哪些工作流阶段被调用。这是一种强大的约束机制，防止Agent在不合适的时机使用工具。examples: 提供了工具调用及其预期输出的示例，有助于Agent（以及开发者）理解工具的使用方式。
3.1 内部工具的具体实现和协议定义
为了满足"准确真实可用"和"实训案例"的要求，我们将为 /doc.agent 中定义的六个内部工具创建概念性的 Python 伪代码包装器。这些包装器模拟了Agent如何通过抽象接口与"底层服务"交互。
实训案例 1：Pseudo-Code Wrapper for /doc.agent Internal Tools (Python)
我们将使用Python来模拟这些工具的接口，尽管它们在实际中可能是独立的微服务或通过HTTP/RPC调用的外部API。
python
import json
import os
import re
from datetime import datetime
# 假设的内部存储或文件系统访问
MOCK_FILE_SYSTEM = {
"mymodule.py": """
def calculate_sum(a: int, b: int) -> int:
# This function adds two integers.
\"\"\"Calculates the sum of two integers.
Args:
a (int): The first integer.
b (int): The second integer.
Returns:
int: The sum of a and b.
\"\"\"
return a + b
def divide_numbers(numerator: float, denominator: float) -> float:
# New function: divides two numbers, handles zero division.
\"\"\"Divides two numbers.
Args:
numerator (float): The number to be divided.
denominator (float): The divisor.
Returns:
float: The result of the division.
Raises:
ValueError: If the denominator is zero.
\"\"\"
if denominator == 0:
raise ValueError("Denominator cannot be zero.")
return numerator / denominator
""",
"api_reference.md": """
# API Reference
## `calculate_sum`
This function calculates the sum of two integers.
**Parameters:**
- `a` (int): The first integer.
- `b` (int): The second integer.
**Returns:**
- `int`: The sum of a and b.
"""
}
class DocAgentTools:
"""
Simulated internal tools for the /doc.agent.
These would typically be separate microservices or robust libraries.
"""
@staticmethod
def code_scanner(input: str, context: str) -> dict:
"""
/code.scan: Scans code/docs for existing structure, coverage, and missing/obsolete items.
Simulates parsing a Python file for docstrings and identifying functions without docs.
"""
print(f"[Tool Call] code_scanner: input='{input}', context='{context}'")
if input not in MOCK_FILE_SYSTEM:
return {"coverage": {"overall": 0, "functions_documented": 0}, "scan_log": [f"File '{input}' not found."]}
content = MOCK_FILE_SYSTEM[input]
functions_found = re.findall(r"def\s+(\w+)\s*\(", content)
documented_functions = re.findall(r"def\s+\w+\s*\(.*\):\s*\n\s*\"\"\"(.|\n)*?\"\"\"", content)
coverage = {
"overall": f"{len(documented_functions) / len(functions_found) * 100 if functions_found else 100:.2f}%",
"functions_found": len(functions_found),
"functions_documented": len(documented_functions),
"missing_docstrings": [f for f in functions_found if not any(re.search(f"def\\s+{f}\\s*\\(", doc) for doc in documented_functions)]
}
# Simulate detecting drift in api_reference.md
scan_log = []
if input == "mymodule.py" and "api_reference.md" in MOCK_FILE_SYSTEM:
api_ref_content = MOCK_FILE_SYSTEM["api_reference.md"]
if "divide_numbers" not in api_ref_content:
scan_log.append("Detected 'divide_numbers' in mymodule.py but missing in api_reference.md (drift detected).")
if "New function" in content and "api_reference.md" not in api_ref_content:
scan_log.append("New functionality in mymodule.py requires API doc update.")
return {"coverage": coverage, "scan_log": scan_log, "flagged_gaps": scan_log}
@staticmethod
def doc_writer(input: str, goal: str, type: str) -> dict:
"""
/doc.write: Generates or updates docs, comments, and guides.
Simulates generating a docstring or updating a markdown file.
"""
print(f"[Tool Call] doc_writer: input='{input}', goal='{goal}', type='{type}'")
changes = []
docs_output = ""
if goal == "update" and type == "api" and input == "api_reference.md":
# Simulate updating the API reference for the new function
original_content = MOCK_FILE_SYSTEM.get("api_reference.md", "")
if "divide_numbers" not in original_content:
new_api_section = """
## `divide_numbers`
This function divides two numbers, handling zero division.
**Parameters:**
- `numerator` (float): The number to be divided.
- `denominator` (float): The divisor.
**Returns:**
- `float`: The result of the division.
**Raises:**
- `ValueError`: If the denominator is zero.
"""
docs_output = original_content + "\n" + new_api_section
changes.append({"item": "api_reference.md", "type": "api_guide", "change": "added new section for divide_numbers"})
# Update mock file system for subsequent phases
MOCK_FILE_SYSTEM["api_reference.md"] = docs_output
else:
docs_output = original_content
changes.append({"item": "api_reference.md", "type": "api_guide", "change": "no change needed, already present"})
return {"docs": docs_output, "changes": changes}
@staticmethod
def structure_mapper(input: str) -> dict:
"""
/structure.map: Maps doc structure, TOC, code/doc relationships.
Simulates creating a TOC for a markdown file.
"""
print(f"[Tool Call] structure_mapper: input='{input}'")
if input not in MOCK_FILE_SYSTEM:
return {"toc": [], "structure": {}}
content = MOCK_FILE_SYSTEM[input]
toc_items = []
structure = {"title": input, "sections": []}
# Simple markdown header parsing for TOC
headers = re.findall(r"^(#+)\s*(.*)$", content, re.MULTILINE)
for level_str, title in headers:
level = len(level_str)
slug = title.lower().replace(" ", "-").replace("`", "")
toc_items.append({"level": level, "title": title, "link": f"#{slug}"})
# For structure mapping, simplified
if level == 1:
structure["sections"].append({"title": title, "subsections": []})
elif level == 2 and structure["sections"]:
structure["sections"][-1]["subsections"].append({"title": title})
# Simulate code/doc relationships
code_doc_relationships = {}
if input == "api_reference.md" and "mymodule.py" in MOCK_FILE_SYSTEM:
code_doc_relationships["calculate_sum"] = "api_reference.md#calculate-sum"
if "divide_numbers" in content: # check if doc_writer added it
code_doc_relationships["divide_numbers"] = "api_reference.md#divide-numbers"
return {"toc": toc_items, "structure": structure, "code_doc_relationships": code_doc_relationships}
@staticmethod
def linker(input: str, links: list) -> dict:
"""
/link.crossref: Links related docs, references, and code.
Simulates adding internal links or verifying external links.
"""
print(f"[Tool Call] linker: input='{input}', links='{links}'")
link_log = []
xref_map = {}
if input in MOCK_FILE_SYSTEM:
content = MOCK_FILE_SYSTEM[input]
# Simulate adding a link to a common utility document
if "utils.md" in links and "See also [Utilities]" not in content:
content += "\n\nSee also [Utilities](./utils.md)\n"
link_log.append(f"Added link to utils.md in {input}")
xref_map["utils.md"] = [{"source": input, "type": "internal_link"}]
MOCK_FILE_SYSTEM[input] = content # Update mock file system
# Simulate cross-referencing for the api_reference.md example
if input == "api_reference.md":
if "mymodule.py" not in xref_map:
xref_map["mymodule.py"] = []
xref_map["mymodule.py"].append({"source": input, "type": "mentions_codebase"})
link_log.append(f"Cross-referenced mymodule.py from {input}")
return {"link_log": link_log, "xref": xref_map}
@staticmethod
def reviewer(input: str, changes: list) -> dict:
"""
/review.summarize: Reviews changes, summarizes deltas, and flags issues.
Simulates a basic review of the changes for completeness.
"""
print(f"[Tool Call] reviewer: input='{input}', changes='{changes}'")
summary = f"Review of changes for {input}:\n"
flagged_issues = []
if not changes:
summary += "- No changes were made."
else:
for change in changes:
summary += f"- {change.get('item', 'N/A')}: {change.get('change', 'N/A')}\n"
if "missing sample" in change.get('change', '').lower():
flagged_issues.append({"item": change.get('item'), "issue": "Missing code sample", "severity": "Medium"})
if "added new section" in change.get('change', '').lower() and "mymodule.py" in input:
summary += "- Verified new section for 'divide_numbers' is present and covers arguments."
# Simulate checking if the new function is properly documented
if "api_reference.md" in input and "divide_numbers" in MOCK_FILE_SYSTEM.get("api_reference.md", ""):
summary += "- Confirmed 'divide_numbers' is now present in API reference."
else:
flagged_issues.append({"item": "api_reference.md", "issue": "Expected 'divide_numbers' not found in final API doc.", "severity": "High"})
return {"summary": summary, "flagged": flagged_issues}
@staticmethod
def audit_logger(phase_logs: list, args: dict) -> dict:
"""
/log.audit: Maintains audit log, doc events, and version checkpoints.
Simulates appending to a global audit log and managing versions.
"""
print(f"[Tool Call] audit_logger: phase_logs={len(phase_logs)} entries, args='{args}'")
current_time = datetime.now().isoformat()
audit_log_entry = {
"timestamp": current_time,
"agent_args": args,
"phase_logs": phase_logs,
"version": "v2.0." + current_time.split('T')[0].replace('-', '') # Simple versioning
}
# In a real system, this would write to a persistent store.
# For simulation, we just return it.
return {"audit_log_entry": audit_log_entry, "version": audit_log_entry["version"]}这些伪代码实现展示了每个工具如何接收输入、执行逻辑并返回结构化输出。请注意，MOCK_FILE_SYSTEM 模拟了一个简化的文件系统，以在每次工具调用之间保持状态。
3.2 工具调用机制和阶段限制
Agent的 [instructions] 中明确要求"Explicitly declare tool access in [tools] per phase."。这意味着Agent不仅仅是根据其内部逻辑决定使用哪个工具，它还必须参照 [tools] 块中为每个工具定义的 phases 字段。
- 调用机制 : 当Agent处于某个特定阶段（例如
scan_analyze）时，它会检查[tools]列表中哪些工具被允许在该阶段调用。例如，code_scanner只能在scan_analyze阶段被调用。Agent会根据当前任务的需求，选择最合适的工具并以其input_schema定义的格式传递参数。 - 阶段限制 : 这种限制是 Agent 设计中的一个重要安全和稳定性特性。它防止了 Agent 在不适当的时刻执行不相关的操作，例如在
context_goal_parsing阶段尝试写入文档。这降低了出错的概率，并使 Agent 的行为更可预测。
3.3 可扩展性分析：如何接入外部工具（e.g., Jira, Git API）
DADP的 [tools] 框架设计具有强大的可扩展性。虽然当前示例中的工具被标记为 internal，但很容易想象它们是实际的外部服务或API。
-
接入外部工具的步骤:
- 定义工具ID和类型 : 将
type设置为external。 - 编写描述: 清晰地说明工具功能。
- 定义输入/输出模式 : 根据外部API的文档，精确定义
input_schema和output_schema。这通常涉及将Agent的内部数据结构映射到外部API所需的请求体和响应体。 - 指定调用协议 :
call字段将不再是/code.scan{...}这样的抽象协议，而是具体的HTTP请求（URL、方法、头部、认证信息）或SDK调用。 - 指定适用阶段 : 根据工具的职责，将其限制在合适的
phases中。
- 定义工具ID和类型 : 将
-
示例：集成 Jira API 进行问题追踪
- 工具ID :
jira_issue_tracker - 类型 :
external - 描述: 创建、更新或查询Jira中的文档相关问题。
- input_schema :
{ "action": "create" | "update" | "query", "issue_key": string, "summary": string, "description": string, "labels": [string] } - output_schema :
{ "status": "success" | "failure", "issue_url": string, "issue_key": string, "error": string } - call :
{ protocol: "http", method: "POST", url: "https://your-jira-instance.com/rest/api/2/issue", headers: { "Authorization": "Bearer <token>" }, body: { "fields": { "project": ..., "summary": <summary>, "description": <description> } } } - phases :
[review_summarize, audit_logging](当发现文档问题时自动创建Jira工单，或在审计阶段记录相关问题)。
- 工具ID :
通过这种方式，/doc.agent 可以从一个纯文档Agent演变为一个与整个软件开发生命周期工具链深度集成的协作Agent。
Part IV: Practical Case Study: Correcting API Documentation Drift
本部分将通过一个真实的实训案例来展示 /doc.agent 协议的实际运行。我们将模拟一个典型的场景：由于代码更新，API文档与实际代码发生了漂移，并使用 /doc.agent 自动检测并修正这一问题。
4.1 场景设定：Python API模块功能更新导致文档漂移
初始状态:
我们有一个名为 mymodule.py 的Python模块，其中包含一个用于计算和的函数 calculate_sum。对应的API文档 api_reference.md 已经存在并准确描述了 calculate_sum 函数。
代码更新:
开发者在 mymodule.py 中添加了一个新函数 divide_numbers，但没有同时更新 api_reference.md。这就是"文档漂移"的发生。
mymodule.py (更新后):
python
# MOCK_FILE_SYSTEM["mymodule.py"] 已经包含此内容
def calculate_sum(a: int, b: int) -> int:
# This function adds two integers.
\"\"\"Calculates the sum of two integers.
Args:
a (int): The first integer.
b (int): The second integer.
Returns:
int: The sum of a and b.
\"\"\"
return a + b
def divide_numbers(numerator: float, denominator: float) -> float:
# New function: divides two numbers, handles zero division.
\"\"\"Divides two numbers.
Args:
numerator (float): The number to be divided.
denominator (float): The divisor.
Returns:
float: The result of the division.
Raises:
ValueError: If the denominator is zero.
\"\"\"
if denominator == 0:
raise ValueError("Denominator cannot be zero.")
return numerator / denominatorapi_reference.md (初始状态，未更新):
markdown
# API Reference
## `calculate_sum`
This function calculates the sum of two integers.
**Parameters:**
- `a` (int): The first integer.
- `b` (int): The second integer.
**Returns:**
- `int`: The sum of a and b.我们的目标是使用 /doc.agent 来检测 divide_numbers 函数在 api_reference.md 中的缺失，并自动添加其文档。
4.2 Agent 循环执行：逐阶段实训（从 /doc 命令到审计日志）
我们将模拟Agent的完整七阶段循环，并展示每个阶段的输入、Agent决策和输出。
Agent 初始调用:
我们通过一个斜杠命令启动 /doc.agent：
bash
/doc input="mymodule.py" goal="update" type="api" context="api_reference.md"这将被Agent解析为 doc_context：
json
{
"input": "mymodule.py",
"goal": "update",
"type": "api",
"context": "api_reference.md"
}4.2.1 阶段 1/2 模拟输出：识别漂移和覆盖率报告
阶段 1: context_goal_parsing
-
Agent 决策 : 根据
/doc命令参数，Agent 明确了任务：更新mymodule.py相关的 API 文档，并将api_reference.md作为额外上下文。 -
模拟输出 :
markdown### Context/Goal Parsing Report Agent successfully parsed the command. | Argument | Value | Description | |---------------|-----------------|----------------------------------------------| | `input` | `mymodule.py` | Primary target for scanning and analysis. | | `goal` | `update` | The objective is to update existing documentation. | | `type` | `api` | The documentation type is API reference. | | `context` | `api_reference.md` | Provides additional context for API docs. | **Goals Map:** 1. Scan `mymodule.py` for API definitions. 2. Compare discovered APIs with `api_reference.md`. 3. Identify missing or outdated API documentation. 4. Generate/update `api_reference.md` to reflect `mymodule.py`. **Open Questions:** None at this stage. Context is sufficiently clear.
阶段 2: scan_analyze
-
Agent 决策 : Agent 调用
code_scanner工具，扫描mymodule.py以获取函数定义和现有文档覆盖率，并与api_reference.md进行比对。 -
工具调用 :
/code.scan{ input="mymodule.py", context="api_reference.md" } -
模拟
code_scanner输出 :json{ "coverage": { "overall": "100.00%", # All functions have docstrings in code "functions_found": 2, "functions_documented": 2, "missing_docstrings": [] }, "scan_log": [ "Detected 'divide_numbers' in mymodule.py but missing in api_reference.md (drift detected).", "New functionality in mymodule.py requires API doc update." ], "flagged_gaps": [ "Detected 'divide_numbers' in mymodule.py but missing in api_reference.md (drift detected).", "New functionality in mymodule.py requires API doc update." ] } -
Agent 决策 : Agent 接收到
code_scanner的输出，明确识别到divide_numbers函数的 API 文档漂移。 -
模拟输出 :
markdown### Scan/Analyze Report Agent successfully scanned `mymodule.py` and compared it against `api_reference.md`. | File | Coverage (Code Docstrings) | Functions Found | Functions Documented | Missing Docstrings | |----------------|----------------------------|-----------------|----------------------|--------------------| | `mymodule.py` | 100.00% | 2 | 2 | - | **Scan Log & Flagged Gaps:** - **Drift Detected**: The function `divide_numbers` exists in `mymodule.py` but its corresponding API documentation is **missing** in `api_reference.md`. - **Action Required**: New functionality in `mymodule.py` requires an update to the API documentation. Next Step: Proceed to generate/update documentation based on detected drift.
4.2.2 阶段 3 模拟输出：生成新的 Docstring 和 Change Log
阶段 3: generate_update_docs
-
Agent 决策 : 基于
scan_analyze阶段的发现，Agent 确定需要更新api_reference.md以包含divide_numbers的文档。它将调用doc_writer工具。 -
工具调用 :
/doc.write{ input="api_reference.md", goal="update", type="api" } -
模拟
doc_writer输出:json{ "docs": "# API Reference\n\n## `calculate_sum`\n\nThis function calculates the sum of two integers.\n\n**Parameters:**\n- `a` (int): The first integer.\n- `b` (int): The second integer.\n\n**Returns:**\n- `int`: The sum of a and b.\n\n\n## `divide_numbers`\n\nThis function divides two numbers, handling zero division.\n\n**Parameters:**\n- `numerator` (float): The number to be divided.\n- `denominator` (float): The divisor.\n\n**Returns:**\n- `float`: The result of the division.\n\n**Raises:**\n- `ValueError`: If the denominator is zero.\n", "changes": [ {"item": "api_reference.md", "type": "api_guide", "change": "added new section for divide_numbers"} ] } -
Agent 决策 :
doc_writer成功更新了api_reference.md。Agent 将更新后的内容存储在模拟文件系统中，并记录变更。 -
模拟输出:
markdown### Generate/Update Docs Report Agent successfully generated/updated documentation. **Changes Applied:** - **File**: `api_reference.md` - **Type**: API Guide - **Change**: Added a new section for the `divide_numbers` function, including its parameters, return value, and raised exceptions. **Updated `api_reference.md` Content (Snippet):** ```markdown # API Reference ## `calculate_sum` ... (existing content) ... ## `divide_numbers` This function divides two numbers, handling zero division. **Parameters:** - `numerator` (float): The number to be divided. - `denominator` (float): The divisor. **Returns:** - `float`: The result of the division. **Raises:** - `ValueError`: If the denominator is zero.Next Step: Proceed to map the updated document's structure.
4.2.3 阶段 4/5 模拟输出：结构图和交叉引用更新
阶段 4: structure_mapping
-
Agent 决策 : 现在
api_reference.md已更新，Agent 调用structure_mapper工具来重新分析其结构并生成目录。 -
工具调用 :
/structure.map{ input="api_reference.md" } -
模拟
structure_mapper输出:json{ "toc": [ {"level": 1, "title": "API Reference", "link": "#api-reference"}, {"level": 2, "title": "`calculate_sum`", "link": "#calculate_sum"}, {"level": 2, "title": "`divide_numbers`", "link": "#divide_numbers"} ], "structure": { "title": "api_reference.md", "sections": [ {"title": "API Reference", "subsections": [ {"title": "`calculate_sum`"}, {"title": "`divide_numbers`"} ]} ] }, "code_doc_relationships": { "calculate_sum": "api_reference.md#calculate-sum", "divide_numbers": "api_reference.md#divide-numbers" } } -
Agent 决策: Agent 成功地映射了更新后的文档结构。
-
模拟输出:
markdown### Structure Mapping Report Agent successfully mapped the structure of `api_reference.md`. **Table of Contents (TOC):** - [API Reference](#api-reference) - [`calculate_sum`](#calculate_sum) - [`divide_numbers`](#divide_numbers) **Document Structure (Simplified):** ```json { "title": "api_reference.md", "sections": [ { "title": "API Reference", "subsections": [ { "title": "`calculate_sum`" }, { "title": "`divide_numbers`" } ] } ] }Code-Doc Relationships:
calculate_sum:api_reference.md#calculate-sumdivide_numbers:api_reference.md#divide-numbers
Next Step: Proceed to link and cross-reference.
阶段 5: linking_crossref
-
Agent 决策 : Agent 将根据当前文档内容和潜在的外部关联，调用
linker工具来添加或验证链接。在这个简单的案例中，我们模拟添加一个通用的"Utilities"链接。 -
工具调用 :
/link.crossref{ input="api_reference.md", links=["utils.md"] } -
模拟
linker输出:json{ "link_log": [ "Added link to utils.md in api_reference.md", "Cross-referenced mymodule.py from api_reference.md" ], "xref": { "utils.md": [ {"source": "api_reference.md", "type": "internal_link"} ], "mymodule.py": [ {"source": "api_reference.md", "type": "mentions_codebase"} ] } } -
Agent 决策: Agent 成功更新了链接和交叉引用。
-
模拟输出:
markdown### Linking/Cross-reference Report Agent successfully linked related documentation and code. **Link Log:** - Added an internal link to `utils.md` in `api_reference.md`. - Cross-referenced `mymodule.py` as the source codebase for `api_reference.md`. **Cross-reference Map (XREF):** ```json { "utils.md": [ { "source": "api_reference.md", "type": "internal_link" } ], "mymodule.py": [ { "source": "api_reference.md", "type": "mentions_codebase" } ] }Next Step: Proceed to review and summarize changes.
4.2.4 阶段 6/7 模拟输出：Review Digest 和 Audit Log 验证
阶段 6: review_summarize
-
Agent 决策 : Agent 调用
reviewer工具，审查所有已执行的变更。它将检查generate_update_docs阶段的changes列表。 -
工具调用 :
/review.summarize{ input="api_reference.md", changes=[{"item": "api_reference.md", "type": "api_guide", "change": "added new section for divide_numbers"}] } -
模拟
reviewer输出 :json{ "summary": "Review of changes for api_reference.md:\n- api_reference.md: added new section for divide_numbers\n- Confirmed 'divide_numbers' is now present in API reference.", "flagged": [] } -
Agent 决策: 审查结果表明，所有预期更改都已完成，并且没有发现新的问题。
-
模拟输出 :
markdown### Review/Summarize Report Agent completed the review of all documentation changes. **Summary Digest:** The `api_reference.md` has been successfully updated to include documentation for the `divide_numbers` function. The new section covers its parameters, return value, and exceptions. The Agent has confirmed the presence and correctness of this new section. **Review Table:** | Change Item | Status | Flagged Issues | |-------------------|-------------|----------------| | `api_reference.md` | Reviewed | - | **Flagged Gaps/Issues:** None. The documentation drift has been successfully resolved. Next Step: Proceed to audit logging to finalize the process.
阶段 7: audit_logging
-
Agent 决策 : 这是 Agent 循环的最后一步。它将收集所有阶段的日志、变更和输入参数，调用
audit_logger工具来生成最终的审计记录和版本信息。 -
工具调用 :
/log.audit{ phase_logs=[...], args={"input": "mymodule.py", "goal": "update", "type": "api", "context": "api_reference.md"} }(这里的phase_logs是一个包含所有前六个阶段输出的列表，为简洁起见，此处省略了其具体内容) -
模拟
audit_logger输出 :json{ "audit_log_entry": { "timestamp": "2025-07-11T10:30:00.000Z", "agent_args": { "input": "mymodule.py", "goal": "update", "type": "api", "context": "api_reference.md" }, "phase_logs": [ // ... (simplified for brevity, actual logs would be much larger) {"phase": "context_goal_parsing", "output": {...}}, {"phase": "scan_analyze", "output": {"coverage": "...", "scan_log": "...", "flagged_gaps": [...]}}, {"phase": "generate_update_docs", "output": {"docs": "...", "changes": [...]}}, {"phase": "structure_mapping", "output": {"toc": "...", "structure": "..."}}, {"phase": "linking_crossref", "output": {"link_log": "...", "xref": "..."}}, {"phase": "review_summarize", "output": {"summary": "...", "flagged": []}} ], "version": "v2.0.20250711" }, "version": "v2.0.20250711" } -
Agent 决策: 审计日志已生成并记录所有操作。
-
模拟输出 :
markdown### Audit Log and Final Summary The `/doc.agent` has completed its execution cycle. **Documentation Summary:** The API documentation for `mymodule.py` has been successfully synchronized with the codebase. The `divide_numbers` function, previously undocumented in `api_reference.md`, has now been fully documented, resolving the identified documentation drift. The updated document includes a new section detailing its purpose, parameters, return value, and exceptions. Internal linking was also updated. **Audit/Version Log Entry (Simplified):** | Phase | Change/Action | Rationale | Timestamp | Version | |-----------------------|-----------------------------------------------------|-------------------------------|---------------------|---------------| | `context_goal_parsing`| Parsed command for API doc update. | User request | 2025-07-11 10:20:00Z | v2.0.20250711 | | `scan_analyze` | Identified doc drift: `divide_numbers` missing. | Code vs. doc comparison | 2025-07-11 10:21:05Z | v2.0.20250711 | | `generate_update_docs`| Added `divide_numbers` section to `api_reference.md`. | Resolve drift | 2025-07-11 10:23:10Z | v2.0.20250711 | | `structure_mapping` | Updated TOC and structure for `api_reference.md`. | Doc content change | 2025-07-11 10:24:15Z | v2.0.20250711 | | `linking_crossref` | Added `utils.md` link, cross-referenced `mymodule.py`.| Enhance navigability | 2025-07-11 10:25:20Z | v2.0.20250711 | | `review_summarize` | Confirmed resolution of `divide_numbers` drift. | Self-verification | 2025-07-11 10:26:30Z | v2.0.20250711 | | `audit_logging` | Finalized audit record and version checkpoint. | Process completion | 2025-07-11 10:27:00Z | v2.0.20250711 | **Flagged Gaps / Remaining Concerns:** None. **Suggested Next Steps:** 1. Commit the updated `api_reference.md` to version control. 2. Integrate `/doc.agent` into CI/CD pipeline to automate drift detection. 3. Consider expanding `[tools]` to include external validation tools (e.g., Markdown linters).
至此，/doc.agent 成功地完成了其任务，检测并纠正了API文档的漂移，并提供了完整的操作日志。
Part V: Advanced Topics: Recursion, Auditing, and Future State
本部分将深入探讨DADP的两个关键高级特性：[recursion] 块定义的自修正能力，以及审计日志的深层价值。最后，我们将展望DADP在未来软件工程中的集成和发展潜力。
5.0 递归与自修正机制 ([recursion])
[recursion] 块是DADP的"智能决策中心"，它允许Agent在检测到问题时进行自我修正，而不是简单地失败。这使得Agent系统能够从错误中学习并提高其韧性。
python
[recursion]
def doc_agent_cycle(context, state=None, audit_log=None, depth=0, max_depth=4):
if state is None: state = {}
if audit_log is None: audit_log = []
for phase in [
'context_goal_parsing', 'scan_analyze', 'generate_update_docs',
'structure_mapping', 'linking_crossref', 'review_summarize'
]:
state[phase] = run_phase(phase, context, state) # run_phase would use the tools
if depth < max_depth and needs_revision(state):
revised_context, reason = query_for_revision(context, state)
audit_log.append({'revision': phase, 'reason': reason, 'timestamp': get_time()})
return doc_agent_cycle(revised_context, state, audit_log, depth + 1, max_depth)
else:
state['audit_log'] = audit_log
return state5.1 递归逻辑分析：doc_agent_cycle 的深度控制和回溯条件
doc_agent_cycle 函数定义了Agent的主循环逻辑：
depth和max_depth: 引入了递归深度控制。max_depth（默认为4）限制了Agent可以尝试自我修正的次数。这对于防止无限循环和管理计算资源至关重要。run_phase(phase, context, state): 这是一个抽象函数，代表了执行单个阶段的逻辑。在实际实现中，它会根据当前阶段的指令和可用工具来调用相应的工具（例如，在scan_analyze阶段调用code_scanner）。needs_revision(state):- 作用 : 这是递归机制的核心判断条件。它会检查Agent当前的
state（即所有已完成阶段的输出和结果）是否满足任务要求，或者是否发现了需要修正的重大问题。 - 实现 : 在
review_summarize阶段标记的flagged列表，或者在audit_logging阶段识别的flagged_issues，都可以作为needs_revision的输入。例如，如果flagged列表中有severity: "High"的问题，则needs_revision可能返回True。 - 例子 : 在上述案例中，如果
reviewer工具在发现divide_numbers缺失后，doc_writer仍然未能正确添加该部分，那么needs_revision就会被触发。
- 作用 : 这是递归机制的核心判断条件。它会检查Agent当前的
query_for_revision(context, state):- 作用 : 当需要修正时，此函数根据当前状态和已发现的问题，智能地生成一个"修订后的上下文"（
revised_context）。这个新的上下文将指导下一轮的Agent循环。 - 实现 : 这通常涉及LLM的再次调用，LLM分析
state中的问题报告，并生成新的goal、constraints或special_instructions，以便在下一次循环中解决这些问题。 - 例子 : 如果
divide_numbers的文档仍然缺失，revised_context可能会包含更具体的指令，例如"Ensure thedivide_numbersfunction inmymodule.pyis accurately and fully documented inapi_reference.md, paying close attention to argument types and error handling."
- 作用 : 当需要修正时，此函数根据当前状态和已发现的问题，智能地生成一个"修订后的上下文"（
- 审计跟踪 : 每次递归修正都会在
audit_log中添加一条记录，详细说明修正的原因和时间戳，确保整个自修正过程也是可审计的。
这种递归设计使得DADP不仅仅是执行任务，而是能够自我学习、自我纠正，显著提高了文档自动化的可靠性和自主性。
5.2 审计日志 ([audit_log]) 的核心价值：可追溯性和合规性
audit_log: true 是 [meta] 中一个看似简单但极其强大的声明，它强调了DADP的核心原则之一：所有Agent行为都必须是可追溯和可解释的。
审计日志的深层价值:
-
可追溯性 (Traceability):
- 每一次Agent的决策、工具调用、输入解析和输出生成都被记录下来。如果文档出现了问题，可以迅速回溯到Agent执行的哪个阶段、哪个工具调用出了错，或者原始输入是否存在缺陷。
- 这对于调试Agent本身、验证文档变更来源以及理解为何生成特定内容至关重要。
-
合规性 (Compliance):
- 在受监管的行业（如金融、医疗），任何系统性的内容生成和发布都需要经过严格的审计。DADP的审计日志为满足这些合规性要求提供了基础，证明文档是根据既定协议和可验证的流程生成的。
- 它可以作为变更控制记录的一部分，与Git提交历史并行，为文档变更提供更细粒度的AI Agent端视角。
-
信任与透明度 (Trust & Transparency):
- 通过清晰的审计日志，用户可以相信Agent的运作是透明的。他们可以看到Agent何时做了什么，以及为什么做。这有助于建立用户对自动化系统的信任。
- 对于 Agent 本身而言，审计日志是其"记忆"和"自我反思"的基础。
-
学习与改进 (Learning & Improvement):
- 审计日志是Agent行为模式的宝贵数据集。分析这些日志可以发现Agent在哪些方面表现良好，哪些方面需要改进（例如，某个工具经常失败，或者某个阶段的输出经常触发递归修正）。
- 这些洞察可以用于优化Prompt设计、改进工具实现或调整 Agent 的工作流。
-
安全 (Security):
- 审计日志可以帮助检测异常行为。如果Agent在未经授权的阶段调用了工具，或者尝试访问不应访问的文件，审计日志会记录这些事件，从而触发警报。
5.3 扩展性设计：多模态输出和持续集成 (CI) 集成
DADP不仅设计用于当前，也面向未来。其模块化和协议化的设计使其在两个关键领域具有强大的扩展潜力：
-
多模态输出的演进 (
prompt_style: "multimodal-markdown"):- 当前的
multimodal-markdown已经支持文本、表格和代码块。未来，随着LLM和多模态AI技术的发展，/doc.agent可以直接生成和嵌入更复杂的视觉元素。 - 集成图表生成工具 : Agent可以通过
[tools]块调用专门的图表生成服务（如Mermaid JS、PlantUML、Graphviz）。例如，在structure_mapping阶段生成一个可视化的文档依赖图，或者在review_summarize阶段生成一个展示代码覆盖率变化的柱状图。 - 动态媒体嵌入: Agent甚至可以根据上下文，建议或生成短视频链接、GIF动画来解释复杂的操作流程。
- 当前的
-
深度持续集成 (CI) 集成:
- 将
/doc.agent嵌入到CI/CD流水线中是实现"living KBs"（活知识库）和自动化文档漂移检测的终极目标。 - Git Hook 触发 : 每次代码提交（
git push）或合并请求（Pull Request）都可以触发/doc.agent的运行。- 前置检查 (Pre-commit/Pre-push) : 在代码提交前，Agent可以作为Git Hook运行
scan_analyze阶段，检查新代码的docstring覆盖率，并拒绝未达标的提交。 - CI/CD 自动文档更新 : 在主分支合并后，CI管道可以触发
/doc.agent运行一个完整的文档更新周期。如果检测到漂移，Agent会自动生成修订，并作为新的提交推送到文档库，或者在Pull Request中建议更改。 - 警报与通知 :
audit_logging阶段可以与Slack、Jira、邮件等通知系统集成，在Agent发现严重文档问题或完成重要更新时通知团队。
- 前置检查 (Pre-commit/Pre-push) : 在代码提交前，Agent可以作为Git Hook运行
- 微服务架构集成 :
[tools]中定义的call: { protocol: /code.scan{...} }模式暗示了Agent可以通过标准的RPC或HTTP调用与微服务通信。这意味着文档Agent可以成为微服务生态系统中的一个普通服务。
- 将
(Image: Enhanced CI/CD Pipeline Diagram with /doc.agent)
Example Diagram Sketch for Enhanced CI/CD Integration:
Phase 1: Context/Goal Phase 2: Scan/Analyze Doc Drift Detected Phase 3: Generate/Update Phase 4-6: Structure, Link, Review Phase 7: Audit/Log If Issues Flagged & Max Depth Not Reached No Issues / Max Depth Reached Alerts/Notifications Code Commit/PR Merge CI/CD Pipeline Run /doc.agent Agent Logic Code Scanner Doc Writer Structure Mapper, Linker, Reviewer Audit Logger Generate Report/Commit Docs Deployment/Publishing Slack/Jira/Email
Caption: /doc.agent 集成到 CI/CD 流水线中，实现文档的持续自动化、自修正和审计。
5.4 结论：DADP在未来软件工程中的定位
/doc.agent System Prompt 所体现的 DADP 是一种前瞻性的设计，它将Agentic Prompt Engineering推向了一个新的高度。它不仅仅是一个简单的指令，更是一个完整的自治协议，为构建高可靠、可审计、自修正的智能文档系统提供了蓝图。
DADP的核心价值在于：
- 提升文档质量和一致性: 通过自动化检测和纠正文档漂移，确保文档始终与最新代码保持同步。
- 解放开发者生产力: 将繁琐的文档维护工作自动化，让开发者可以专注于核心代码开发。
- 增强团队协作: 提供清晰的审计日志和多角色支持，促进团队对文档变更的理解和信任。
- 构建"活"的知识库: 将文档视为代码库的活生生的延伸，而非静态的负担。
随着 Agentic Systems 和 LLMs 技术的不断成熟，DADP 这样的协议将成为未来软件工程基础设施的不可或缺的一部分。它预示着一个时代：文档不再是开发流程的滞后产物，而是由智能Agent主动管理、持续演进的战略资产。采纳并扩展DADP，将是任何希望在AI时代保持竞争力的组织的关键一步。