121 lines
8.1 KiB
Markdown
121 lines
8.1 KiB
Markdown
|
# xas-skills
|
||
|
|
|
||
|
|
公司内部共享的 Codex Skills 仓库。每个技能都是一个包含 `SKILL.md` 的目录，可带上执行任务需要的脚本、参考文档和资源。本仓库提供 Windows 安装与更新入口，安装后对当前用户的 Codex 项目生效。
|
||
|
|
|
||
|
|
## 环境要求
|
||
|
|
|
||
|
|
- Windows，自带 Windows PowerShell 5.1。可以在 CMD、Windows PowerShell 5.1 或 PowerShell 7 中运行下面的命令。
|
||
|
|
- Git 已加入 `PATH`，并且当前用户能够访问[公司仓库](https://code.it.aisuan.cn/wenhuadian/xas-skills)。脚本沿用 Git 已有的账号、凭据或认证配置，不收集密码或令牌。
|
||
|
|
- 已安装支持 Skills 的 Codex。技能安装到当前用户的 `~/.agents/skills/`，在 Windows 上通常是 `C:\Users\你的用户名\.agents\skills\`。
|
||
|
|
|
||
|
|
安装工具本身不需要 Python、Node.js 或额外 PowerShell 模块。单个业务技能若有额外依赖，必须在自己的 `SKILL.md` 中说明。
|
||
|
|
|
||
|
|
## 技能清单
|
||
|
|
|
||
|
|
| 名称 | 用途 | 额外依赖 |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| [xas-skill-review](skills/xas-skill-review/SKILL.md) | 检查待共享技能的元数据、引用文件、路径可移植性和依赖说明，给出位置、证据与修改建议 | 无 |
|
||
|
|
|
||
|
|
`skills/` 只包含正式技能；`templates/` 用于创建新技能，不会出现在安装清单中。
|
||
|
|
|
||
|
|
## 下载与安装
|
||
|
|
|
||
|
|
克隆仓库，然后查看可安装技能：
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
git clone https://code.it.aisuan.cn/wenhuadian/xas-skills.git
|
||
|
|
cd xas-skills
|
||
|
|
.\skills list
|
||
|
|
```
|
||
|
|
|
||
|
|
选择一个技能安装，或先预览将进行的操作：
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
.\skills install xas-skill-review --preview
|
||
|
|
.\skills install xas-skill-review
|
||
|
|
```
|
||
|
|
|
||
|
|
以后有多个正式技能时，将名称用空格分隔；下面的名称只是示例，需要替换为清单中真实存在的名称：
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
.\skills install skill-one skill-two
|
||
|
|
```
|
||
|
|
|
||
|
|
安装全部正式技能：
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
.\skills install --all
|
||
|
|
```
|
||
|
|
|
||
|
|
运行 `.\skills help` 或不带参数的 `.\skills` 查看帮助。入口是仓库中的 `skills.cmd`，无须添加到 `PATH`；脚本始终使用其所在仓库的技能目录，从其他工作目录通过完整路径调用也可使用。
|
||
|
|
|
||
|
|
入口内部使用 Windows PowerShell 5.1，仅为本次进程设置执行策略，不修改用户或机器策略。应先阅读并信任仓库脚本；公司组策略仍优先，若公司不允许执行，应遵循公司的批准流程。原有 `install.ps1` 和 `update.ps1` 保留兼容，但日常使用统一通过 `.\skills`。
|
||
|
|
|
||
|
|
安装完成后，在 Codex 中查看技能清单，必要时重新启动 Codex。可以这样试用：
|
||
|
|
|
||
|
|
```text
|
||
|
|
使用 $xas-skill-review 检查 D:\work\my-skills\example-skill，列出共享给同事前需要解决的问题。
|
||
|
|
```
|
||
|
|
|
||
|
|
安装会复制完整技能目录，并记录来源与文件摘要。相同内容重复安装会跳过；存在不属于本仓库管理的同名目录，或已安装内容被用户增加、删除、修改时，会报告冲突并停止。没有强制覆盖选项。
|
||
|
|
|
||
|
|
每个已安装技能中的 `.xas-install.json` 是安装器的管理记录，不要编辑它或将它复制回仓库的源技能目录。
|
||
|
|
|
||
|
|
## 更新已安装技能
|
||
|
|
|
||
|
|
保留本地仓库，用它获取更新：
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
.\skills update --preview
|
||
|
|
.\skills update
|
||
|
|
```
|
||
|
|
|
||
|
|
`--preview` 只显示预期步骤，不拉取远端，也不写入文件，因此不能预览尚未下载的新版本内容。正常更新要求工作区干净、当前分支跟踪 `origin/main`，并且不存在本地未推送提交；满足条件后只做快进更新，不创建合并提交。
|
||
|
|
|
||
|
|
拉取成功后会重新运行更新后的脚本，再同步此前从本仓库安装的技能。新增的上游技能需要主动安装；上游已删除的技能会提示人工处理，不自动卸载。
|
||
|
|
|
||
|
|
同步前先检查冲突，再准备完整的新目录并替换。旧版本中已被上游移除的文件不会残留。替换失败时恢复当前技能的旧版本；多个技能并非一个整体事务，错误信息会说明失败情况。不会改动其他来源的技能。
|
||
|
|
|
||
|
|
首次发布前，远端没有可拉取的 `main` 提交，更新入口会给出明确错误。此时应先审阅并完成仓库首次发布，再验证真实远端更新流程。
|
||
|
|
|
||
|
|
## 常见问题
|
||
|
|
|
||
|
|
| 情况 | 处理方式 |
|
||
|
|
| --- | --- |
|
||
|
|
| 无法访问远端、认证失败 | 先用 Git 确认仓库权限、公司网络及凭据；脚本不会修改认证配置。 |
|
||
|
|
| PowerShell 禁止执行脚本 | 上述命令采用本次进程的执行策略；公司组策略仍然优先。按公司策略处理，并先检查源码；安装工具不会修改系统或用户执行策略。 |
|
||
|
|
| 找不到技能或名称有误 | 用 `.\skills list` 查看真实名称；模板不能直接安装。 |
|
||
|
|
| 忘记命令用法 | 运行 `.\skills help`；无需记忆 PowerShell 参数。 |
|
||
|
|
| 已有同名技能，或已安装文件被修改 | 先查看报错中的目标路径。把需要保留的整个技能目录移到独立备份位置，再重新安装；不要只删除管理记录以绕过冲突。 |
|
||
|
|
| 工作区有未提交文件，或分支状态不符合要求 | 先人工审阅并处理本地修改和分支状态，再运行更新；脚本不会暂存、提交、重置或丢弃修改。 |
|
||
|
|
| 远端为空或不存在 `main` | 由维护者审阅并发布首个 `main` 版本后再使用更新入口。 |
|
||
|
|
| 检测到链接目录或越界路径 | 使用普通目录的仓库与安装路径；检查报错指出的链接，不通过强制覆盖绕过检查。 |
|
||
|
|
| 同步失败 | 查看报错与恢复提示，保留备份，再处理文件占用或权限等原因。失败时脚本返回非零退出码。 |
|
||
|
|
|
||
|
|
## 添加或修改技能
|
||
|
|
|
||
|
|
1. 将 `templates/skill-template/` 整个复制到 `skills/<技能名称>/`。目录和 `SKILL.md` 中的 `name` 使用相同的小写字母、数字与连字符名称，长度小于 64 个字符。
|
||
|
|
2. 替换模板里的填写提示。`description` 写清“做什么、何时使用”；正文写具体操作、输入、输出和确实需要的依赖。只添加实际需要的 `scripts/`、`references/`、`assets/` 目录。
|
||
|
|
3. 以技能自身为单位保持完整：内部资源使用相对路径，不写个人机器路径，不提交凭据、客户数据或临时产物。外部依赖写明配置方式，不能假设同事拥有作者的环境。
|
||
|
|
4. 更新本 README 的技能清单。用 `xas-skill-review` 检查技能，再用一个正常任务和一个信息不完整的任务验证实际表现；检查报告不能替代实际使用验证。
|
||
|
|
5. 运行安装与更新测试，在测试临时目录验证，不覆盖自己的技能。经人工审阅后，再按公司流程提交、推送。
|
||
|
|
|
||
|
|
本仓库安装器不依赖完整 YAML 解析模块。必填键使用顶层未加引号的 `name:`、`description:`；值支持单行纯文本、单双引号和行尾注释，`description` 还支持 `|`、`>` 多行块及 `+`/`-` 标记。双引号内使用 JSON 转义。空值、非字符串、重复必填键、集合、锚点、别名、标签、多行普通或引号字符串、显式块缩进指标会被拒绝；请改用模板中的写法。这是本安装器的支持范围，不代表 Codex 对所有 YAML 的限制。
|
||
|
|
|
||
|
|
## 开发验证
|
||
|
|
|
||
|
|
项目测试只使用 PowerShell 和 Git，不要求安装测试模块。文件操作使用临时目录，Git 更新流程使用模拟结果，不创建测试提交，也不修改真实个人技能目录。
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tests\Test-Install.ps1
|
||
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tests\Test-Update.ps1
|
||
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\tests\Test-Cli.ps1
|
||
|
|
pwsh -NoProfile -ExecutionPolicy Bypass -File .\tests\Test-Install.ps1
|
||
|
|
pwsh -NoProfile -ExecutionPolicy Bypass -File .\tests\Test-Update.ps1
|
||
|
|
pwsh -NoProfile -ExecutionPolicy Bypass -File .\tests\Test-Cli.ps1
|
||
|
|
```
|
||
|
|
|
||
|
|
应同时验证 Windows PowerShell 5.1 与 PowerShell 7。远端尚未首次发布时，这些本地测试不等同于真实远端端到端验收；发布后应使用独立临时克隆补充验证下载安装和更新。
|
||
|
|
|
||
|
|
PowerShell 源码保存为 UTF-8 with BOM，以兼容 Windows PowerShell 5.1 对中文的读取；Markdown 保存为 UTF-8 without BOM。换行约定见 `.gitattributes`。
|