内容生产与发布流程

生成文章

调用项目内 .agents/skills/github-guide-author/，输入 GitHub URL、owner/repo 或项目名称。默认生成 Markdown、证据清单、分析范围和配图提示词，不生成真实图片或 HTML。

也可以先运行仓库侦察命令建立确定性的研究起点：

npm run repo:analyze -- --repo https://github.com/owner/repo

命令读取公开 GitHub API 的仓库元数据、默认分支最新提交、README 和 Git tree，输出到 articles/inbox/owner--repo/。它不执行仓库代码；生成的文章是带明确未知项的 draft，必须继续使用 Skill 选择源码范围、补充调用链和验证证据。读取私有仓库时使用临时的最小权限只读 GITHUB_TOKEN，不得将 token 写入文件或日志。

已有同名草稿时命令默认拒绝覆盖；只有确认人工修改可以丢弃后才使用 --force 刷新。

建议输出目录：

output/{owner}--{repo}/
├── article.md
├── analysis-manifest.yaml
├── evidence.json
├── metadata.json
├── structure.txt
└── assets/
    ├── prompts/
    └── images/

确认文章可以进入发布流水线后，把整个输出目录放到 articles/inbox/{owner}--{repo}/。inbox 是草稿区，不会被 VitePress 收录；文章与 assets/prompts/ 保持相对路径关系。

校验与 promote

npm run content:check
npm run content:promote -- --file articles/inbox/owner--repository/article.md --approve

--approve 只表示用户确认把当前文章提升到本地公开目录，不表示允许 push 或远端部署。脚本会再次校验文章，写入 docs/guides/，重建 catalog，并运行索引一致性检查。

可选 GitHub Actions

.github/workflows/analyze-repository.yml.example 提供手动触发的共享入口。启用后，Actions 使用 GITHUB_TOKEN 做受限读取，运行 repo:analyze，校验草稿并上传 artifact。它不会自动写入 docs/guides/、创建 PR、推送或部署；下载 artifact 后仍需本地 Skill 深度分析、人工审阅和显式 --approve。

完整启用和权限说明见 GitHub Actions 自动化分析。

公开文章至少需要以下 frontmatter：

---
title: "项目标题"
summary: "用于目录展示的一句话项目判断"
slug: owner-repository
repository: owner/repository
repository_url: https://github.com/owner/repository
source_commit: 40-character-commit-sha
project_type: cli
status: published
visibility: public
created: 2026-08-28
updated: 2026-08-28
analyzed_at: 2026-08-28
freshness_status: fresh
verification: source-confirmed
license: MIT
tags:
  - CLI
  - Developer Tools
---

本地开发与发布门

npm run docs:dev
npm run check
npm run docs:preview
npm run pages:dev

公开前确认 source commit、许可证、命令和引用；不得混写证据状态，不得包含私有源码、密钥、内部地址、未解决占位符或伪造截图。配图标签引用的 prompt/image 文件必须存在。远端 push、Cloudflare Pages 发布和 GitHub Pages 启用分别确认。