编写新的工具适配器

当你要为 Apothem 编写一个新的工具适配器（作为一方内置项或第三方包）时， 请使用本操作手册。

前置条件Copy Anchor Link

• 熟悉 HarnessAdapter 协议
• 理解目标工具的配置格式
• Python 3.10+

步骤Copy Anchor Link

1. 实现适配器Copy Anchor Link

按照 编写工具适配器 示例，为目标工具实现 HarnessAdapter。

如果适配器以 mode: write_text 和 ownership_class: operator-owned 写入一个纯文本模板（不是 JSON 或 YAML 的文件），则只有当该文件是 Apothem 所发布模板的未经编辑的副本时，uninstall 才会删除它。当之后的某个版本更改了该模板时， 请在同一次更改中将先前文本的 SHA-256 摘要添加到该清单条目的 earlier_digests 列表中， 否则 uninstall 会保留较早版本写入的每一份未经编辑的副本。 使用 git show <tag>:<template path> | sha256sum 获取最新发布标签处文本的摘要； 该模板不得带有任何 ${...} 路径标记。当某个已发布的模板未被记录在案时， tests/unit/test_template_digests.py 会失败。

2. 编写文档页面Copy Anchor Link

创建 site/content/docs/harnesses/<slug>.mdx，涵盖：

• 安装流程
• 配置文件到原生配置的映射
• 兼容性注意事项
• 验证方法
• 更新与卸载方法
• 合规闸门表面
• 故障排查表
• 配置项表

3. 编写测试Copy Anchor Link

tests/packaging/test_<slug>_adapter.py
tests/unit/test_<slug>_adapter.py

最低测试覆盖：

• test_install_creates_expected_files
• test_verify_passes_after_install
• test_uninstall_removes_files

4. 本地验证Copy Anchor Link

apothem install --harness <slug>
apothem verify --harness <slug>
python -m apothem.conformity.gate --all .

5. 提交拉取请求Copy Anchor Link

提交一个包含以下内容的 PR：

• 适配器实现
• 位于 site/content/docs/harnesses/<slug>.mdx 的文档页面
• 测试
• 在 pyproject.toml 中注册入口点，在 src/apothem/lib/harness_registry_data.py 中添加 HARNESS_REGISTRY 条目（并在那里递增 SUPPORTED_HARNESS_COUNT），以及将该 ID 加入 src/apothem/schemas/profile.schema.json 的 harnessId 枚举
• 变更日志条目