# 草诀歌 Agent 资源

本轮覆盖官网与司马迁、包青天、严复、列宾、张骞五个公开 skill 子站。网站继续使用静态托管；未增加 MCP、OAuth、交易接口或 AI 训练授权。

## 公开入口

- `/agents/`：首页页脚可见的中文资源页，按任务介绍五个 skill，提供完整下载与可复制的开始指令。
- `/llms.txt`：公开说明页与技能安装包导航。
- `/.well-known/agent-skills/index.json`：Agent Skills Discovery draft v0.2 索引。官网汇总五项，子站各列自己的一项。
- `/index.md`：从本域首页生成的 Markdown。官网的 21 个 sitemap 页面均提供同名 `.md`，包含 `/agents/index.md`。
- `/agent-skills/<name>/SKILL.md`：可直接读取的技能指令，相邻目录包含配套参考文件、脚本、模板。
- `/downloads/agent-<name>-<digest>.zip`：完整技能包，包含顶层 `<name>/` 目录。索引中的 SHA-256 对应下载文件的精确字节。

网页通过 HTML `<link>` 和 HTTP `Link` 响应头公开入口。`.md` 返回 `text/markdown`，索引返回 JSON；资源允许跨域读取。顶层 `404.html` 关闭 Cloudflare Pages 的隐式首页回退。

本轮提供显式 `.md` 文件，**没有开启 `Accept: text/markdown` 内容协商**。后者需单独决定 Cloudflare 区域设置或请求处理方式，且不能顺带改变训练授权策略。`llms.txt` 和发现索引不保证客户端采用或流量增长。

## 内容来源与边界

网页是说明内容的源，`SKILL.md` 及配套目录是安装包的源。生成器只处理官网 sitemap 中的页面和子站首页；`family/`、未发布的知识页、工作输出和用户材料不进入索引或 Markdown。

中文资源页由 `agents/template.html` 和 `agents/skills.json` 生成；下载地址与开始指令中的安装包地址取自同一份 skills 索引。更新 `agents/skills.json` 中的用途、输入输出或开始指令后，重新生成资源页。`agents/agents.js` 负责复制；剪贴板不可用时展开并选中指令，支持手动复制。

安装包按 `agent-resources.json` 的白名单生成，排除 `.git`、`__pycache__`、`.pyc`、`node_modules`。不执行下载的技能脚本。ZIP 的文件顺序、时间戳与权限固定；不变的源文件生成不变的摘要。已公开的带摘要文件名应保留，不覆盖原文件。

司马迁的 `name` 元数据从 `simaqian.skill` 规范为 `simaqian`，并同步 `agents/openai.yaml` 的 `$simaqian` 调用名；页面展示名仍为“司马迁.skill”。旧技能目录可继续手动使用，新安装建议使用 `simaqian/`。技能流程未修改。

本轮源仓库基线：

| 仓库 | 源提交 | 发布目录 |
| --- | --- | --- |
| simaqian | `b2384a6575579aaadcb2b85df30d576fddfdae11` | `landing/` |
| baoqingtian | `019186330bcbde1bd54248051e8d7957249339b0` | 仓库根目录 |
| yanfu | `61933c74bd310604d9a06aef59bf50945d23192a` | `landing/` |
| Liebin | `f343b732e350af01815f2919a5bd7090f6f1764b` | `site/` |
| zhangqian | `7dc8f7176b4cee6a8489db9f5fa09f2c6638495b` | `site/` |

## 更新和验证

需要 Python 3.9+ 和 Defuddle CLI。先更新公开源码的本地副本，再从官网仓库执行：

```sh
python3 scripts/agent-resources.py \
  --repo simaqian=/path/to/simaqian \
  --repo baoqingtian=/path/to/baoqingtian \
  --repo yanfu=/path/to/yanfu \
  --repo Liebin=/path/to/Liebin \
  --repo zhangqian=/path/to/zhangqian

python3 -m unittest discover -s tests -p 'test_agent_resources.py'
```

生成器会同时更新六个站的静态产物，需将对应产物带入各自的发布目录；它不会自动发布。不要只更新安装包、不更新索引摘要。修改网页后也应重新生成 Markdown。

发布前用 Cloudflare 的本地运行环境检查 GET / HEAD、MIME、Link、跨域读取、404、摘要和解压后的依赖。官网有尚未发布的本地工作时，从本次变更清单和已有受版本控制的网站文件准备发布目录，不能直接上传整个工作区。

上线后逐域验证 `/robots.txt`、`/sitemap.xml`、`/llms.txt`、`/index.md`、skills 索引，以及随机缺失的 `.json` 地址。主站索引依赖五个子站的安装包，正式发布时先发布子站，再发布主站，并按真实站点类型重跑 isitagentready。

## 已知限制

司马迁安装包保留 README，但没有复制其中指向的公开人物示例；需要这些示例时请访问源仓库的 `examples/`。模板、核心参考文件、导出脚本、npm 配置及锁文件均包含在安装包中。