文档维护智能体

自动检测陈旧的文档、断开的链接和过时的示例。通过每周扫描和自动 PR 保持文档更新。

文档自然会过时。API 会改变，示例会变成过时的，链接会断开。保持文档与代码同步是一项非常适合自动化的繁琐工作。

一个文档维护智能体按计划运行，审计你的文档，并打开 PR 以在问题让用户困惑前修复它们。

智能体的功能

按照每周的计划（或通过分配按需），文档智能体会：

查找陈旧的文档 — 检测对旧 API、已弃用标志或已删除函数的引用
检查断开的链接 — 爬取内部和外部链接；标记 404
验证示例 — 运行代码片段并确保它们编译/执行
更新 changelog — 将已合并的 PR 标题提取到草稿 changelog
打开 PR — 将结果整合到一个 PR 中，其中包含用于审查的清晰部分

设置

前提条件

具有活跃智能体的 AACWorkflow 工作区
文档仓库（或主仓库中的 docs 文件夹）
安装了 bash、Go 或 Node.js 的智能体运行时

步骤 1：创建文档维护智能体

转到 Settings → Agents 并单击 New Agent
选择你的运行时和提供商
将其命名为 docs-audit 或 doc-keeper
添加这个系统提示：

Role: Documentation auditor
Task: Every week or on-demand:
1. Clone the repository
2. Find all .md and .mdx files
3. Check all links (internal with grep, external with curl)
4. Find code snippets and validate syntax
5. Look for TODOs, deprecated markers, or version mismatch
6. Summarize findings in a changelog-style report
7. Create a GitHub branch "docs/maintenance-<date>"
8. Open a PR with all findings grouped by category
9. Link the PR to workspace as "docs-audit"

Output format:
## Stale References
- api/v1/GetIssue() → moved to /v2/GetIssue
- Example in quickstart.md lines 45–50 uses old syntax

## Broken Links
- Internal: docs/guides/auth.mdx → "see [Setup Guide](/setup)" (guide removed)
- External: 3 links to archived.example.com (404)

## Code Examples
- JavaScript example in index.mdx fails to parse (syntax error line 12)

## Changelog
Merged PRs since last scan:
- feat: add workspace invites
- fix: pagination token bug
- docs: update API docs

步骤 2：计划智能体

在 AACWorkflow 中，转到 Settings → Automations 并创建计划任务：

Trigger: 每周（例如，星期一上午 9 点）
Task: 分配给 docs-audit 智能体
Template: docs-maintenance

或在你自己的基础设施中使用 cron 任务：

# 每个星期一上午 9 点运行文档审计
0 9 * * 1 curl -X POST https://aacworkflow.com/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent_id": "docs-audit", "title": "Weekly docs audit"}'

步骤 3：配置仓库访问

向你的仓库添加 .aacworkflow/config.yml：

docs_audit:
  paths:
    - "docs/"
    - "README.md"
    - "CHANGELOG.md"
  exclude:
    - "docs/archived/"
    - "node_modules/"
  checks:
    - link-validation
    - code-snippet-syntax
    - version-references
    - deprecated-markers

示例 PR 输出

Title: docs: maintenance audit for 2025-06-22

Body:

## Stale References (3 items)
- Line 87 in docs/agent-setup.md: "Runtime v2" → should be "Runtime v3"
- docs/api/endpoints.md: Old Swagger URL → update to OpenAPI v3.1
- Quickstart: "Deploy to Heroku" section → remove (service EOL)

## Broken Links (7 items)
- docs/guides/docker.mdx: line 23 → /install/docker-compose (moved to /docker)
- External: https://old-api-docs.example.com → 404

## Code Examples (2 updated)
- Python snippet in examples/webhook.md uses old v1 client → fixed
- Go example missing error handling → added

## Changelog Fragment
### Merged since 2025-06-15
- feat(api): add workspace export endpoint
- fix: typo in API error messages
- docs: expand rate limiting guide

---
Review and merge to publish. Auto-close stale branches after merge.

提示和最佳实践

快速合并。 文档 PR 应该是低摩擦的。在一小时内审查，合并，发布。智能体可以每周运行而不受阻碍。

Changelog 自动化 — 将已合并的 PR 标题提取到 ## Unreleased 部分，这样你就有了发布说明的开端
示例验证 — 使用 Docker 容器验证跨语言的代码示例，无需在本地安装所有内容
外部链接超时 — 为外部链接检查设置 5 秒超时，避免挂起
排除模式 — 将存档的文档保持在审计之外（添加到 .aacworkflow/config.yml）
批准门 — 在自动合并文档 PR 前需要至少一个人工批准