开发环境配置

本页说明 tiangong-lca-next-docs 的本地开发环境，以及它与产品仓 ../tiangong-lca-next 之间的 Node 基线关系。

如果您这次修改还涉及文档与产品行为对齐，请继续阅读 Docs / Product 同步指南。

Node 基线

当前有两层基线需要区分：

Docs 站点仓：package.json 当前声明 node >=18.0
产品仓 ../tiangong-lca-next：工程基线当前是 Node 24

安装依赖

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

nvm install 24
nvm alias default 24
nvm use 24

npm install --no-package-lock

仓库当前不提交 package lock，因此干净 checkout 不能使用 npm ci。除非另一个依赖治理变更明确引入 lockfile，本地安装请保持不生成 lockfile。

常用命令

本地调试

npm run start

本地站点默认运行在 http://localhost:3000/。

Markdown 检查

npm run lint

生成和检查 AI 文档索引

npm run docs:llms
npm run docs:llms:check

docs:llms 会从公开 Docusaurus 文档生成 static/llms.txt。docs:llms:check 用于确认已提交的索引与当前公开文档内容一致。

检查公开发布范围

npm run docs:publication-scope:check

该命令会检查 static/llms.txt、sidebars.ts、context7.json 以及存在时的 build/llms.txt，防止内部 agent 文档、TODO、计划、事故记录或治理执行材料进入公开 AI 消费范围。

检查 docs-impact 截图证据

npm run docs:screenshots:test
npm run docs:screenshots:check
npm run docs:screenshots:check -- \
  --manifest /tmp/docs-impact-visual-result.json \
  --diff-file /tmp/docs-impact-visual.name-status

docs:screenshots:test 运行截图合同回归测试。docs:screenshots:check 在没有 manifest 时会确认所选 diff 不包含文档截图变更；存在新增、替换或复用证据时，应传入本地 visual result 和完整 name-status diff。校验覆盖中英文页面本地资产、引用与 alt、各语言页面的邻近说明、 144 DPI、hash、比例及 action 对应的 diff 状态。权限受阻的 Draft 例外仍由 workspace validate-visual-evidence.rb 复核本地 0600 access report。

自动修复可修复的 Markdown 问题

npm run lint:fix

TypeScript 检查

npm run typecheck

生产构建

npm run build

npm run build 会先通过 prebuild 自动执行 npm run docs:llms，确保托管平台只调用标准构建命令时，发布产物中的 llms.txt 也会写入当前构建 commit。

本地预览构建产物

npm run serve

生成翻译骨架

npm run write-translations -- --locale en

修改文档时的最小校验

涉及公开文档内容变更时，至少建议执行：

npm run lint
npm run docs:screenshots:check
npm run docs:llms:check
npm run docs:publication-scope:check
npm run build

如果这次修改影响了导航、侧边栏、链接结构或中英文镜像，也建议一并检查：

docs/intro.md
docs/user-guide/overview.md
sidebars.ts

发布说明

仓库中的 .github/workflows/publish-docs.yml 会在 main 收到 push 后自动执行发布闭环：

生成并检查 static/llms.txt
运行公开范围检查
执行 lint、typecheck、Docusaurus build
部署 Cloudflare Pages
验证公开站点的 /llms.txt
刷新 Context7，或在缺少 secret / refresh 失败时留下可见 follow-up

仓库仍保留 .github/workflows/build.yml 的 tag 发布流程，适合版本式 release。创建符合 v* 规则的标签并推送后，即可触发该流程。

git tag
git tag v0.0.1
git push origin v0.0.1

Cloudflare Pages 相关自动部署仍依赖仓库环境中的：

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID
CONTEXT7_API_KEY（用于自动刷新 Context7；缺失时 workflow 会保留 pending follow-up）

可选仓库变量：

CONTEXT7_LIBRARY_NAME（默认使用 /${{ github.repository }} 形式的 Context7 library id）

Node 基线​

推荐做法​

安装依赖​

常用命令​

本地调试​

Markdown 检查​

生成和检查 AI 文档索引​

检查公开发布范围​

检查 docs-impact 截图证据​

自动修复可修复的 Markdown 问题​

TypeScript 检查​

生产构建​

本地预览构建产物​

生成翻译骨架​

修改文档时的最小校验​

发布说明​