iztro

# astro（iztro）仓库约束

## 工作范围与变更管理

- 开始修改前检查工作区、暂存区和当前分支，保留用户已有修改。按本次请求确定范围，不顺带升级无关依赖或改写无关文档。
- `src/` 为库源码，`src/__tests__/` 为测试，`lib/` 和 `dist/` 为库构建输出，`docs/` 为文档站点构建输出；文档源码位于独立的相邻 `astro-docs` 仓库。操作前确认实际路径及各仓库状态。
- 涉及相邻仓库时，先阅读其 `AGENTS.md` 及要求使用的技能，分别遵守其约束。不因路径相邻而假设拥有写权限。
- 仅调查、评估升级兼容性时，优先在隔离临时副本中安装和测试候选方案；实施修改后，核对验证副本与最终源文件一致。

## 依赖与安全告警

- 根项目使用 Yarn Classic 和 `yarn.lock`。依赖修改须同步 `package.json` 与锁文件，避免引入额外的根目录 `package-lock.json`；示例子项目已有的锁文件按其自身约定维护。
- CI 安装根项目依赖使用 `yarn install --frozen-lockfile`，缓存与测试命令保持 Yarn 一致。`resolutions` 是 Yarn 的版本覆盖规则，不可假设 `npm install` 会应用它。
- 处理 Dependabot 告警时，读取当前告警、受影响范围、修复版本及依赖引入链，并核查上游安全公告和 CVE 最新状态。区分生产依赖、开发依赖及是否进入发布产物，不仅凭严重性标签判断业务影响。
- 优先采用同一主版本内的最小安全补丁，更新既有覆盖规则；不要为消除告警将所有间接依赖强制统一到一个主版本。
- 核实安装后的实际依赖版本及锁文件差异。存在多个版本分支时逐一确认，不能仅修改顶层版本号后宣布修复。
- 已撤销、无补丁或当前调用路径不可达的告警，应说明证据、适用范围和处理建议；未经用户授权，不替用户关闭远端告警。

## 多语言术语与文档同步

- 语言定义以 `src/i18n/locales/` 为准。修改前对照中文语义、当地专业用法及上下文；已确认的误译直接修正，有争议的异名先保留。
- 需要外部查证时，韩语以 `자미두수` 在 Naver 检索；日语以 `紫微斗数`、越南语以 `Tử Vi Đẩu Số` 在 Google 和必应检索。搜索摘要用于定位资料，结论优先依据原文，并记录未确认项。
- 日语显示文本统一为常用日文字形；有日本字形的字使用对应形式，没有对应形式的专业字保留。不要将中文源码、其他语言的汉字括注或古文引文一并替换。
- 译名也参与类型定义和 `kot()` 反查。修正星曜、宫位、亮度、四化名称时检查显示、反查和实际查询行为，尤其区分同音星曜、宫位与星曜同名，以及天钺与天月。
- 保留 `src/i18n/starAliases.ts` 中有意提供的消歧别名。反查按查询类型限定名称范围，避免星曜名称被当成宫位名称。
- 修改对外显示值或 API 取值时，同步检查 `astro-docs` 的对应正文、所有语言页面中的多语言取值列表、术语词表和语义校验记录；不要只修改目标语言目录而遗漏其他页面展示的同一列表。
- 文档中保留代码标识、中文输入示例、链接目标、既有锚点和规定保留的古文引文。批量替换必须识别语言选项卡、缩进代码块及引用边界，不能全文替换同形字词。

## 兼容性与验证

- 保持公共方法、JSON 字段、UMD 文件名、浏览器目标及 sourcemap 的兼容性。农历依赖应避免 CommonJS/ESM 入口重复打包；压缩配置不得混淆公共属性名。
- 排盘结果及后续查询应使用生成时的配置和语言，避免受后续全局设置或其他排盘调用影响。处理日期、运限、语言相关修改时，覆盖对应边界和隔离行为。
- 按修改范围执行验证：相关 Jest 测试、`yarn lint` 和 `yarn tsc --noEmit`；依赖升级或核心行为修改执行 `yarn test --runInBand`。
- 依赖、构建或发布兼容性有变化时，执行 `yarn build:umd` 与 `yarn verify:umd`，验证 CommonJS、AMD、浏览器全局入口及依赖去重。`verify:umd` 不会替代前置的 UMD 构建。
- 安全补丁除正常功能回归外，尽可能验证相关漏洞边界确实受限。不得运行会失控消耗资源的攻击样例。
- 文档同步按 `astro-docs` 约束运行检查和构建。构建前确认输出目录；仅为验证时使用临时输出，避免覆盖本仓库 `docs/` 或其他已有产物。
- 验证通过后只在修改、失败或新增疑点需要时重跑。报告实际测试范围、运行环境及未验证项，不将一次运行的测试数量写成永久门槛。纯约束或日志修改无需重跑库测试。

## CHANGELOG

- 功能、修复、依赖安全更新及相关构建/CI 变更应同步记录到 `CHANGELOG.md` 的“未发布”部分；用户指定版本时按其要求处理，不自行发版或修改版本号。
- 沿用 v2.6.2 的嵌套分类格式：顶层使用 `✨ 改进（enhancement）`、`🪄 功能（feature）`、`🛠️ 修复（fix）`、`🧹 琐事（Chore）`，具体条目缩进写在分类下；仅列有内容的分类。
- 描述最终行为、兼容性影响和必要迁移信息。安全修复注明依赖和修复版本，确认存在时注明 CVE；不要把已撤销告警写成已修复漏洞。
- 新变更使已有“未发布”描述过时时一并修订，避免日志内部矛盾；不重写无关历史版本。

## 提交与交付

- 用户要求提交时，检查并明确暂存本次相关文件，分别提交各仓库；提交信息说明具体问题、最终变化及验证结果。
- 生成文件只在本次需要更新时纳入提交；大批量站点文件应核对来源、修正内容及资源引用，必要时与库源码分开提交。
- 提交后检查工作区并报告提交哈希。区分“本地提交”和“推送远端”；未获相应授权时不推送、不打标签、不发布 npm 包或部署站点。注意 `yarn version` 会触发本仓库的版本生命周期脚本，包含提交暂存及推送操作，不将其用于普通验证。
- 提交或推送不等于远端安全告警已关闭，也不等于站点已完成线上验收；交付时只报告已确认的状态。

## 版本发布技能

- 用户明确要求“发布版本”、发布 iztro 到 npm 或执行 release 时，读取并遵循 `skills/iztro-release/SKILL.md`，执行同步、验证、版本确认、日志整理、提交、标签发布和远端验收。
- 仅创建或修改发布技能、workflow、版本号及讨论流程不触发发布。明确的发布请求授权技能内必要的提交和推送；已发布版本必须询问用户确认并输入新的版本号。
- 发版日志标题使用 `## v版本号（YYYY.MM.DD 发布）`，日期取实际发布当天的 Asia/Shanghai 日期。Release 说明提取须兼容带日期标题和历史裸版本标题，拒绝缺失、重复或空章节。

More agent context in SylarLong/iztro

One other file this repository gives its agents.