ziwei 0.1.0__tar.gz

ziwei-0.1.0/.github/workflows/checks.yml

@@ -0,0 +1,47 @@
+name: Checks
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: quality (${{ matrix.os }}, ${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: "3.11"
+            uv-checksum: "68a509da24b06b4223a1c0175fb5eb5bc79342b76cbeff0cfe51ac3f5b17b6b2" # uv-x86_64-unknown-linux-gnu.tar.gz
+          - os: ubuntu-latest
+            python: "3.14"
+            uv-checksum: "68a509da24b06b4223a1c0175fb5eb5bc79342b76cbeff0cfe51ac3f5b17b6b2" # uv-x86_64-unknown-linux-gnu.tar.gz
+          - os: ubuntu-24.04-arm
+            python: "3.14"
+            uv-checksum: "9bf43b4d1a07665bf64d4c4e710930b382321a785e0eb10aac07f46471f86a31" # uv-aarch64-unknown-linux-gnu.tar.gz
+          - os: macos-latest
+            python: "3.14"
+            uv-checksum: "5bb0e5fe008a773c3dbcb97ff79cd89e1241464fe9d2f986d52ad8f1b037bd62" # uv-aarch64-apple-darwin.tar.gz
+          - os: windows-latest
+            python: "3.14"
+            uv-checksum: "4c4d49d8738847d9b71ba319e49a5688c93eac0fe6204b1df24e98528dddf39a" # uv-x86_64-pc-windows-msvc.zip
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          version: "0.12.5"
+          checksum: ${{ matrix.uv-checksum }}
+          enable-cache: false
+      - run: uv sync --locked --python ${{ matrix.python }}
+      - run: uv run --locked python tools/check.py

ziwei-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,177 @@
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Candidate version already committed on main
+        required: true
+        type: string
+      sha:
+        description: Full lowercase SHA of the latest main commit when dispatching
+        required: true
+        type: string
+
+permissions: {}
+
+concurrency:
+  group: ziwei-publish
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    env:
+      RELEASE_VERSION: ${{ inputs.version }}
+      RELEASE_SHA: ${{ inputs.sha }}
+    outputs:
+      version: ${{ steps.release.outputs.version }}
+      source_sha: ${{ steps.release.outputs.source_sha }}
+      sdist_name: ${{ steps.release.outputs.sdist_name }}
+      wheel_name: ${{ steps.release.outputs.wheel_name }}
+      sdist_sha256: ${{ steps.release.outputs.sdist_sha256 }}
+      wheel_sha256: ${{ steps.release.outputs.wheel_sha256 }}
+      artifact_id: ${{ steps.upload.outputs.artifact-id }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.14"
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          version: "0.12.5"
+          checksum: "68a509da24b06b4223a1c0175fb5eb5bc79342b76cbeff0cfe51ac3f5b17b6b2"
+          enable-cache: false
+      - run: uv sync --locked --python 3.14
+      - name: Check source checkout
+        run: &verify-source |
+          set -euo pipefail
+          test -z "$(git status --porcelain --untracked-files=all)"
+          git diff --exit-code "$GITHUB_SHA" --
+      - run: uv run --locked python tools/release.py validate
+      - run: uv run --locked python tools/check.py --artifacts-dir dist
+        env:
+          SCRATCH: ${{ runner.temp }}
+      - name: Check source remained unchanged
+        run: *verify-source
+      - id: release
+        run: uv run --locked python tools/release.py prepare
+      - id: upload
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: ziwei-${{ steps.release.outputs.version }}-${{ github.run_id }}
+          path: dist/
+          if-no-files-found: error
+          overwrite: false
+          retention-days: 14
+
+  consume:
+    needs: build
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: "3.11"
+            checksum: "68a509da24b06b4223a1c0175fb5eb5bc79342b76cbeff0cfe51ac3f5b17b6b2"
+          - os: ubuntu-latest
+            python: "3.12"
+            checksum: "68a509da24b06b4223a1c0175fb5eb5bc79342b76cbeff0cfe51ac3f5b17b6b2"
+          - os: ubuntu-latest
+            python: "3.13"
+            checksum: "68a509da24b06b4223a1c0175fb5eb5bc79342b76cbeff0cfe51ac3f5b17b6b2"
+          - os: ubuntu-latest
+            python: "3.14"
+            checksum: "68a509da24b06b4223a1c0175fb5eb5bc79342b76cbeff0cfe51ac3f5b17b6b2"
+          - os: ubuntu-24.04-arm
+            python: "3.14"
+            checksum: "9bf43b4d1a07665bf64d4c4e710930b382321a785e0eb10aac07f46471f86a31"
+          - os: macos-latest
+            python: "3.14"
+            checksum: "5bb0e5fe008a773c3dbcb97ff79cd89e1241464fe9d2f986d52ad8f1b037bd62"
+          - os: windows-latest
+            python: "3.14"
+            checksum: "4c4d49d8738847d9b71ba319e49a5688c93eac0fe6204b1df24e98528dddf39a"
+    env:
+      RELEASE_VERSION: ${{ needs.build.outputs.version }}
+      RELEASE_SHA: ${{ needs.build.outputs.source_sha }}
+      SDIST_SHA256: ${{ needs.build.outputs.sdist_sha256 }}
+      WHEEL_SHA256: ${{ needs.build.outputs.wheel_sha256 }}
+      PYTHON_VERSION: ${{ matrix.python }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.sha }}
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7.6.0
+        with:
+          version: "0.12.5"
+          checksum: ${{ matrix.checksum }}
+          enable-cache: false
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          artifact-ids: ${{ needs.build.outputs.artifact_id }}
+          path: dist
+          digest-mismatch: error
+      - run: uv sync --locked --python "$PYTHON_VERSION"
+        shell: bash
+      - run: uv run --locked python tools/release.py consume
+        env:
+          SCRATCH: ${{ runner.temp }}
+
+  publish-pypi:
+    if: github.ref == 'refs/heads/main'
+    needs: [build, consume]
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          artifact-ids: ${{ needs.build.outputs.artifact_id }}
+          path: dist
+          digest-mismatch: error
+      - name: Verify exact publish bytes
+        id: verify-bytes
+        shell: bash
+        env:
+          DIST_DIR: dist
+          RELEASE_VERSION: ${{ needs.build.outputs.version }}
+          SDIST_NAME: ${{ needs.build.outputs.sdist_name }}
+          WHEEL_NAME: ${{ needs.build.outputs.wheel_name }}
+          SDIST_SHA256: ${{ needs.build.outputs.sdist_sha256 }}
+          WHEEL_SHA256: ${{ needs.build.outputs.wheel_sha256 }}
+        run: |
+          set -euo pipefail
+          [[ "$RELEASE_VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
+          [[ "$SDIST_NAME" == "ziwei-${RELEASE_VERSION}.tar.gz" ]]
+          [[ "$WHEEL_NAME" == "ziwei-${RELEASE_VERSION}-py3-none-any.whl" ]]
+          [[ "$SDIST_SHA256" =~ ^[0-9a-f]{64}$ && "$WHEEL_SHA256" =~ ^[0-9a-f]{64}$ ]]
+          [[ -d "$DIST_DIR" && ! -L "$DIST_DIR" ]]
+          [[ -d "$DIST_DIR/packages" && ! -L "$DIST_DIR/packages" ]]
+          [[ $(find "$DIST_DIR/packages" -mindepth 1 -maxdepth 1 | wc -l) -eq 2 ]]
+          [[ -f "$DIST_DIR/packages/$SDIST_NAME" && ! -L "$DIST_DIR/packages/$SDIST_NAME" ]]
+          [[ -f "$DIST_DIR/packages/$WHEEL_NAME" && ! -L "$DIST_DIR/packages/$WHEEL_NAME" ]]
+          printf '%s  %s\n' "$SDIST_SHA256" "$DIST_DIR/packages/$SDIST_NAME" \
+            "$WHEEL_SHA256" "$DIST_DIR/packages/$WHEEL_NAME" | sha256sum --check --strict
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+        with:
+          repository-url: https://upload.pypi.org/legacy/
+          packages-dir: dist/packages
+          attestations: true
+          skip-existing: false

ziwei-0.1.0/AGENTS.md

@@ -0,0 +1,69 @@
+# Agent 指令
+
+## 范围
+
+本仓是处于初始化阶段的 Python 紫微斗数库。实现功能前先读 `README.md`、`docs/architecture.md`、
+`docs/knowledge.md` 与对应 issue。GitHub issue 记录功能范围与验收条件。
+
+历法与时间（公历与农历互转、闰月、节气时刻、真太阳时）使用 celestial-calendar。本仓负责出生记录与
+口径解析、安星规则、四化与流派变体、十二宫与大限、命盘组合与序列化，以及知识记录与查询。
+
+## 领域契约
+
+- 原始出生记录与解析后的计算输入分开保存。未知时辰、未知性别显式保留；完整命盘入口拒绝缺项，
+  不代填子时或默认性别。
+- 闰月归属、子时换日、换年是三个独立口径，各自为具名选项并进入结果记录。请求的口径不可用时
+  显式失败，不静默换成另一种。
+- 历法算法、流派规则、实现手段分别表达。所选农历算法、支持范围与版本随结果保存。
+- 安星表、四化表与大限规则须注明来源与适用条件。流派有分歧时建模为具名变体，不合成一张无出处的表；
+  未决口径先向作者确认再编码。
+- 天文与历法原值、安星结果、知识解释分开。显示用的星曜名或宫位名不改变计算结果。
+- 先写具体的 celestial 适配。共享抽象只在真实实现或调用方需要时加入。
+
+## Python
+
+完整类型标注；模块与函数 snake_case，类型 PascalCase；两空格缩进。输入、配置、规则与结果默认不可变；
+冻结 dataclass 同时隔离可变成员与调用方持有的数据。偏向普通纯函数与声明式规则表。
+文件读取、原生库初始化、缓存等效果放在所属边界并显式表达。不使用全局可变配置与静默替代。
+
+通用概念使用惯用英语，如 `timezone`、`BirthRecord`、`Gender`；只有术数专有词用拼音，如
+`Ziwei`、`Tianfu`、`Minggong`、`Ganzhi`、`sihua`。专有词枚举提供拼音成员与中文别名
+（`紫微 = ZIWEI`），其他枚举使用英语成员并可提供中文别名。测试与示例优先使用中文别名。
+JSON 中的领域值用中文。
+定义归所属领域模块，入口负责组合。名字与类型承载含义，注释解释原因与约束。公开输入校验在
+`python -O` 下仍须有效。
+
+支持 Python 3.11–3.14。先 `uv sync --locked`，再 `uv run --locked python tools/check.py` 运行与 CI
+相同的检查。配置与工具版本钉在 `pyproject.toml` 与 `uv.lock`；更新依赖时同时修改两者，并在
+最低与最高 Python 版本各验一次。开发包提供完整命盘、JSON保存/恢复、重算与文本盘面，
+并支持独立知识查询。
+
+## 知识与文档
+
+PR 标题与正文、issue、评论与审阅回复使用中文。文档中文。代码标识符、命令、原文引述、
+固定署名与机器识别字段保留原形。
+
+本仓也是知识库。概念、来源记录、规则变体与陈述需要稳定且与语言无关的标识。知识查询不得依赖
+命盘或原生历法初始化。来源状态、前提状态、默认展示资格与命盘匹配分别记录。
+
+可执行规则归所属领域模块，知识从那里引用，参考表由同一来源生成。原文引述、译文与仓内原作说明
+可区分。引文保留来源原有字词、标点与标记，不规范化口诀或古籍原文。保留不确定与前提不全，
+不把它们写成适用结论。
+
+标识、签名、单位、默认值与机器可读规则只有一份来源。本文件是唯一的 agent 指令源；
+读者文档沿上面的路径维护。只在模块有功能时才创建源文件。
+
+## 验证与交付
+
+测试领域边界与独立来源的参考盘例，写明口径配置与容差。序列化往返检验保全，重算与外部参考
+检验不同性质。安星规则以独立来源盘例与边界用例验收：闰月、子时、正月初一与立春之间、立春瞬间两侧、
+支持范围端点、真太阳时跨日。
+
+提交前运行完整检查命令。证明新增检查会拒绝代表性缺陷。来源忠实度、别名、不必要的抽象、
+测试范围缺口与自动结果分开审阅。在 PR 中记录实际执行的命令与未解决的限制。
+
+PR 正文分内容、测试、验证、范围说明四节，末尾署名 `Built by @0xf3cd with <工具> (<模型>).`，
+不写会话链接。提交不带 `Co-Authored-By:`；squash 合并以 PR 正文为提交正文。
+
+示例使用合成数据或适当匿名化的盘例：化名，出生地到省。公开文件与讨论只含项目相关信息。
+提交经维护者批准的签名路径。合并与发布需要明确授权。

ziwei-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0xf3cd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ziwei-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include AGENTS.md uv.lock
+recursive-include .github/workflows *.yml *.yaml
+recursive-include docs *.md *.py *.inv
+recursive-include tests *.py
+recursive-include tools *.py
+prune .review

ziwei-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: ziwei
+Version: 0.1.0
+Summary: 紫微斗数排盘与有出处的知识
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/0xf3cd/ziwei/tree/main/docs
+Project-URL: Repository, https://github.com/0xf3cd/ziwei
+Project-URL: Issues, https://github.com/0xf3cd/ziwei/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: celestial-calendar==0.8.0
+Requires-Dist: tzdata==2026.5
+Dynamic: license-file
+
+# ziwei
+
+Python 紫微斗数排盘与知识库。历法与时间由
+[celestial-calendar](https://github.com/0xf3cd/celestial-calendar) 提供；本仓记录紫微斗数的安星规则、
+四化口径、流派变体与出处，并组织可复现的命盘结果。
+
+目前提供出生记录、显式口径配置、民用时刻消歧、干支基础、celestial 历法适配、解析层
+（公历/农历记录到计算输入）、命宫身宫与十二宫、五行局、28星安星、具名生年四化与大限，
+以及完整命盘组合、带版本的JSON保存/恢复、重算、文本十二宫格和独立知识目录。
+用法见[出生输入](docs/birth.md)、[历法与时间](docs/calendar.md)、[解析层](docs/resolver.md)、
+[命宫身宫与十二宫](docs/palaces.md)、[五行局](docs/bureau.md)、[安星](docs/stars.md)、
+[四化与大限](docs/sihua-decades.md)、[完整命盘与记录](docs/chart.md)和[知识查询](docs/knowledge.md)，
+开发检查与协作约定见[参与开发](docs/contributing.md)。
+首次发布的前置配置、审批与产物核验见[发布准备](docs/releasing.md)。
+
+当前源码为首版候选，版本号不表示已经上架PyPI；已发布版本以
+[发布记录](https://github.com/0xf3cd/ziwei/releases)为准。
+
+## 安装要求
+
+支持Python 3.11–3.14。运行时精确依赖`celestial-calendar==0.8.0`与`tzdata==2026.5`。
+celestial-calendar 0.8.0在PyPI只提供下列原生wheel，没有源码分发包；ziwei自身的纯Python wheel不扩大这个范围：
+
+| 平台 | 架构与最低系统要求 |
+|---|---|
+| macOS | arm64，macOS 14或更新 |
+| Linux | x86_64，glibc 2.26或更新；aarch64，glibc 2.24或更新 |
+| Windows | amd64 |
+
+Intel macOS、Windows ARM64、较旧macOS和musl Linux不在上述制品覆盖范围内，不能依靠pip自动回退源码构建。
+请使用独立虚拟环境；与不同精确版本的celestial-calendar或tzdata显式共装会冲突。
+安装ziwei时，pip也可能将环境中已有的较新celestial-calendar或tzdata降到上述精确版本。
+当前源代码开发安装与检查见[参与开发](docs/contributing.md)，版本与首次发布仍以发布记录为准。
+
+## 首版目标
+
+已知出生时刻与性别，排出可复现的本命盘：
+
+- 保存出生原始记录，显式处理时区与可选的真太阳时，保留解析后的农历年月日时与所用历法算法。
+- 闰月归属、子时换日、换年三个口径作为具名配置，不设静默默认。
+- 安命宫、身宫与十二宫宫干，定五行局，安紫微、天府两系十四主星。
+- 安六吉、六煞、禄存与天马；按所选具名四化表取生年四化。
+- 起大限：顺逆由年干阴阳与性别定，首限起始虚岁由五行局数定。
+- 输出不可变结构、文本盘面与带版本的序列化，保留输入、口径、历法版本与派生结果。
+
+交付任务与验收见 [v0.1.0 milestone](https://github.com/0xf3cd/ziwei/milestone/1)。
+
+## 设计边界
+
+- [仓库结构与计算边界](docs/architecture.md)
+- [知识组织与来源](docs/knowledge.md)
+- [参与开发](docs/contributing.md)
+
+首版同时支持独立查知识：不排盘、不加载原生历法库，也能查到星曜、宫位、四化等概念，
+以及安星规则的流派变体与出处。来源核验状态、适用前提与展示资格分别记录。
+
+通用概念用惯用英语，术数专有词用拼音，枚举另有中文别名；文档、issue 与 PR 使用中文。
+
+## 后续方向
+
+- [杂曜、运限与展示](https://github.com/0xf3cd/ziwei/milestone/2)：杂曜、庙旺利陷、小限与流年流月、
+  飞星四化、格局识别、盘面展示。
+- [解释知识与研究](https://github.com/0xf3cd/ziwei/milestone/3)：有出处的解释知识与前提判别、
+  1972 年前的历史时刻、多源排盘比对、与八字的联合入口。
+
+这些 milestone 记录方向，不设发布日期。每项技术在实现前须明确定义、出处与参考盘例。
+
+## 许可证
+
+[MIT](LICENSE)。

ziwei-0.1.0/README.md

@@ -0,0 +1,70 @@
+# ziwei
+
+Python 紫微斗数排盘与知识库。历法与时间由
+[celestial-calendar](https://github.com/0xf3cd/celestial-calendar) 提供；本仓记录紫微斗数的安星规则、
+四化口径、流派变体与出处，并组织可复现的命盘结果。
+
+目前提供出生记录、显式口径配置、民用时刻消歧、干支基础、celestial 历法适配、解析层
+（公历/农历记录到计算输入）、命宫身宫与十二宫、五行局、28星安星、具名生年四化与大限，
+以及完整命盘组合、带版本的JSON保存/恢复、重算、文本十二宫格和独立知识目录。
+用法见[出生输入](docs/birth.md)、[历法与时间](docs/calendar.md)、[解析层](docs/resolver.md)、
+[命宫身宫与十二宫](docs/palaces.md)、[五行局](docs/bureau.md)、[安星](docs/stars.md)、
+[四化与大限](docs/sihua-decades.md)、[完整命盘与记录](docs/chart.md)和[知识查询](docs/knowledge.md)，
+开发检查与协作约定见[参与开发](docs/contributing.md)。
+首次发布的前置配置、审批与产物核验见[发布准备](docs/releasing.md)。
+
+当前源码为首版候选，版本号不表示已经上架PyPI；已发布版本以
+[发布记录](https://github.com/0xf3cd/ziwei/releases)为准。
+
+## 安装要求
+
+支持Python 3.11–3.14。运行时精确依赖`celestial-calendar==0.8.0`与`tzdata==2026.5`。
+celestial-calendar 0.8.0在PyPI只提供下列原生wheel，没有源码分发包；ziwei自身的纯Python wheel不扩大这个范围：
+
+| 平台 | 架构与最低系统要求 |
+|---|---|
+| macOS | arm64，macOS 14或更新 |
+| Linux | x86_64，glibc 2.26或更新；aarch64，glibc 2.24或更新 |
+| Windows | amd64 |
+
+Intel macOS、Windows ARM64、较旧macOS和musl Linux不在上述制品覆盖范围内，不能依靠pip自动回退源码构建。
+请使用独立虚拟环境；与不同精确版本的celestial-calendar或tzdata显式共装会冲突。
+安装ziwei时，pip也可能将环境中已有的较新celestial-calendar或tzdata降到上述精确版本。
+当前源代码开发安装与检查见[参与开发](docs/contributing.md)，版本与首次发布仍以发布记录为准。
+
+## 首版目标
+
+已知出生时刻与性别，排出可复现的本命盘：
+
+- 保存出生原始记录，显式处理时区与可选的真太阳时，保留解析后的农历年月日时与所用历法算法。
+- 闰月归属、子时换日、换年三个口径作为具名配置，不设静默默认。
+- 安命宫、身宫与十二宫宫干，定五行局，安紫微、天府两系十四主星。
+- 安六吉、六煞、禄存与天马；按所选具名四化表取生年四化。
+- 起大限：顺逆由年干阴阳与性别定，首限起始虚岁由五行局数定。
+- 输出不可变结构、文本盘面与带版本的序列化，保留输入、口径、历法版本与派生结果。
+
+交付任务与验收见 [v0.1.0 milestone](https://github.com/0xf3cd/ziwei/milestone/1)。
+
+## 设计边界
+
+- [仓库结构与计算边界](docs/architecture.md)
+- [知识组织与来源](docs/knowledge.md)
+- [参与开发](docs/contributing.md)
+
+首版同时支持独立查知识：不排盘、不加载原生历法库，也能查到星曜、宫位、四化等概念，
+以及安星规则的流派变体与出处。来源核验状态、适用前提与展示资格分别记录。
+
+通用概念用惯用英语，术数专有词用拼音，枚举另有中文别名；文档、issue 与 PR 使用中文。
+
+## 后续方向
+
+- [杂曜、运限与展示](https://github.com/0xf3cd/ziwei/milestone/2)：杂曜、庙旺利陷、小限与流年流月、
+  飞星四化、格局识别、盘面展示。
+- [解释知识与研究](https://github.com/0xf3cd/ziwei/milestone/3)：有出处的解释知识与前提判别、
+  1972 年前的历史时刻、多源排盘比对、与八字的联合入口。
+
+这些 milestone 记录方向，不设发布日期。每项技术在实现前须明确定义、出处与参考盘例。
+
+## 许可证
+
+[MIT](LICENSE)。