# 与 Agent 一起使用 Semifold

为发布任务提供按需读取的 Markdown 文档和可移植的 Semifold Skill。

Source: https://semifold.noctisynth.org/zh/docs/agents/
Language: zh



Agent 可以通过[英文索引](https://semifold.noctisynth.org/llms.txt)、[中文索引](https://semifold.noctisynth.org/zh/llms.txt)或[双语全文](https://semifold.noctisynth.org/llms-full.txt)读取与网页同源的文档。索引直接链接逐页 Markdown，便于按任务读取。每个文档网页通过 HTML alternate 链接标记对应的 Markdown 版本。

## 获取 Semifold Skill [#获取-semifold-skill]

仓库以 [Agent Skills 格式](https://agentskills.io/specification)分发 [skills/semifold](https://github.com/noctisynth/semifold/tree/main/skills/semifold)。将包含 `references/` 的完整 `semifold` 目录复制到客户端支持的技能目录，或使用客户端的仓库技能安装功能，指定仓库 `noctisynth/semifold` 与路径 `skills/semifold`。安装和发现位置由客户端决定，本仓库不会自动执行全局安装。

Skill 将 changeset 创建、配置维护、发布计划检查和发布故障定位引导到已有命令文档，并遵守使用者仓库规则及授权范围。Semifold 仓库根目录的 `AGENTS.md` 则服务于修改 Semifold 自身源码的 Agent。

## 开始任务前 [#开始任务前]

运行 `smif --version` 和 `smif <command> --help`，读取目标仓库的 `.changes/config.toml` 和工作流，使用真实配置的 package ID 和 tag。旧版本与新文档示例不一致时，以已安装版本的 help 确认参数，不从网站文档推断本地版本。

## 任务检查点 [#任务检查点]

| 任务     | 前置条件与操作                                    | 预期结果和副作用                                        | 恢复参考                                   |
| ------ | ------------------------------------------ | ----------------------------------------------- | -------------------------------------- |
| 记录变更   | 使用配置中的 package ID；非交互 `smif commit` 提供完整参数 | 创建一个 changeset，不修改版本；随后查看 `smif status`         | [Changeset](https://semifold.noctisynth.org/zh/docs/commands/commit/) |
| 检查发布计划 | 有效配置和 changeset；`smif status`              | 展示包、版本和传播原因，不改包文件；`--comment` 会写 GitHub         | [状态](https://semifold.noctisynth.org/zh/docs/commands/status/)        |
| 维护配置   | 已接入项目；`smif config sync --check`           | 检查差异；执行 `config sync` 才应用配置更新                   | [配置](https://semifold.noctisynth.org/zh/docs/commands/config/)        |
| 准备版本   | 确定手动或 CI 流程并检查 hook                        | 更新版本和 changelog，消费 changeset；hook 失败可能保留部分已应用状态 | [版本更新](https://semifold.noctisynth.org/zh/docs/commands/version/)     |
| 发布     | 版本已准备、凭据就绪且发布范围明确                          | 写入 registry 及按配置操作 GitHub，报告部分完成状态              | [发布](https://semifold.noctisynth.org/zh/docs/commands/publish/)       |

`--dry-run` 仍可能执行明确允许 dry run 的配置命令，publish preflight 也可能访问 registry。先检查 hook，并遵守网络或本地禁止编译的约束。

使用生成的 GitHub Actions 时遵循 [CI 流程](https://semifold.noctisynth.org/zh/docs/commands/ci/)，同一次发布不再重复执行本地 version 或 publish。