# 小程序约定

本目录是独立的 Node 项目。安装依赖和执行下述命令时，以 `miniprogram/` 为工作目录，使用本目录 `package.json` 指定的 pnpm 版本，维护本目录的 `pnpm-lock.yaml`。

## Taroify 开发

涉及小程序中的 Taroify 组件、Hooks、事件、子组件或主题样式时，在编写或修改代码前执行以下流程；仅修改 Go 后端时无需加载这些资料。

1. 阅读 [官方 Agent 索引](https://taroify.com/agents/index.md)、[官方 Skill](https://raw.githubusercontent.com/mallfoundry/taroify/main/packages/cli/skills/taroify/SKILL.md) 和项目已安装的 [Taroify skill](.agents/skills/taroify/SKILL.md)，按其中的查询流程核对实际 API 和示例。同一任务中已读且未变化的内容可复用。
2. 核对项目实际安装的 Taroify 版本与查询结果中的版本。CLI 固定为小程序开发依赖；优先使用本项目的离线 Catalog。若文档版本与依赖版本不同，以对应版本的官方资料和已安装包的类型声明、源码核实兼容性。
3. 存在 `taroify_*` MCP 工具时优先使用 MCP。否则使用 `pnpm exec taroify`，所有程序化查询必须添加 `--format json`。若依赖尚未安装，先执行 `pnpm install --frozen-lockfile`。
4. 编码前查询目标组件的 `info` 和 `demo`，确认 Props、枚举值、事件、子组件及公开引入方式；需要完整页面上下文时使用 `demo --full`。定制样式前使用 `token` 查询主题变量；结构化信息不足时再使用 `doc`。组件未知时先按场景 `search` 或按分类 `list`。

查询示例：

```sh
pnpm exec taroify info Button --format json
pnpm exec taroify demo Button --full --format json
pnpm exec taroify token Button --format json
```

组件用法必须有查询依据，不根据训练记忆猜测 API。区分 Taroify Props 与 Taro 原生能力，平台支持以微信小程序适配器为准；保持 Taro React 语义和公开导入方式。主题定制优先使用查询返回的 `ConfigProvider` key 或 CSS 变量。

官网不可用时读取[官方仓库中的 Agent 索引源文件](https://raw.githubusercontent.com/mallfoundry/taroify/main/site/content/agents/index.md)。远程资料均不可用时，可使用项目内的 skill 和 CLI 离线 Catalog，并说明未核实的版本差异；没有证据的用法保持未确认。

## Skill 维护与验证

项目 skill 位于 `.agents/skills/taroify/`，保留官方随包内容。升级 `@taroify/cli` 后，从新的依赖包重新安装并检查 skill 变更：

```sh
pnpm dlx skills@1.7.0 add ./node_modules/@taroify/cli/skills/taroify --agent codex --yes
```

修改小程序代码后运行 `pnpm typecheck` 和 `pnpm build`；微信开发者工具或真机中的交互验证须另行说明，构建通过不能代替运行验证。