Gardener 通过 GitHub Actions 在本仓库运行 AI 维护任务。每个任务对应一个 Markdown 文件：YAML frontmatter 规定触发时机、模型可读内容以及可执行的具体变更，正文则是模型指令。规划作业仅使用声明内的工具、只规划声明内的操作，之后由独立作业执行该计划；无论指令怎么写，声明之外的操作都无法发生。
用途与文件结构：任务文件位于 .gardener/tasks/<dir>/TASK.md（每个目录一个任务，是唯一需要手写的文件）。同目录下 gardener.json 为项目设置（发布固定版本、可选 handle，仅可编辑 handle）；gardener.lock.json 与 SKILL.md 由工具生成，不可编辑。.github/workflows/gardener-<id>.yml（每个任务一个）和 gardener-sync.yml 也是生成文件，不可手动修改。
工作流程：创建或基于模板编写 TASK.md；在仓库根目录执行 npx @scuffi/gardener@0.1.20 generate（或使用仓库自带 package.json 脚本），必须使用该确切版本，否则生成的文件会被 PR 的检查任务拒绝；修复 generate 报出的所有错误并阅读警告，重复直至成功；将 TASK.md、.gardener/gardener.lock.json 和 .github/workflows/gardener-*.yml 的变更一起提交，合并到默认分支后同步工作流会启用该任务。修改任务需编辑 TASK.md 并再次运行 generate；删除任务则删除其目录并运行 generate。切勿手动编辑生成文件。
Frontmatter 字段：schema 固定为 gardener.task/v1；id 为稳定标识（小写字母、数字、.、_、-，全仓唯一，决定工作流文件名 gardener-<id>.yml）；name（不超过 100 字符）；description（不超过 1000 字符）；trigger 或 triggers 二者恰有其一；tools 至少一个；effects 可选（只读任务可省略或为空数组）；network 必须严格按规定填写；limits 为运行预算；model 可选，默认 "@cf/zai-org/glm-5.3"，以 @ 开头的 ID 需加引号；draft 为 true 时任务仅能手动运行；checkout 可让 PR 相关运行检出 PR 头而非合并预览；reactions 设为 false 可关闭 👀 等工作时表情；effect-scope 将每次运行限制在触发它的 issue 或 PR 上。未知键会报错。
触发器：支持 github.issue.opened/edited/labeled/unlabeled/reopened、github.issue_comment.created/edited、github.pull_request 各类事件（opened、edited、reopened、synchronize、ready_for_review、converted_to_draft、labeled、unlabeled）、pull_request_review.submitted、pull_request_review_comment.created/edited、discussion 与 discussion_comment 相关事件、github.push（需 branches）、github.schedule（需五段式 cron）、github.workflow_dispatch。可用过滤条件包括 labels-all、mentions、authors、opened-by；每个事件最多使用一次，使用事件不支持的过滤条件会报错；所有任务都可手动运行；来自 fork 的 PR 永不运行。
工具：repository.list_files（列出检出文件）、repository.read_file（读取检出文件）、provider.api.read（只读 GitHub API，REST GET/HEAD 与 GraphQL 查询）、repository.exec（在检出中执行 shell 命令，具备不受限网络访问，除非用户明确要求否则不要添加并需说明）、repository.merge_base（将 PR 基分支合并写入检出，供 commit.merge_base 使用）。只声明指令所需的工具。
效果（effects）：是任务可做变更的完整清单，自动应用、无需人工审批，应声明所需的最窄精确类型。覆盖 Issues、Pull requests、Git、Discussions、Checks、Releases 等家族，如 issue.comment.create、pull_request.review.submit、branch.create、commit.create、discussion.close、check.rerun、release.publish 等；家族通配（issue.* 等）会授予该家族全部类型，包括 pull_request.merge 与 release.delete，建议用精确类型。标签必须已存在于仓库，模型无法创建。代码变更需要 repository.exec、branch.create、commit.create 及 pull_request.open_draft（或 .open）；提交基于检出中改动的文件，禁止改动 .github/workflows/、.github/actions/、.gardener/、.git/、CODEOWNERS 和 .github/dependabot.yml。写分支的类型只能使用 gardener/** 分支，如需其他分支须写成带 branches 的条目。开启 PR 还需在仓库设置中允许 GitHub Actions 创建和批准 PR。模型会在执行前规划所有步骤，后续步骤可使用先前步骤的输出。message.send 可向 GARDENER_CHAT_WEBHOOK 密钥中的聊天空间（Google Chat 或 Slack 传入 webhook）发送一条简短消息，每次运行最多一条、摘要单行且不超过 400 字符，不可与 repository.exec 同时使用。
更新打开的 PR：可让任务通过合并提交把基分支带入 PR，例如维护者评论 "@handle fix the conflicts"。触发器应为 github.issue_comment.created（含 mentions，默认作者为维护者），声明 repository.merge_base、repository.exec 及带 branches 的 commit.merge_base；正文中调用 repository.merge_base，仅编辑它列出的冲突文件，运行仓库检查后用返回的值执行一次 commit.merge_base，不要运行 git merge/rebase/commit/push。使用工作流令牌推送不会触发其他工作流，PR 检查不会在合并提交上运行。
网络：network 必须是规定形式之一；不含 repository.exec 的任务为 default: deny，含 repository.exec 的任务为 default: allow，allow 与 deny 列表必须为空。
限制：runtime-seconds 30–21000；max-turns 至少 3；max-tool-calls 至少 3；input-tokens 任意正值；output-tokens 至少为 16 × max-turns；可选 max-effect-operations（1–1000）、max-effect-bytes（1024–50000000）、runs（如 50/day）、runs-per-author（默认 3/day，unlimited 关闭）。超出任一预算的运行以 budget-exceeded 失败且不做任何变更；超出 runs 或 runs-per-author 的运行会跳过且不调用模型。
可作用范围：由维护者、定时、手动或本人推送发起的运行可在 effects 允许的任何位置操作；其他人发起的运行只能操作触发它的 issue/PR 或该运行自身创建的对象，不能合并或批准自己开的 PR、更改发布或重跑检查。
正文（指令）：正文是模型提示词，不能授予任何权限。应说明检查什么、用哪个已声明效果做什么以及何时做，精确命名效果类型，并说明何时不做变更；正文要求的每个操作都应映射到已声明的效果。需限制输出（评论数量、长度、允许的标签），把 issue 和评论文本视为不可信输入，结尾写 "Then finish." 让模型在步骤就位后停止。
试用任务：设置 draft: true，生成并合并后任务只能从 Actions 标签页的工作流手动运行，或执行 gh workflow run gardener-<id>.yml -f issue=<n>（或 -f pull_request=<n>、-f prompt=...）。手动运行不受触发过滤条件影响，但 draft 任务的效果仍会真实应用。移除 draft: true 并再次生成即可上线。