theoju/engineering-docs-agent

# engineering-docs-agent 一个 Claude Code 插件：夜间的文档 PR 生成器，包含发布验证和分层内容 lint。 ## 功能 - 监控宿主仓库的 Git/PRs/Jira，获取自上次成功运行以来的更改。 - 针对宿主的文档站点发起一个 PR，包含： - 总结更改的 **What's New** 条目。 - 由 `page-author` 子代理使用 voice few-shot 编写的 **更新/新页面**。 - 针对没有 spec/plan 的非琐碎 PR 提供的 **Gap flags**。 - 发送 Slack + 电子邮件摘要。 - 在 PR 合并后，验证宿主的构建 pipeline 是否成功以及页面是否已上线。 ## 安装 1. `claude plugin marketplace add ` — 从本地路径或远程 URL 注册 marketplace。 2. `claude plugin install engineering-docs-agent@engineering-docs-agent-marketplace` — 安装插件。 3. `claude /engineering-docs-agent-setup` — 从宿主仓库的根目录运行 setup skill。 有关全面的操作指南（GitHub App 注册、所有仓库 secrets、分支保护、验证、每种语言的宿主说明、针对每种 partial-mode 失败的故障排除），请参阅 [docs/site-src/setup-guide.md](docs/site-src/setup-guide.md)。相同的内容也会发布在文档站点的 `setup-guide.html` 上。 ## 自托管 (dogfood) 此仓库配置为针对自身运行代理 —— 为新宿主仓库提供的参考布局： 1. `.engineering-docs-agent/config.yml` — 宿主配置（框架、路径、Jira 项目键、voice 样本、发布目标）。 2. `.engineering-docs-agent/state.json` — 提交的状态。`last_successful_run.head_sha` 是下一次夜间运行窗口的事实来源。每个合并的 `docs-agent/YYYY-MM-DD` PR 都通过正常的 git merge 推进它 —— 没有单独的 promote workflow。 3. `.engineering-docs-agent/state.example.json` — 用于全新宿主仓库的种子模板。此 dogfood 宿主已经拥有真实的 `state.json`；该示例文件是为安装到新仓库的插件用户保留的。 4. `.engineering-docs-agent/current_run.json` — 被 gitignore 的临时运行状态，每次状态更新时都会写入，用于诊断和测试可观测性。不是 docs-agent PR 的一部分。 5. `docs/site-src/` — 代理可编辑区域和 MkDocs 源目录；`agent_editable_paths` glob (`docs/site-src/**`) 限制在此处的写入，并且同一棵树会发布到 GitHub Pages。 针对此宿主在本地运行代理： ``` python3 scripts/orchestrator_runner.py --repo-root . --no-pr ``` 要获取每个子代理的原始 stdout 诊断信息，请在调用前设置 `DOCS_AGENT_DEBUG_DIR=/tmp/cce-debug`。 ### 夜间编写运行 主要的编写 pipeline（不带子命令的 `scripts/orchestrator_runner.py`）每天 07:00 UTC 通过 `.github/workflows/docs-agent-nightly.yml` 自动运行一次。该 workflow 会打开或附加提交到一个 `docs-agent/YYYY-MM-DD` PR；根据规范第 8 节，partial run 仍然会打开并在 body 中包含 `partial: true` 的 PR，以便使操作差距可见，而不是静默的。 要手动触发它： ``` gh workflow run docs-agent-nightly.yml -f reason="" gh run watch ``` `reason` 输入是一个自由文本标签，会与运行后的 `state.json` 快照一起显示在运行摘要中。身份验证通过 `CLAUDE_CODE_OAUTH_TOKEN` 仓库 secret 进行（与 `release.yml` 的 secret 相同）。每个仓库一次只能运行一个 —— 并发调用会排队，而不是在同一个 docs-agent 分支上竞争。 ### 从本地 clone 安装 如果您正在通过此仓库的检出进行工作（例如，在发布前测试更改），请注册本地 marketplace 并安装插件： ``` claude plugin marketplace add /path/to/engineering-docs-agent claude plugin install engineering-docs-agent@engineering-docs-agent-marketplace ``` 这使得这八个代理无需 `--plugin-dir` 变通方法即可解析。marketplace 注册会读取 `.claude-plugin/marketplace.json`；插件清单位于 `.claude-plugin/plugin.json`。 ### Lens 路径和可编辑路径 代理从 **lens 路径**读取并写入**可编辑路径**。它们有重叠，但却是不同的： - `docs.lens_paths` 定义了_每个 lens 的文档所在位置_（例如，`core: docs/site-src/`）。voice-load、gap-detection 和 PR-summarization 阶段会从这些路径读取。 - `docs.agent_editable_paths` 定义了_代理可以写入的位置_。Orchestrator 的 runtime filter 会拒绝任何不在这些 globs 之内的建议页面。 **不变式：** 每个 `lens_paths` 条目都必须至少被一个 `agent_editable_paths` glob 覆盖。Config loader 会在启动时通过 `scripts/state_io.py` 中的 `_validate_lens_paths_are_editable` 强制执行此操作。一个没有匹配可编辑 glob 的 lens 意味着代理读取了它永远无法更新的文档 —— 这通常是一个错误。 可编辑的 glob 可以比 lens 路径**更窄** —— 例如，一个 lens `core: docs/` 配对可编辑的 `docs/generated/**` 是有效的：代理读取 `docs/` 下的所有内容，但只写入 `generated/` 子路径。验证器接受这一点，因为可编辑 glob 的锚点 (`docs/generated/`) 以 lens 路径 (`docs/`) 开头。兼容性规则是双向的：glob 锚点和 lens 路径必须共享一个路径分支。此仓库的 dogfood 配置将两者放在同一位置：lens `docs/site-src/` 配对可编辑的 `docs/site-src/**`。 ### Jira 丰富 (可选) 如果您的宿主配置设置了 `sources.jira.enabled: true` 并且您希望 source-collector 子代理获取链接的 issue 摘要，请在调用 orchestrator 的 shell 中设置两个环境变量： ``` export JIRA_EMAIL="your.email@example.com" export JIRA_API_TOKEN="…" # token from https://id.atlassian.com/manage-profile/security/api-tokens ``` `JIRA_API_TOKEN` 是 Atlassian Cloud API token（不是您的密码）。该 token 通过 TLS 使用 HTTP basic-auth 发送到 Jira REST API。 `dispatch_subagent` 已经将完整的父环境传递到 subprocess 中，因此任何继承的 `JIRA_*` 变量都可以到达代理，而无需 额外的连接配置。 如果没有这些环境变量，orchestrator 将继续运行；source-collector 输出中的 `jira_issues` 将是 `[]`，并且运行将被标记为 `partial: true` 以及 `error: "jira_auth_missing"`，以便在 `.engineering-docs-agent/state.json` 的 partial_reasons 和 Slack/电子邮件通知中使操作差距可见。有关代理端的契约，请参阅 `agents/source-collector.md` 第 5 步 + Forbidden outputs 第 6 节。 ## 实时集成测试 默认的 `pytest` 运行是完全模拟的 —— 没有网络，没有 LLM，没有成本。一个单独的 `@pytest.mark.live` 门控涵盖了真实的 LLM 调度路径： ``` pytest -m live -v ``` 这些测试调用真实的 `claude` CLI，每次完整通过的成本约为 **$1-3**（每个测试约 $0.10-$0.50）。它们需要安装并验证过（OAuth 或 `ANTHROPIC_API_KEY`）的 `claude` CLI、网络访问权限和 API 配额。默认情况下会跳过实时测试（一个 `conftest.py` hook）；使用 `-m live` 选择加入。CI 仅在 tag 推送时运行它们 (`.github/workflows/release.yml`)，从不在每个 PR 上运行。 涵盖范围：每种 payload 形状进行一次 `dispatch_subagent` 调用（带有摘要的 notifier，带有 PR 元数据的 pr-summarizer）。调度路径是被测系统 —— CCE-2 和 CCE-3 修复的那类连接错误正是这些测试要捕获的。 ## 架构 请参阅 [设计规范](docs/superpowers/specs/2026-05-19-engineering-docs-agent-design.md)。 ## Lint 规则 位于 `scripts/lint/` 中的独立脚本。宿主可以在自己的 CI 中对人工编写的 PR 运行它们： ``` python scripts/lint/lint_runner.py --config .engineering-docs-agent/config.yml --paths docs/**/*.md --json ``` ## License MIT。

标签：AI代理, Claude插件, SOC Prime, 安全规则引擎, 开发工具, 开源框架, 持续集成, 文档自动化, 逆向工具