repo_layout_tools

Python 包发布准备

首版 0.1.0 正在准备，本次尚未上传 PyPI。要求 Python 3.10+，无第三方运行依赖。 在本仓根目录可以先安装：

python -m pip install .

正式发布后可使用 python -m pip install estrellio-repo-layout-tools==0.1.0。

wheel 提供 repo_path、host_path、json_config 的现有 Python 接口； 首版不新增安装后的命令行入口，也不会安装 scripts/ 中的 Shell/PowerShell 启动器。

路径推导仍约定目标模块位于项目的 src/ 或 sim/ 下。pip 安装后调用初始化 接口时应显式传入目标路径；省略目标的宿主仓自动发现依赖 vendored/submodule 布局。 部分生成的 runner 仍调用 libs/py_env_tools/scripts/py_env.sh 或 .ps1， 仅用 pip 安装两个库不能替代该布局。通过配置解析到解释器的 runner 则直接调用解释器。

详见 使用说明、测试说明和 发布说明。

repo_layout_tools 提供 AutoScripts 风格仓库的路径推导工具，包括：

• 根据 src/.../*.py 或 sim/.../*.py 模块路径推导仓库根目录
• 生成配置、日志、输出、文档和 runner 脚本路径
• 初始化 _runner.ps1 / _runner.sh 包装脚本和必要目录，并跳过 __init__.py
• 提供跨 Windows / WSL 的 host path 归一化 helper

规范导入方式：

from repo_layout_tools import host_path
from repo_layout_tools import repo_path

例如：

host_path.normalize_host_path(r"D:\Users\shade\Downloads")
host_path.normalize_host_path("/mnt/d/Users/shade/Downloads")

源码仓库的 CLI 入口仍在子模块内：

• scripts/repo_path.py
• scripts/repo_path.sh
• scripts/repo_path.ps1

常用调用方式：

bash libs/repo_layout_tools/scripts/repo_path.sh src

默认初始化只生成 runner 和必要目录，不再创建 *_local.txt。如需创建默认 Local text 配置文件，请显式调用 repo_path.init_config_file(...)。

如果宿主仓想直接暴露仓库级稳定入口，可以复制安装到 scripts/：

bash libs/repo_layout_tools/scripts/install_minimal_repo.sh --repo-root . --force

这会写入：

• scripts/repo_path.py
• scripts/repo_path.sh
• scripts/repo_path.ps1

更细的说明见：

• docs/usage.md
• docs/testing.md

作为 submodule 使用时的常见操作

当这个仓库以 libs/repo_layout_tools 的形式被父仓引用时，需要区分两种状态：

• 父仓当前锁定的 submodule 提交
• 这个子仓自己远端分支上的最新提交

在父仓根目录下，常见操作如下：

# 查看父仓记录的 submodule 状态，以及当前指针差异
git submodule status
git diff --submodule=log -- libs/repo_layout_tools

# 把子仓切回父仓当前锁定的提交
git submodule update --init --recursive

# 把子仓切到它自己 origin/main 的最新提交
git -C libs/repo_layout_tools checkout main
git -C libs/repo_layout_tools pull --ff-only

# 把新的 submodule 指针提交回父仓
git add libs/repo_layout_tools
git commit -m "Update repo_layout_tools submodule"

git submodule update --init --recursive 不是“拉取子仓远端最新代码”，而是“检出父仓当前记录的那个提交”。执行后子仓经常会处于 detached HEAD 状态，这属于正常现象。

仓库布局约定

假设源文件是：

<repo>/src/git_ops/para_notes/para_update_projects.py

则默认派生路径为：

• 配置文件路径：<repo>/src/git_ops/para_notes/para_update_projects_local.txt
• 日志文件：<repo>/logs/git_ops/para_notes/para_update_projects.log
• 输出文件：<repo>/output/git_ops/para_notes/para_update_projects.txt
• 文档文件：<repo>/docs/git_ops/para_notes/para_update_projects.md
• PowerShell runner：<repo>/src/git_ops/para_notes/para_update_projects_runner.ps1
• Bash runner：<repo>/src/git_ops/para_notes/para_update_projects_runner.sh

runner 统一使用 _runner 后缀，而不是直接复用 Python 文件名。

这些是路径推导结果；CLI 初始化不会默认创建 *_local.txt。

通过显式解释器解析回调生成不依赖子模块的 runner，参见独立 runner 示例。