docs: self-host the star history chart from real stargazer data

[FenjuFu]

Summary

The Star History chart embedded in the READMEs currently renders an error image, not a chart. As of 2026-06-30 GitHub restricted the stargazer-timestamp API to a repository's admins/collaborators, so api.star-history.com can no longer read this repo's star dates and returns a "GitHub restricted access to star data" placeholder.

This PR fixes the chart by self-hosting it instead of depending on an external service:

• Adds docs/star-history.svg, generated from this repository's real stargazer history (cumulative stars over time, 8,963★ at time of writing).
• Points the English, Chinese, and Japanese READMEs at that file via repo-relative paths (docs/star-history.svg, star-history.svg, ../star-history.svg respectively) so each renders correctly from its own location.

Why self-host rather than swap to another chart service

Keeping the image under the project's own control avoids handing README rendering to a third-party host the maintainers haven't vetted — the SVG is plain, versioned, and served from this repo. It also renders in contexts where GitHub's image proxy doesn't apply (mirrors, package pages, IDEs).

Notes

• The SVG is a point-in-time snapshot. If you'd like it to stay current, I'm happy to follow up with a small scheduled GitHub Actions workflow that regenerates it (it reads the stargazer timestamps, which a repo-scoped GITHUB_TOKEN in Actions is allowed to do).
• Only the four <img src> lines changed in the READMEs; no other content (including the osai-verify marker) was touched.---

Update: now self-refreshing

This PR also adds .github/workflows/star-history.yml (monthly + manual workflow_dispatch) and .github/scripts/gen-star-history.mjs, so the chart stays current without manual work:

• The generator uses Node built-ins only (no dependencies) and reads the repo's real stargazer timestamps via the workflow's GITHUB_TOKEN. It fails closed — if the token can't read dated stars, it errors and leaves the committed SVG untouched, so a permission problem never commits a broken chart.
• The workflow commits only when the chart actually changes, with a DCO sign-off from github-actions[bot].
• Note: this step pushes to the default branch. If that branch is protected against the Actions bot, either allow it or set a STAR_HISTORY_TOKEN PAT secret (the workflow already prefers it when present). Happy to switch it to a PR-opening flow instead if you'd rather review each refresh.

[lyj715824]

审查结论：Request changes

这个 PR 的目标是把 README 中的 api.star-history.com 外链替换为仓库内的 docs/star-history.svg，并通过每月 GitHub Actions 重新生成图表。方向可以理解，但当前版本有几处会让“自动刷新/文档发布”链路失效的问题：

1. VitePress 构建会直接失败（P1）
   docs/README.md:126 使用了裸路径 star-history.svg。我在 PR head 的 clean worktree 执行 cd docs && npm install && DOCS_BASE=/astron-agent npm run docs:build，得到：
   Rollup failed to resolve import "star-history.svg" from "docs/README.md"。这里应使用 ./star-history.svg。仓库的 deploy-pages.yml 会在 docs/** 变更时执行同一个构建，因此合并后文档站发布会被阻断。

2. PAT fallback 没有覆盖 git push（P1）
   .github/workflows/star-history.yml:19 的 checkout 使用默认 github.token，并持久化了 git 凭据；:28 的 STAR_HISTORY_TOKEN 只传给 Node 脚本的 API 请求，:40 的裸 git push 仍会使用 checkout 写入的 GITHUB_TOKEN。因此即使配置 PAT 解决了 stargazer API 读取，推送仍可能被当前 main 分支保护规则拒绝。若要直推，需要让 checkout/push 使用同一个具备相应权限的 PAT/App token；更稳妥的是创建 PR。

3. 即使 push 成功，Pages 也不会因该 push 自动重建（P1）
   GitHub 不会为由 GITHUB_TOKEN 触发的 push 再启动其他 workflow，而 deploy-pages.yml 只监听 push(main/master, docs/**)。所以月度提交可能更新仓库文件，却不会更新文档站。需要使用 PAT/App token 推送，或显式 dispatch Pages workflow。

4. 默认 token 的 stargazer 读取能力需要实际验证（P1）
   GitHub 已对 stargazers 列表接口实施 admin/collaborator 限制。PR 中假设 repo-scoped GITHUB_TOKEN 一定能读取带 starred_at 的列表，但这个新 workflow 没有在 PR CI 中运行，也没有提供实测证据；在同一政策下已有 Actions installation token 返回 403、PAT 返回 200 的案例。没有 STAR_HISTORY_TOKEN 时，当前脚本很可能每月失败并保留旧图。

5. 生成的并不是稳定的历史累计曲线（P1/P2）
   .github/scripts/gen-star-history.mjs:82-95 用当前仍在 star 的用户列表序号作为历史累计值。用户取消 star 后会从列表消失，下一次重生成会把过去所有点整体下移；重新 star 也会改变时间。这样会回写历史，不能称为真实 cumulative star history。建议保存每月的 stargazers_count 快照并基于快照绘图，或明确文案这是当前 stargazer 的时间分布近似。

建议先修正 ./star-history.svg 并加入 docs build 检查；自动刷新部分在明确 token、分支保护、Pages 触发和历史数据模型后再合入。

[FenjuFu]

Addressed all five review points in e2948e9 (after merging current main):

1. docs/README.md now uses ./star-history.svg; DOCS_BASE=/astron-agent npm run docs:build passes locally.
2. The monthly job no longer pushes protected main. It uses the same STAR_HISTORY_TOKEN for checkout, branch push, and gh pr create.
3. The generated change lands through a normal PR, so a maintainer merge triggers the existing Pages workflow.
4. The generator no longer calls the restricted dated-stargazer endpoint at all. It reads the public repository stargazers_count once; local execution recorded 8,902 stars successfully.
5. Historical data is now stored as immutable monthly snapshots in docs/star-history.json; the SVG is rendered from those snapshots, so later unstars/restars do not recompute past points.

Validation: node --check .github/scripts/gen-star-history.mjs, deterministic generator run for 2026-08-28, git diff --check, and the VitePress production build all pass.

Operational note: the STAR_HISTORY_TOKEN secret is not configured yet. Before enabling the monthly refresh, a maintainer must add a PAT with repository contents write and pull-request write access. I did not copy my local CLI token into repository secrets.

[FenjuFu]

CI follow-up: 31 checks completed successfully (including the project matrix, CodeQL, DCO, and CLA). The sole red job is claude-review, which fails before reviewing code: anthropics/claude-code-action@v1 rejects the workflow OIDC token with 401 Unauthorized - Invalid OIDC token; the log also reports the configured model input is no longer valid for that action version. No PR source test failed, so I have not changed product/docs code to mask this workflow-infrastructure error.