workspace

工作区

管理研究项目的写作和文档工作：按需搭建基础设施、展示渲染结果、保存迭代版本。若要管理研究任务图本身（规划、执行类型化任务），请使用 asta-flows。

assets/DEVELOPER.md 是共享的开发者指南。在项目 README 中链接到所选 asta-plugins ref 下的该文件；不要将通用说明复制到每个项目中。此 SKILL.md 是针对 Agent 的操作流程。

向用户展示渲染结果

向用户提供渲染结果的网页 URL。根据上下文从以下两个来源中选择：

• 本地 Agent（主机、本地开发容器或 Codespace——用户可以访问你的端口）：在后台运行 make preview。提供 Quarto 输出的 URL（在主机或开发容器中为 localhost；在 Codespace 中为 Codespaces 转发的 URL）。
• 无头 Agent（用户无法访问端口）：推送分支（参见 保存），然后运行 make deployed-url，从 GitHub Pages CI 获取已部署的 URL。

当用户想查看与较早版本相比有哪些改动时，提供 asta workspace what-changed <ref>（Git 2.30 或更高版本）。它会在指定 ref 和私有工作树副本中运行项目的 make render，然后复用 PR 预览的差异脚本。它只会发布到 .asta/cache/what-changed/；实时预览可以继续运行。在后台运行 asta workspace preview --what-changed，并向用户提供其端口 4849 的 URL（localhost 或 Codespaces 转发的 URL）。运行中的服务器会自动显示之后的对比结果。无需 PR 或 Pages 部署。由用户自行跟踪上次阅读的版本；建议他们阅读后运行 git tag -f last-read。

选择可信的 ref，并在创建副本期间保持源文件稳定。基线只包含已提交的文件；不要将当前被忽略的输入当作历史数据呈现。每次只运行一个对比。有关构建前提、复制成本、清理和服务限制，请参阅开发者指南。

合并论文更改前

在合并论文 PR，或在允许的情况下直接将论文编辑推送到默认分支之前，检查是否存在带有 asta:overleaf-sync 标签的未关闭 PR。先合并该 PR，这样较新的合作者编辑会在你的更改落地前与你的更改冲突。如果它尚未同步最新内容，请在 Overleaf 令牌可用的环境中运行 asta workspace overleaf sync --wait 1800（可以在后台运行；根据最终的 Sync outcome: 行和退出代码采取行动），然后更新你的分支。编辑论文前，以及合并论文 PR 后，都要以相同方式进行同步。在该 PR 上解决同步冲突并重新运行检查；不要手动推进 .asta/overleaf 配对记录来绕过冲突。 有关安排、受邀合作者的访问权限、锁恢复和仓库状态，请阅读 Overleaf 同步。

保存

git add + git commit -m "<concise message>"。未经用户明确批准，不要执行 git push。

打开任何工作区 PR 前，无论是本地 Agent 还是无头 Agent，都要确保固定版本为最新：

1. 提交工作，运行 make check，并记录检查是否通过。
2. 运行 asta workspace bump-pin；报告错误，并按照任何恢复提示操作。更新固定版本时会打印 Committed <sha>。
3. 如果打印了 SHA，再运行一次 make check。如果之前构建通过、现在失败了，则运行 git revert --no-edit <sha>，继续操作，不更新固定版本。

对于无头 Agent（用户只能通过已部署的 URL 查看结果）：

• 如果仓库为空，先初始化 main。 仓库没有提交时，首次推送的分支会成为默认分支，届时将没有可供创建 PR 的 main。运行 git ls-remote --heads origin main 检查。如果不存在：优先创建带初始提交的仓库（GitHub 的 “Add a README file”，或 gh repo create <owner>/<name> --add-readme），以便一开始就有 main；否则，用 git push -u origin HEAD:main 为其添加初始提交（此操作合理——没有先前状态需要审查）。
• 首次保存：确保固定版本为最新（见上文），然后运行 git push -u origin HEAD:<feature-branch>、gh pr create --fill，再运行 make deployed-url 并报告 URL。
• 后续保存：运行 git push、make deployed-url。
• 获得明确的合并批准后：运行 gh pr merge、make deployed-url。

未经用户明确批准，不要合并 PR。

拒绝 Overleaf 同步

当 asta workspace overleaf pull 或 publish 拒绝操作，或同步 PR 发生冲突时，请按照消息链接的 workflows/overleaf-recovery.md 章节操作。

按需搭建组件

仅在需要时添加组件；不要主动提出。

组件	添加时机
Quarto 构建工具	始终需要——它是项目结构的一部分。
版本工作流存根	管理规则时始终需要；仅在需要时启用 Pages 自动部署。
GitHub Pages 部署	没有用户可访问的端口，或用户要求提供部署 URL 时。
Dev container	用户想避免安装主机依赖，或想从另一台机器通过浏览器访问时。请参阅关于两种流程的小节。

在以下步骤中写入任何文件之前，请检查目标路径是否已存在。如果已存在，请先询问用户是否要覆盖，或将该组件的内容合并到现有文件中。

Quarto 构建工具

1. 将 assets/_quarto.yml 复制到项目根目录；填写 {{TITLE}} 和 {{REPO_URL}} （使用规范的 GitHub URL，例如 https://github.com/{owner}/{repo}）。
2. 创建包含 title: 前置元数据的 index.qmd。
3. 创建空的 references.bib。
4. 将 assets/evidence.yml 复制到项目根目录（用于存放带键名的引文——即使为空也要保留）。每次渲染前，Makefile 都会从此仓库获取 evidence 扩展和 Asta 主题；请继续以托管方式使用二者，而不要复制它们的扩展目录。无论读者的系统设置如何，脚手架都会以深色模式打开，并提供一个始终显示的浅色模式切换按钮。两种模式使用相同的排版和布局，长页面上的章节标题会固定显示。保留项目自身的 theme: 和 CSS；如需自定义，请参阅开发者指南的 站点外观 一节。另请参阅下文的 为论点提供佐证。
5. 将 assets/gitignore 中项目 .gitignore 尚未包含的行追加进去（如果文件不存在，则创建；不要覆盖已有条目）。
6. 将 assets/Makefile.managed 复制为 Makefile。共享规则和脚本会由 asta workspace sync 获取到被忽略的 .asta/cache/ 中；除非用户希望自定义，否则不要创建 scripts/ 或复制辅助文件。项目自有的 workspace.mk 或 scripts/<name> 优先级更高。采用脚手架时，请保留项目现有的目标。
7. 即使仅用于本地项目，也要添加精简的 assets/docs.yml 工作流存根：它会选择托管版本。若仅用于本地，请移除其 on.push 和 on.pull_request 事件，并使用 on.workflow_dispatch，使发布必须手动触发。保留 jobs.docs.uses 行；同步过程会读取它。保留现有的版本策略（@main 测试版、@latest 发布渠道，或固定的发布版本／提交）。不要将其升级或重新固定到其他版本，除非这是无关设置的一部分。
8. 复制 assets/README.md；填写 {{TITLE}}、{{DESCRIPTION}} 和 {{ASTA_PLUGINS_REF}}。在指南链接中使用 .github/workflows/docs.yml 里的 ref。上游 latest 分支会跟踪已发布的指南；如果使用自定义 ref，请验证链接。
9. 运行 asta workspace sync --require-scripts，然后运行 make check。保留自定义副本。删除旧的、未经修改的辅助文件前，先确保刷新成功，并在空缓存环境下验证项目。
10. 若要让论文与 Overleaf 项目保持同步，请遵循 workflows/overleaf-sync.md。

独立的 LaTeX 论文（可选）

仅当用户想直接编写 LaTeX 时才添加此项。Quarto 转 PDF 仍按需运行 quarto render <page>.qmd --to pdf；不要创建或提交生成的 .tex、PDF、HTML 或查看器页面。

1. 将 assets/paper/main.tex 和 assets/paper/latexmkrc 复制到 paper/（或选定的论文目录），保留现有论文源文件和引擎设置。填写 {{TITLE}}，并对 &、%、_、#、$、花括号和反斜杠等 LaTeX 特殊字符进行转义。从论文目录构建时，rc 会向上搜索 references.bib，直到 Git 根目录；随着参考文献逐渐可用，添加引用并取消模板中参考文献行的注释。空项目构建时不会生成参考文献列表。独立论文的写作内容应与 Quarto 页面相互独立。project.md 属于 asta-assistant 的 brainstorm，不属于此脚手架。
2. 将 assets/paper/gitignore 中缺失的条目追加到 .gitignore，并将 {{PAPER_DIR}} 替换为选定的相对目录（默认为 paper）。每篇论文都要重复此操作，包括嵌套目录；对目录名称中的任何 Git 忽略模式字符进行转义。提交源文件和 rc；构建输出和生成的查看器会被忽略。移除忽略规则后，已提交的自定义查看器仍会优先使用。
3. 在开发容器中使用 -tex 镜像。该镜像提供 TeX、LaTeX Workshop 和编辑器默认设置；不要复制 .vscode/settings.json。选择镜像时，保留项目已选定的版本／渠道。
4. 共享规则提供 make paper 和 make paper-clean；通过 PAPER_DIR=<directory> 选择其他论文目录。使用较旧引用的现有项目可在升级到提供这些目标的引用之前保留自己的目标。项目可以覆盖目标，或移除 workspace.mk。
5. 受管理的查看器位于 <paper-dir>/html/index.qmd。仅当项目明确设置了渲染允许列表时，才将其添加到 project.render，并从站点链接 <paper-dir>/html/index.html。保留现有页面列表／导航栏条目。共享查看器生成会处理所需的 JavaScript 资源；不要提交查看器源文件。
6. 运行 make paper（非默认目录需设置 PAPER_DIR）和 make check。如果所选的已发布规则尚未提供 paper，则使用选定目录运行 (cd paper && latexmk -synctex=1 -interaction=nonstopmode -halt-on-error -file-line-error -outdir=build main.tex)，或改用 LaTeX Workshop；不要悄悄更改项目的引用，也不要添加复制来的 Make 配方。共享 CI 论文预览已支持这些较旧的引用。启用 Pages 后，验证 PR 预览中的论文 PDF、论文页面和 What changed。一个 TeX 镜像支持多篇论文：发现机制会查找带有相邻 latexmkrc 的 main.tex，包括嵌套目录。

用佐证支持论断

脚手架会在每次渲染前从 asta-plugins 获取一个小型 Quarto 扩展（_extensions/evidence/），而不是随项目附带一份可能逐渐过时的副本。受管理的项目使用 .github/workflows/docs.yml 中选定的 ref；要升级，只需更改该 ref 并运行 make update-workspace。独立的、已脱离脚手架的 Makefile 可以单独设置 ASTA_PLUGINS_REF。此扩展能让正文中的事实论断附带佐证：论断会显示为细微的点状下划线，悬停或用键盘聚焦时，会显示逐字引文和正文样式的引用。它完全通过 CSS 渲染，因此也能在 what-changed 差异页面中正常显示，审阅者无需离开差异页面即可核查每条论断的佐证。

如果你写了查证过的论断，就为它添加佐证：在 evidence.yml 中添加一个带键条目，其中包含逐字引文、其 cite 键（将论文添加到 references.bib）、可选的原生 citeproc locator（p. 4、sec. 3.2、abstract 等），以及可选的 provenance:。来源信息必须只记录观察到的事实：method 使用准确的 CLI 子命令（例如 asta papers snippet-search），url 使用为已索引的 Asta 文档返回的规范 asta:// URI；未知字段应省略，不要推断技能或生成者名称。然后在 .qmd 中标记该论断：

NatureBench has [90 tasks]{.ev key="naturebench-count"}.

quote: 中只能填写逐字引文——不支持释义模式；请在正文中用你自己的措辞表述。完整的字段参考和设计说明见 _extensions/evidence/README.md。

这些条目的结构验证应由确定性的构建工具完成。论断是否需要佐证，以及引文是否确实支持按当前措辞表述的论断，属于判断问题——请在创建 PR 前和审阅 PR 时都加载 check-claims 技能。

GitHub Pages 部署

1. 将 assets/docs.yml 复制到 .github/workflows/docs.yml。这是一个精简的存根——构建、部署和预览机制位于此仓库可复用的工作流（.github/workflows/workspace-quarto-site.yml）中，因此脚手架生成的项目无需重新复制即可获取修复。项目专属的质量门禁应放在项目的 make check 目标中，可复用工作流会调用该目标。将现有项目更新为此存根时，请在同一项更改中更新其 Makefile（工作流要求存在 check 目标），并将分支保护中的必需检查名称更新为新的上下文（构建检查现在报告为 docs / build）——可用 gh api 尝试；如果 GitHub 拒绝，请把命令提供给用户。
2. 使用随附的 assets/github-pages.json 将 Pages 配置为从 gh-pages 发布：运行 gh api repos/{owner}/{repo}/pages -X POST --input <skill-dir>/assets/github-pages.json；如果 GitHub 拒绝，请把该命令、文件和 GitHub 的错误信息提供给用户。使用 gh api repos/{owner}/{repo}/pages 读取配置并确认来源匹配；如果 Pages 已存在且使用其他来源，请告知用户。
3. 可选，适用于你配置的此仓库或任何 GitHub 仓库：建议设置仓库保护措施（默认分支规则集、必需的文档检查）。先阅读 workflows/repo-protections.md，并在提出或应用任何措施前遵循其中的说明。

每个 PR 都会发布完整渲染预览，路径为 <pages>/pr-preview/pr-<N>/，并在其旁边发布 what-changed.html。后者会对照已部署的基础站点突出显示渲染后的新增和删除内容，并折叠未更改的部分。唯一的预览评论会先链接到更改页面，再链接到完整预览，方便审阅者直接检查受影响的内容。

开发容器

将 assets/devcontainer.json 复制到 .devcontainer/devcontainer.json。如果项目有 paper/，请将 image 改为 -tex 变体（ghcr.io/allenai/asta:latest-tex，或者固定版本时使用 <version>-tex），这样 LaTeX Workshop 就会使用与 PR 预览相同的 TeX 软件包进行构建。-tex 镜像通过其开发容器元数据添加 LaTeX Workshop 扩展，因此不要在 devcontainer.json 中列出该扩展；一个镜像可用于任意数量的论文。然后选择符合用户意图的流程：

• 本地容器（在用户的机器上工作，无需安装）：运行 make dev，在 VS Code 中打开并连接到本地容器。
• Codespaces（随时随地通过浏览器访问）：提交并推送到 GitHub 远程仓库（如有需要则创建一个），然后运行 gh codespace create 并将 URL 提供给用户。在 Codespaces 终端中使用 asta auth login 进行身份验证（重建后仍会保留），或设置可选的 ASTA_TOKEN Codespaces 密钥。端口 4848 会触发通知（onAutoForward: notify），转发的预览 URL 会显示在连接终端中。在单独的浏览器标签页中打开任一链接。在 Simple Browser 中访问 localhost:4848 无法连接到基于浏览器的 Codespace 所转发的端口，而且嵌入式框架可能无法加载私有转发 URL。本地 VS Code 可使用 Ports → 在编辑器中预览。