ai-rules-sync 1.0.0__tar.gz

ai_rules_sync-1.0.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: ai-rules-sync
+Version: 1.0.0
+Summary: 跨平台同步 AI 编程 Agent 的中文代码注释规范
+Author: AI Rules Sync contributors
+License-Expression: MIT
+Keywords: ai,agent,rules,codex,claude,qoder
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# AI Rules Sync
+
+AI Rules Sync 是一个只依赖 Python 标准库的跨平台命令行工具，用一份中文代码注释规范同步多个 AI 编程 Agent 的全局规则。
+
+## 使用方式
+
+无需克隆仓库或安装 Python 包，直接使用 `uvx`：
+
+```sh
+# 查看当前电脑检测到的 Agent
+uvx ai-rules-sync --list
+
+# 同步规则
+uvx ai-rules-sync
+
+# 预览变更，不写入文件
+uvx ai-rules-sync --dry-run
+
+# 检查是否需要同步；需要同步时返回退出码 1
+uvx ai-rules-sync --check
+
+# 只同步指定 Agent
+uvx ai-rules-sync --agents codex,claude
+```
+
+也可以指定配置目录：
+
+```sh
+uvx ai-rules-sync --config-dir /path/to/config
+```
+
+## 支持的 Agent
+
+内置支持 Codex、Claude Code、Hermes 和 Qoder。工具会自动检测已安装的 Agent；未检测到的 Agent 会跳过，不会创建配置目录。使用 `--agents` 可以显式初始化指定 Agent。
+
+同步过程只替换受管标记内的规则内容，会保留 Agent 原有配置，并在写入前创建备份。
+
+## 本机配置
+
+共享规则随 PyPI wheel 一起发布。安装后的本机覆盖配置和备份默认保存在：
+
+- macOS/Linux：`~/.config/ai-rules-sync/`
+- Windows：`%APPDATA%\\ai-rules-sync\\`
+
+也可以通过 `AI_RULES_HOME` 或 `--config-dir` 指定配置目录。完整的配置格式、安全策略和开发说明请参阅项目中的 [使用说明书](docs/USAGE.md)。

ai_rules_sync-1.0.0/README.md

@@ -0,0 +1,45 @@
+# AI Rules Sync
+
+AI Rules Sync 是一个只依赖 Python 标准库的跨平台命令行工具，用一份中文代码注释规范同步多个 AI 编程 Agent 的全局规则。
+
+## 使用方式
+
+无需克隆仓库或安装 Python 包，直接使用 `uvx`：
+
+```sh
+# 查看当前电脑检测到的 Agent
+uvx ai-rules-sync --list
+
+# 同步规则
+uvx ai-rules-sync
+
+# 预览变更，不写入文件
+uvx ai-rules-sync --dry-run
+
+# 检查是否需要同步；需要同步时返回退出码 1
+uvx ai-rules-sync --check
+
+# 只同步指定 Agent
+uvx ai-rules-sync --agents codex,claude
+```
+
+也可以指定配置目录：
+
+```sh
+uvx ai-rules-sync --config-dir /path/to/config
+```
+
+## 支持的 Agent
+
+内置支持 Codex、Claude Code、Hermes 和 Qoder。工具会自动检测已安装的 Agent；未检测到的 Agent 会跳过，不会创建配置目录。使用 `--agents` 可以显式初始化指定 Agent。
+
+同步过程只替换受管标记内的规则内容，会保留 Agent 原有配置，并在写入前创建备份。
+
+## 本机配置
+
+共享规则随 PyPI wheel 一起发布。安装后的本机覆盖配置和备份默认保存在：
+
+- macOS/Linux：`~/.config/ai-rules-sync/`
+- Windows：`%APPDATA%\\ai-rules-sync\\`
+
+也可以通过 `AI_RULES_HOME` 或 `--config-dir` 指定配置目录。完整的配置格式、安全策略和开发说明请参阅项目中的 [使用说明书](docs/USAGE.md)。

ai_rules_sync-1.0.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ai-rules-sync"
+version = "1.0.0"
+description = "跨平台同步 AI 编程 Agent 的中文代码注释规范"
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+authors = [{ name = "AI Rules Sync contributors" }]
+keywords = ["ai", "agent", "rules", "codex", "claude", "qoder"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.scripts]
+ai-rules-sync = "ai_rules_sync.core:main"
+
+[tool.uv]
+# 明确这是可安装的包项目，便于使用 uv run、uv sync 和 uv build。
+package = true
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ai_rules_sync = ["data/*.md"]
+
+[tool.unittest]
+start-directory = "tests"

ai_rules_sync-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ai_rules_sync-1.0.0/src/ai_rules_sync/__init__.py

@@ -0,0 +1,3 @@
+"""跨平台 AI 编程 Agent 中文注释规范同步工具。"""
+
+__version__ = "1.0.0"

ai_rules_sync-1.0.0/src/ai_rules_sync/__main__.py

@@ -0,0 +1,8 @@
+"""支持 ``python -m ai_rules_sync`` 启动 CLI。"""
+
+from .core import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

ai_rules_sync-1.0.0/src/ai_rules_sync/core.py

@@ -0,0 +1,307 @@
+#!/usr/bin/env python3
+"""跨平台同步中文注释规范；自动跳过未检测到的 Agent，支持自定义全局入口。"""
+
+import argparse
+import datetime
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import sys
+import tempfile
+
+from . import __version__
+
+BEGIN = '<!-- ai-rules:chinese-comments:begin -->'
+END = '<!-- ai-rules:chinese-comments:end -->'
+PACKAGE_DIR = Path(__file__).resolve().parent
+PACKAGED_RULES = PACKAGE_DIR / 'data' / 'AGENTS.md'
+
+
+def default_root():
+    """返回配置与备份目录；兼容源码运行和已安装 wheel 的两种布局。"""
+    configured = os.environ.get('AI_RULES_HOME')
+    if configured:
+        return Path(configured).expanduser()
+    source_root = PACKAGE_DIR.parents[1] / 'config'
+    if (source_root / 'AGENTS.md').is_file():
+        return source_root
+    if os.name == 'nt':
+        base = Path(os.environ.get('APPDATA', Path.home() / 'AppData' / 'Roaming'))
+    else:
+        base = Path(os.environ.get('XDG_CONFIG_HOME', Path.home() / '.config'))
+    return base / 'ai-rules-sync'
+
+
+# 源码仓库优先使用项目内 config/；安装后使用用户配置目录保存本机覆盖项和备份，
+# 共享规则本身从随 wheel 发布的 data/AGENTS.md 读取。
+ROOT = default_root()
+BUILTINS = {
+    'codex': {'path': '~/.codex/AGENTS.md', 'home_env': 'CODEX_HOME',
+              'relative': 'AGENTS.md', 'commands': ['codex']},
+    'claude': {'path': '~/.claude/CLAUDE.md', 'home_env': 'CLAUDE_CONFIG_DIR',
+               'relative': 'CLAUDE.md', 'commands': ['claude']},
+    'hermes': {'path': '~/.hermes/SOUL.md', 'home_env': 'HERMES_HOME',
+               'relative': 'SOUL.md', 'commands': ['hermes']},
+    'qoder': {'path': '~/.qoder/rules/ai-chinese-comments.md',
+              'commands': ['qoder', 'qodercli'], 'format': 'qoder'},
+}
+
+
+def system_name():
+    """返回配置使用的平台名称；WSL 按独立的 Linux 环境处理。"""
+    return 'windows' if os.name == 'nt' else ('macos' if sys.platform == 'darwin' else 'linux')
+
+
+def expand_path(value, home, env, base):
+    """展开当前用户目录及两种环境变量写法；相对路径基于配置目录。"""
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError('入口路径必须是非空字符串')
+    def substitute(match):
+        """变量不存在时报告错误，避免创建名称中带变量占位符的目录。"""
+        key = next(part for part in match.groups() if part is not None)
+        if not env.get(key):
+            raise ValueError('环境变量未设置：' + key)
+        return env[key]
+    value = re.sub(r'\$\{([^}]+)\}|\$([A-Za-z_][A-Za-z0-9_]*)|%([^%]+)%', substitute, value)
+    if value == '~':
+        return home
+    if value.startswith(('~/', '~\\')):
+        return home / value[2:]
+    path = Path(value)
+    return path if path.is_absolute() else base / path
+
+
+def load_agents(root):
+    """读取可共享的配置，再合并本机覆盖项；拒绝旧版绝对路径配置。"""
+    agents = {name: dict(spec, enabled='auto', format=spec.get('format', 'markdown'))
+              for name, spec in BUILTINS.items()}
+    for filename in ['targets.json', 'targets.local.json']:
+        path = root / filename
+        if not path.exists():
+            continue
+        config = json.loads(path.read_text(encoding='utf-8-sig'))
+        if config.get('version') != 2 or not isinstance(config.get('agents'), dict):
+            raise ValueError(filename + ' 必须使用 version: 2；请勿沿用旧版机器绝对路径配置')
+        for name, entry in config['agents'].items():
+            if not re.fullmatch(r'[a-z][a-z0-9_-]*', name) or not isinstance(entry, dict):
+                raise ValueError('Agent 名称或配置无效：' + str(name))
+            extra = set(entry) - {'enabled', 'path', 'commands', 'format'}
+            if extra:
+                raise ValueError('未知配置字段：' + name + ': ' + ', '.join(extra))
+            spec = agents.setdefault(name, {'enabled': 'auto', 'format': 'markdown', 'commands': []})
+            spec.update(entry)
+            if 'path' in entry:
+                spec.pop('home_env', None)
+                spec.pop('relative', None)
+    for name, spec in agents.items():
+        enabled = spec['enabled']
+        if not (enabled == 'auto' or type(enabled) is bool) or spec['format'] not in ('markdown', 'qoder'):
+            raise ValueError('启用方式或格式无效：' + name)
+        if 'path' not in spec or not isinstance(spec['commands'], list) or not all(isinstance(x, str) for x in spec['commands']):
+            raise ValueError('缺少 path 或 commands 格式无效：' + name)
+    return agents
+
+
+def resolve_target(name, spec, root, home, env, platform, which):
+    """计算本机入口并检测配置目录、命令或已知 GUI 安装位置。"""
+    value = spec['path']
+    if isinstance(value, dict):
+        value = value.get(platform, value.get('default'))
+        if value is None:
+            return None, '此平台未配置入口'
+    env_name = spec.get('home_env')
+    if env_name and env.get(env_name):
+        config_home = expand_path(env[env_name], home, env, root)
+        path = config_home / spec['relative']
+    else:
+        path = expand_path(value, home, env, root)
+        config_home = path.parent.parent if spec['format'] == 'qoder' else path.parent
+    if path.exists():
+        return path, '已有规则文件'
+    if config_home.is_dir():
+        return path, '已有配置目录'
+    if any(which(command) for command in spec['commands']):
+        return path, '检测到命令'
+    if platform == 'macos' and name in ('codex', 'qoder'):
+        app = 'Codex.app' if name == 'codex' else 'Qoder.app'
+        if any((folder / app).exists() for folder in [Path('/Applications'), home / 'Applications']):
+            return path, '检测到桌面应用'
+    if platform == 'windows' and name == 'qoder' and env.get('LOCALAPPDATA'):
+        if (Path(env['LOCALAPPDATA']) / 'Programs/Qoder/Qoder.exe').exists():
+            return path, '检测到桌面应用'
+    return path, ''
+
+
+def replace_section(original, content):
+    """替换本工具的规则段，保留其他文字、BOM 和已有换行形式。"""
+    newline = '\r\n' if '\r\n' in original else '\n'
+    block = BEGIN + newline + content.replace('\r\n', '\n').strip().replace('\n', newline) + newline + END
+    if BEGIN not in original and END not in original:
+        separator = '' if not original else (newline if original.endswith('\n') else newline * 2)
+        return original + separator + block + newline
+    if original.count(BEGIN) != 1 or original.count(END) != 1:
+        raise ValueError('受管段标记重复或缺失，请先修复')
+    start, end = original.index(BEGIN), original.index(END)
+    if end < start:
+        raise ValueError('受管段标记顺序错误')
+    return original[:start] + block + original[end + len(END):]
+
+
+def snapshot(path):
+    """读取原始字节；用 None 区分不存在和空文件，并拒绝覆盖符号链接。"""
+    if path.is_symlink():
+        raise ValueError('入口是符号链接，请在本机配置中明确其目标：' + str(path))
+    return path.read_bytes() if path.exists() else None
+
+
+def atomic_write(path, content, mode):
+    """同目录写入并原子替换；Windows 沿用目录权限，POSIX 保留文件模式。"""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, name = tempfile.mkstemp(prefix='.ai-rules-', dir=path.parent)
+    try:
+        with os.fdopen(fd, 'wb') as stream:
+            stream.write(content)
+        if os.name != 'nt':
+            os.chmod(name, mode)
+        os.replace(name, path)
+    finally:
+        if os.path.exists(name):
+            os.unlink(name)
+
+
+def apply_changes(changes, root):
+    """先完整备份再写入；失败时回滚尚未被其他程序修改的已写文件。"""
+    stamp = datetime.datetime.now().strftime('%Y%m%d-%H%M%S-%f')
+    backup = root / 'backups' / stamp
+    backup.mkdir(parents=True, mode=0o700)
+    manifest = []
+    for name, path, old, new in changes:
+        if snapshot(path) != old:
+            raise RuntimeError('文件已被其他程序修改：' + str(path))
+        filename = hashlib.sha256(str(path).encode()).hexdigest()[:12] + '-' + path.name
+        mode = path.stat().st_mode & 0o777 if old is not None else 0o600
+        if old is not None:
+            shutil.copy2(path, backup / filename)
+        manifest.append({'path': str(path), 'existed': old is not None,
+                         'backup': filename if old is not None else None, 'mode': mode})
+    (backup / 'manifest.json').write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + '\n', encoding='utf-8')
+    written = []
+    try:
+        for item, record in zip(changes, manifest):
+            name, path, old, new = item
+            if snapshot(path) != old:
+                raise RuntimeError('文件已被其他程序修改：' + str(path))
+            atomic_write(path, new, record['mode'])
+            written.append((item, record))
+            print('已同步 ' + name + ': ' + str(path))
+    except Exception:
+        for (name, path, old, new), record in reversed(written):
+            try:
+                if snapshot(path) != new:
+                    print('回滚保留并发修改：' + str(path), file=sys.stderr)
+                elif old is None:
+                    path.unlink()
+                else:
+                    atomic_write(path, old, record['mode'])
+            except (OSError, ValueError) as error:
+                print('回滚失败，请使用备份恢复：' + str(error), file=sys.stderr)
+        print('备份：' + str(backup), file=sys.stderr)
+        raise
+    print('备份：' + str(backup))
+
+
+def main(argv=None, root=ROOT):
+    """检测、预览、检查或同步入口；显式选择允许为指定 Agent 初始化配置。"""
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--version', action='version', version='%(prog)s ' + __version__)
+    parser.add_argument('--config-dir', type=Path,
+                        help='规则与 targets.json 所在目录；默认使用项目 config/、AI_RULES_HOME 或用户配置目录')
+    parser.add_argument('--agents', help='只同步指定 Agent，逗号分隔；可显式初始化未检测到的工具')
+    modes = parser.add_mutually_exclusive_group()
+    modes.add_argument('--list', action='store_true', help='仅列出检测结果')
+    modes.add_argument('--check', action='store_true', help='检查一致性，需同步时退出码为 1')
+    modes.add_argument('--dry-run', action='store_true', help='预览变更，不写入')
+    args = parser.parse_args(argv)
+    if args.config_dir is not None:
+        root = args.config_dir.expanduser().resolve()
+    agents = load_agents(root)
+    selected = {x.strip() for x in args.agents.split(',') if x.strip()} if args.agents is not None else None
+    if selected is not None and (not selected or selected - agents.keys()):
+        raise ValueError('指定了空列表或未登记的 Agent；请先在 targets.json 中配置')
+    targets = []
+    home, env, platform = Path.home(), dict(os.environ), system_name()
+    print('平台：' + platform + '；当前用户目录：' + str(home))
+    for name, spec in agents.items():
+        if selected is not None and name not in selected:
+            continue
+        if selected is None and spec['enabled'] is False:
+            print('跳过 ' + name + '：已禁用')
+            continue
+        path, reason = resolve_target(name, spec, root, home, env, platform, shutil.which)
+        if path is None:
+            if selected or spec['enabled'] is True:
+                raise ValueError(name + '：' + reason)
+            print('跳过 ' + name + '：' + reason)
+            continue
+        enabled = selected is not None or spec['enabled'] is True or bool(reason)
+        print(('启用 ' if enabled else '跳过 ') + name + ': ' + str(path) + '（' + (reason or ('显式启用' if enabled else '未检测到')) + '）')
+        if enabled:
+            targets.append((name, path, spec))
+    if args.list:
+        return 0
+    if not targets:
+        print('没有可同步的 Agent，未创建任何配置。')
+        return 1 if args.check else 0
+    rules_path = root / 'AGENTS.md'
+    if not rules_path.is_file() and PACKAGED_RULES.is_file():
+        rules_path = PACKAGED_RULES
+    rules = rules_path.read_text(encoding='utf-8-sig').strip()
+    if not rules or BEGIN in rules or END in rules:
+        raise ValueError('共享规范为空或包含保留的受管段标记')
+    protected = {str(path.resolve()) for path in [rules_path, root / 'sync.py', root / 'targets.json', root / 'targets.local.json']}
+    seen, changes = set(), []
+    for name, path, spec in targets:
+        identity = str(path.resolve())
+        if os.name == 'nt':
+            identity = os.path.normcase(identity)
+            protected = {os.path.normcase(x) for x in protected}
+        if identity in seen or identity in protected:
+            raise ValueError('入口重复或与工具自身文件冲突：' + str(path))
+        seen.add(identity)
+        # 非空覆盖文件优先级更高，提前提示，避免把未加载误判为同步成功。
+        if name == 'codex' and path.name == 'AGENTS.md':
+            override = path.with_name('AGENTS.override.md')
+            if override.exists() and override.read_bytes().strip():
+                raise ValueError('Codex 存在非空 AGENTS.override.md，请将本机 path 指向实际生效的入口')
+        old = snapshot(path)
+        text = old.decode('utf-8') if old is not None else ''
+        if spec['format'] == 'qoder' and text and BEGIN not in text:
+            raise ValueError('同名 Qoder 规则不是本工具创建，已停止：' + str(path))
+        new = replace_section(text, rules)
+        if spec['format'] == 'qoder' and not text:
+            new = '---\ntrigger: always_on\nalwaysApply: true\n---\n\n' + new
+        data = new.encode('utf-8')
+        print(('OK ' if old == data else '需同步 ') + name)
+        if old != data:
+            changes.append((name, path, old, data))
+    if args.check:
+        return 1 if changes else 0
+    if args.dry_run:
+        print('预览完成，未写入；待更新入口数：' + str(len(changes)))
+        return 0
+    if changes:
+        apply_changes(changes, root)
+    else:
+        print('全部选中入口已同步，无需修改。')
+    return 0
+
+
+if __name__ == '__main__':
+    try:
+        raise SystemExit(main())
+    except (ValueError, OSError, RuntimeError) as error:
+        print('错误：' + str(error), file=sys.stderr)
+        raise SystemExit(2)

ai_rules_sync-1.0.0/src/ai_rules_sync/data/AGENTS.md

@@ -0,0 +1,301 @@
+# 语言与代码注释规范
+
+## 默认语言
+- 用户的母语是中文。默认使用简体中文交流。
+- 新增或修改的代码注释、文档注释均使用简体中文，无需用户再次提醒。
+- 代码标识符、API 名称、协议字段、文档标签和工具指令保持原有形式，例如 @param、@return、TODO、eslint-disable；其中的解释文字使用中文。
+
+## 注释必须与代码同时完成
+- 编写、修改或重构代码时，同步完成必要的中文注释。
+- 不得将聊天中的解释当作源码注释；必要说明必须写入代码文件。
+- 修改代码行为时，同步更新相关注释，避免注释与实现不一致。
+
+## 注释覆盖范围
+- 新增或实质修改的模块、类、接口、函数和方法，应说明其用途；下述显而易见的简单代码除外。
+- 对外接口和复杂函数，按需说明参数含义、返回值、异常、副作用、单位、取值范围和边界条件。
+- 复杂分支、业务规则、算法、状态转换、并发控制、重试、缓存和兼容性处理，应说明设计原因及关键约束。
+- 具有业务含义的常量、位运算、协议字段和特殊数值，应解释其含义。
+- 简单赋值、直观的 getter/setter 和显而易见的语句无需逐行注释。
+
+## 遵循对应语言的规范
+- 自动识别代码语言、框架和项目的文档工具，使用其惯用注释形式。
+- 下方列出的 20 种语言是常见工程覆盖集合，不是严格的语言排行榜；选择参考了近期开发者调查中的主流语言范围。项目已有规范优先于本表。
+- 已有项目保持注释结构、缩进和文档标签风格一致，自然语言说明默认使用中文。
+- 未列出的语言采用其通行规范，不生搬硬套其他语言的格式。
+- 严格 JSON 等不支持注释的格式，不插入非法注释；必要说明放在对应文档中。
+
+## 20 种常见语言的注释规范与示例
+
+以下示例只展示注释写法；新增代码时按项目实际的 formatter、lint、文档生成器和版本约定调整。示例中的自然语言必须保持简体中文，语言要求的标签、关键字和 API 名称保持原样。
+
+### 1. C
+- 行注释使用 `//`，块注释使用 `/* ... */`；公共头文件可使用 Doxygen 的 `/** ... */`。
+
+```c
+/**
+ * 根据用户编号读取用户信息。
+ *
+ * @param user_id 用户编号，必须大于 0。
+ * @return 成功返回用户指针，失败返回 NULL。
+ */
+struct User *user_find(int user_id);
+```
+
+### 2. C++
+- 普通逻辑使用 `//`；公共类、函数和模板优先使用 Doxygen 的 `///` 或 `/** ... */`。
+
+```cpp
+/// 将输入值限制在闭区间 [min, max] 内。
+template <typename T>
+T clamp_value(T value, T min, T max) {
+  return value < min ? min : (value > max ? max : value);
+}
+```
+
+### 3. C#
+- 普通说明使用 `//`；公共 API 使用 XML 文档注释 `///`，并保留 `<summary>`、`<param>`、`<returns>` 等标签。
+
+```csharp
+/// <summary>按编号加载订单。</summary>
+/// <param name="orderId">订单编号。</param>
+/// <returns>订单不存在时返回 <c>null</c>。</returns>
+public Order? LoadOrder(long orderId)
+{
+    return null;
+}
+```
+
+### 4. Java
+- 普通说明使用 `//` 或 `/* ... */`；公共 API 使用 Javadoc `/** ... */`，标签使用 `@param`、`@return`、`@throws`。
+
+```java
+/**
+ * 根据订单编号查询订单。
+ *
+ * @param orderId 订单编号。
+ * @return 找不到订单时返回 {@code null}。
+ */
+Order findOrder(long orderId) {
+    return null;
+}
+```
+
+### 5. Kotlin
+- 普通说明使用 `//`；公共 API 使用 KDoc `/** ... */`，支持 `@param`、`@return`、`@throws` 和 Markdown。
+
+```kotlin
+/**
+ * 根据编号查询订单；找不到时返回 null。
+ *
+ * @param orderId 订单编号。
+ */
+fun findOrder(orderId: Long): Order? {
+    return null
+}
+```
+
+### 6. Swift
+- 普通说明使用 `//`；公共 API 使用 Swift 文档注释 `///` 或 `/** ... */`，参数说明使用 `- Parameter`，返回值使用 `- Returns`。
+
+```swift
+/// 根据编号加载订单。
+/// - Parameter orderID: 订单编号。
+/// - Returns: 找不到订单时返回 `nil`。
+func loadOrder(orderID: Int) -> Order? {
+    return nil
+}
+```
+
+### 7. JavaScript
+- 普通逻辑使用 `//`；跨模块函数、类和复杂对象使用 JSDoc `/** ... */`，标签使用 `@param`、`@returns`、`@throws`。
+
+```javascript
+/**
+ * 将字符串解析为非负整数。
+ *
+ * @param {string} text 待解析文本。
+ * @returns {number|null} 无法解析时返回 null。
+ */
+function parseCount(text) {
+  return null;
+}
+```
+
+### 8. TypeScript
+- 普通说明使用 `//`；导出的类型、接口、函数和类使用 TSDoc/JSDoc，类型标签应与实际类型一致。
+
+```typescript
+/** 根据用户编号获取用户；不存在时返回 undefined。 */
+export function getUser(userId: string): User | undefined {
+  return undefined;
+}
+```
+
+### 9. Python
+- 行内说明使用 `#`；模块、类和公共函数使用 PEP 257 风格 docstring，复杂 API 可使用 Google、NumPy 或项目既有风格。
+
+```python
+def retry_delay(failure_count: int) -> float:
+    """根据连续失败次数计算重试间隔。
+
+    Args:
+        failure_count: 已连续失败的次数，从 1 开始。
+
+    Returns:
+        以秒为单位的等待时间，最大为 32 秒。
+    """
+    return min(2 ** max(failure_count - 1, 0), 32)
+```
+
+### 10. Go
+- 普通说明使用 `//`；导出的包、类型、函数和变量的文档注释应以被说明的名称开头，块注释只用于确有需要的多行说明。
+
+```go
+// ParseCount 将文本解析为非负整数；格式错误时返回错误。
+func ParseCount(text string) (int, error) {
+    return 0, nil
+}
+```
+
+### 11. Rust
+- 普通说明使用 `//`；公开项使用 rustdoc `///`，模块或 crate 级说明使用 `//!`，可用 Markdown 和 `# Panics`、`# Errors` 等章节。
+
+```rust
+/// 根据连续失败次数计算重试间隔。
+///
+/// 返回值单位为秒，最大不超过 32 秒。
+pub fn retry_delay(failure_count: u32) -> u64 {
+    0
+}
+```
+
+### 12. Ruby
+- 普通说明使用 `#`；公共类和方法沿用 RDoc/YARD 风格，可用 `@param`、`@return` 和 `@raise`。
+
+```ruby
+# 根据连续失败次数计算重试间隔。
+# @param failure_count [Integer] 连续失败次数
+# @return [Integer] 等待秒数，最大为 32
+def retry_delay(failure_count)
+  0
+end
+```
+
+### 13. PHP
+- 普通说明使用 `//` 或 `/* ... */`；公共函数、类和属性使用 PHPDoc `/** ... */`，标签使用 `@param`、`@return`、`@throws`。
+
+```php
+/**
+ * 根据用户编号加载用户。
+ *
+ * @param int $userId 用户编号
+ * @return User|null 找不到时返回 null
+ */
+function findUser(int $userId): ?User
+{
+    return null;
+}
+```
+
+### 14. Dart
+- 普通说明使用 `//`；公共 API 优先使用 `///` 文档注释，Flutter/Dart API 可用 Markdown 和 `{@template ...}` 等项目约定标签。
+
+```dart
+/// 根据编号加载订单；找不到时返回 `null`。
+Order? loadOrder(int orderId) => null;
+```
+
+### 15. Scala
+- 普通说明使用 `//`；公共 API 使用 Scaladoc `/** ... */`，参数和返回值使用 `@param`、`@return`。
+
+```scala
+/**
+  * 根据编号加载订单。
+  *
+  * @param orderId 订单编号
+  * @return 找不到时返回 None
+  */
+def loadOrder(orderId: Long): Option[Order] = {
+  None
+}
+```
+
+### 16. R
+- 普通说明使用 `#`；包和公共函数优先使用 roxygen2 `#'`，通过 `@param`、`@return`、`@export` 生成文档。
+
+```r
+#' 根据编号加载订单
+#' @param order_id 订单编号
+#' @return 订单对象或 NULL
+#' @export
+load_order <- function(order_id) {
+  NULL
+}
+```
+
+### 17. SQL
+- 单行说明使用 `--`，多行说明使用 `/* ... */`；迁移和复杂查询应解释业务规则、关联条件及特殊过滤。
+
+```sql
+-- 只统计已支付订单，避免把取消订单计入收入。
+SELECT customer_id, SUM(amount) AS total_amount
+FROM orders
+WHERE status = 'paid'
+GROUP BY customer_id;
+```
+
+### 18. Bash / Shell
+- 使用 `#`；脚本入口、函数、危险命令、环境变量约束和退出码应说明，避免把每条简单命令逐行翻译。
+
+```bash
+# 清理超过保留天数的临时文件；失败时返回非零状态。
+cleanup_temp_files() {
+  find "$TMP_DIR" -type f -mtime +"$RETENTION_DAYS" -delete
+}
+```
+
+### 19. PowerShell
+- 单行说明使用 `#`，多行说明使用 `<# ... #>`；高级函数使用 comment-based help 的 `.SYNOPSIS`、`.PARAMETER`、`.OUTPUTS`。
+
+```powershell
+function Get-Order {
+    <#
+    .SYNOPSIS
+    根据编号加载订单。
+    .PARAMETER OrderId
+    订单编号。
+    #>
+    param([long]$OrderId)
+}
+```
+
+### 20. Lua
+- 单行说明使用 `--`，多行说明使用 `--[[ ... ]]`；公共模块函数可按项目约定使用 LDoc 注释标签。
+
+```lua
+--- 根据编号加载订单；找不到时返回 nil。
+-- @param order_id number 订单编号
+-- @return table|nil 订单对象或 nil
+function M.load_order(order_id)
+  return nil
+end
+```
+
+### 多语言文件和模板
+- HTML/XML 使用 `<!-- ... -->`；CSS 使用 `/* ... */`；JSON、YAML、TOML 和多数纯数据格式不支持注释，不要插入非法注释。
+- Vue、Svelte、JSX/TSX 等混合文件必须根据注释所在区域使用对应语法；不要把 HTML 注释放进 JavaScript 表达式，也不要把 JavaScript 注释放进 JSON 数据。
+- SQL、Shell、配置模板和迁移脚本中的注释必须说明环境、执行顺序、不可逆操作和兼容性约束。
+
+## 注释表达方式
+- 使用简洁、准确的中文，优先解释用途、原因、约束和边界。
+- 不机械翻译代码，不写“声明变量”“进入循环”等无信息量注释。
+- 不编造业务原因；无法从上下文确定时明确说明不确定之处。
+- 不添加无必要的作者、日期、修改流水账或装饰性分隔线。
+- 不为补注释修改无关代码，不手动修改生成文件或第三方源码，保留许可证声明。
+
+## 完成前自检
+- 检查本次新增或修改的代码是否已补充必要注释。
+- 检查说明文字是否为简体中文。
+- 检查注释语法是否符合当前语言及文档工具要求。
+- 检查注释是否与实际实现一致。
+- 发现遗漏时，在交付前主动补齐，无需等待用户提醒。

ai_rules_sync-1.0.0/src/ai_rules_sync.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: ai-rules-sync
+Version: 1.0.0
+Summary: 跨平台同步 AI 编程 Agent 的中文代码注释规范
+Author: AI Rules Sync contributors
+License-Expression: MIT
+Keywords: ai,agent,rules,codex,claude,qoder
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# AI Rules Sync
+
+AI Rules Sync 是一个只依赖 Python 标准库的跨平台命令行工具，用一份中文代码注释规范同步多个 AI 编程 Agent 的全局规则。
+
+## 使用方式
+
+无需克隆仓库或安装 Python 包，直接使用 `uvx`：
+
+```sh
+# 查看当前电脑检测到的 Agent
+uvx ai-rules-sync --list
+
+# 同步规则
+uvx ai-rules-sync
+
+# 预览变更，不写入文件
+uvx ai-rules-sync --dry-run
+
+# 检查是否需要同步；需要同步时返回退出码 1
+uvx ai-rules-sync --check
+
+# 只同步指定 Agent
+uvx ai-rules-sync --agents codex,claude
+```
+
+也可以指定配置目录：
+
+```sh
+uvx ai-rules-sync --config-dir /path/to/config
+```
+
+## 支持的 Agent
+
+内置支持 Codex、Claude Code、Hermes 和 Qoder。工具会自动检测已安装的 Agent；未检测到的 Agent 会跳过，不会创建配置目录。使用 `--agents` 可以显式初始化指定 Agent。
+
+同步过程只替换受管标记内的规则内容，会保留 Agent 原有配置，并在写入前创建备份。
+
+## 本机配置
+
+共享规则随 PyPI wheel 一起发布。安装后的本机覆盖配置和备份默认保存在：
+
+- macOS/Linux：`~/.config/ai-rules-sync/`
+- Windows：`%APPDATA%\\ai-rules-sync\\`
+
+也可以通过 `AI_RULES_HOME` 或 `--config-dir` 指定配置目录。完整的配置格式、安全策略和开发说明请参阅项目中的 [使用说明书](docs/USAGE.md)。

ai_rules_sync-1.0.0/src/ai_rules_sync.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+src/ai_rules_sync/__init__.py
+src/ai_rules_sync/__main__.py
+src/ai_rules_sync/core.py
+src/ai_rules_sync.egg-info/PKG-INFO
+src/ai_rules_sync.egg-info/SOURCES.txt
+src/ai_rules_sync.egg-info/dependency_links.txt
+src/ai_rules_sync.egg-info/entry_points.txt
+src/ai_rules_sync.egg-info/top_level.txt
+src/ai_rules_sync/data/AGENTS.md
+tests/test_core.py

ai_rules_sync-1.0.0/src/ai_rules_sync.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ai_rules_sync-1.0.0/src/ai_rules_sync.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ai-rules-sync = ai_rules_sync.core:main

ai_rules_sync-1.0.0/src/ai_rules_sync.egg-info/top_level.txt

@@ -0,0 +1 @@
+ai_rules_sync

ai_rules_sync-1.0.0/tests/test_core.py

@@ -0,0 +1,202 @@
+"""验证跨平台路径、不同 Agent 组合、配置保留与失败恢复；不访问真实 Agent 配置。"""
+
+import contextlib
+import io
+import json
+import os
+from pathlib import Path, PureWindowsPath
+import sys
+import tempfile
+import unittest
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / 'src'))
+from ai_rules_sync import core as sync
+
+
+class PortableSyncTests(unittest.TestCase):
+    """在临时用户目录中验证同步行为，隔离机器实际安装的 Agent。"""
+
+    def setUp(self):
+        """创建含中文和空格的独立工具目录与用户目录。"""
+        self.temp = tempfile.TemporaryDirectory()
+        self.addCleanup(self.temp.cleanup)
+        self.base = Path(self.temp.name)
+        self.root = self.base / '共享规则 tool'
+        self.home = self.base / '用户 home'
+        self.root.mkdir()
+        self.home.mkdir()
+        (self.root / 'AGENTS.md').write_text('# 中文规则\n注释使用简体中文。\n', encoding='utf-8')
+        self.config({})
+
+    def config(self, agents, filename='targets.json'):
+        """写入当前测试的 Agent 配置。"""
+        (self.root / filename).write_text(json.dumps({'version': 2, 'agents': agents}), encoding='utf-8')
+
+    def run_sync(self, args=None, platform='linux', env=None, which=None):
+        """用模拟的系统与用户环境运行工具，捕获输出。"""
+        with patch.object(sync.Path, 'home', return_value=self.home), \
+                patch.object(sync, 'system_name', return_value=platform), \
+                patch.dict(os.environ, env or {}, clear=True), \
+                patch.object(sync.shutil, 'which', side_effect=which or (lambda name: None)), \
+                contextlib.redirect_stdout(io.StringIO()):
+            return sync.main(args or [], root=self.root)
+
+    def test_missing_agents_create_nothing(self):
+        """没有安装痕迹时，跳过所有 Agent，不产生规则目录。"""
+        self.assertEqual(self.run_sync(), 0)
+        self.assertEqual(list(self.home.iterdir()), [])
+        self.assertFalse((self.root / 'backups').exists())
+        self.assertEqual(self.run_sync(['--check']), 1)
+
+    def test_subset_and_idempotency(self):
+        """只安装部分 Agent 时，仅同步对应入口且重复执行无变更。"""
+        for name in ['.codex', '.hermes']:
+            (self.home / name).mkdir()
+        self.assertEqual(self.run_sync(), 0)
+        self.assertTrue((self.home / '.codex/AGENTS.md').exists())
+        self.assertTrue((self.home / '.hermes/SOUL.md').exists())
+        self.assertFalse((self.home / '.claude').exists())
+        self.assertFalse((self.home / '.qoder').exists())
+        self.assertEqual(self.run_sync(), 0)
+        self.assertEqual(self.run_sync(['--check']), 0)
+        self.assertEqual(len(list((self.root / 'backups').iterdir())), 1)
+
+    def test_explicit_and_disabled(self):
+        """显式选择可以初始化入口，也可以覆盖自动同步时的禁用设置。"""
+        self.config({'claude': {'enabled': False}})
+        (self.home / '.claude').mkdir()
+        self.assertEqual(self.run_sync(), 0)
+        self.assertFalse((self.home / '.claude/CLAUDE.md').exists())
+        self.assertEqual(self.run_sync(['--agents', 'claude']), 0)
+        content = (self.home / '.claude/CLAUDE.md').read_text(encoding='utf-8')
+        self.assertIn('注释使用简体中文', content)
+        self.assertNotIn(str(self.root), content)
+
+    def test_env_overrides(self):
+        """三种官方主目录环境变量分别决定入口，未污染默认目录。"""
+        env = {name: str(self.base / name) for name in ['CODEX_HOME', 'CLAUDE_CONFIG_DIR', 'HERMES_HOME']}
+        for value in env.values():
+            Path(value).mkdir()
+        self.run_sync(env=env)
+        for key, filename in [('CODEX_HOME', 'AGENTS.md'), ('CLAUDE_CONFIG_DIR', 'CLAUDE.md'), ('HERMES_HOME', 'SOUL.md')]:
+            self.assertTrue((Path(env[key]) / filename).exists())
+        self.assertEqual(list(self.home.iterdir()), [])
+
+    def test_custom_agent_and_platform_paths(self):
+        """macOS、Windows、Linux 配置分支均选择本平台路径。"""
+        paths = {name: str(self.base / name / '中文规则.md') for name in ['macos', 'windows', 'linux']}
+        self.config({'extra': {'enabled': True, 'path': paths}})
+        for platform in paths:
+            self.run_sync(['--agents', 'extra'], platform=platform)
+            self.assertTrue(Path(paths[platform]).exists())
+
+    def test_native_windows_path_expansion(self):
+        """用 Windows 路径语义验证用户目录、反斜杠和环境变量。"""
+        home = PureWindowsPath('C:/Users/张 三')
+        base = PureWindowsPath('D:/规则工具')
+        with patch.object(sync, 'Path', PureWindowsPath):
+            self.assertEqual(sync.expand_path('~/.codex/AGENTS.md', home, {}, base), home / '.codex/AGENTS.md')
+            self.assertEqual(sync.expand_path('~\\.claude\\CLAUDE.md', home, {}, base), home / '.claude/CLAUDE.md')
+            self.assertEqual(sync.expand_path('%APPDATA%/extra/RULES.md', home, {'APPDATA': 'C:/Users/张 三/AppData/Roaming'}, base), home / 'AppData/Roaming/extra/RULES.md')
+            self.assertEqual(sync.expand_path('D:\\Agent\\RULES.md', home, {}, base), PureWindowsPath('D:/Agent/RULES.md'))
+
+    def test_local_override_and_command_detection(self):
+        """本机覆盖配置优先；命令存在时可初始化自定义规则文件。"""
+        self.config({'extra': {'path': '~/unused/RULES.md', 'commands': ['extra-cli']}})
+        self.config({'extra': {'path': '~/actual/RULES.md'}}, 'targets.local.json')
+        self.run_sync(which=lambda name: '/bin/extra-cli' if name == 'extra-cli' else None)
+        self.assertTrue((self.home / 'actual/RULES.md').exists())
+        self.assertFalse((self.home / 'unused').exists())
+
+    def test_preview_is_read_only(self):
+        """列表和预览不写文件；检查能发现不同步。"""
+        for flag in ['--list', '--dry-run', '--check']:
+            self.run_sync(['--agents', 'codex', flag])
+            self.assertEqual(list(self.home.iterdir()), [])
+            self.assertFalse((self.root / 'backups').exists())
+
+    def test_packaged_rules_are_used_without_source_config(self):
+        """安装后的 wheel 没有项目 config/ 时仍能使用包内共享规则。"""
+        packaged = self.base / 'package-data' / 'AGENTS.md'
+        packaged.parent.mkdir()
+        packaged.write_text('# 安装后的规则\n使用中文注释。\n', encoding='utf-8')
+        (self.root / 'AGENTS.md').unlink()
+        with patch.object(sync, 'PACKAGED_RULES', packaged):
+            self.assertEqual(self.run_sync(['--agents', 'codex']), 0)
+        content = (self.home / '.codex/AGENTS.md').read_text(encoding='utf-8')
+        self.assertIn('使用中文注释', content)
+
+    def test_preserve_crlf_bom_and_backup(self):
+        """保留原内容、Windows 换行和 BOM，并保存完全一致的备份。"""
+        target = self.home / '.hermes/SOUL.md'
+        target.parent.mkdir()
+        before = '\ufeff已有的人格设置。\r\n'.encode('utf-8')
+        target.write_bytes(before)
+        self.run_sync()
+        after = target.read_bytes()
+        self.assertTrue(after.startswith(before))
+        self.assertNotIn(b'\n', after.replace(b'\r\n', b''))
+        backup = next((self.root / 'backups').iterdir())
+        record = json.loads((backup / 'manifest.json').read_text(encoding='utf-8'))[0]
+        self.assertEqual((backup / record['backup']).read_bytes(), before)
+
+    def test_preflight_rejects_bad_markers_before_writes(self):
+        """任一文件的标记损坏时，不先修改其他入口。"""
+        target = self.home / '.hermes/SOUL.md'
+        target.parent.mkdir()
+        target.write_text(sync.BEGIN, encoding='utf-8')
+        with self.assertRaises(ValueError):
+            self.run_sync(['--agents', 'codex,hermes'])
+        self.assertFalse((self.home / '.codex').exists())
+
+    def test_duplicate_and_source_targets_rejected(self):
+        """配置不能让两个 Agent 写同一文件，也不能覆盖主规则。"""
+        shared = str(self.home / 'shared.md')
+        self.config({'one': {'enabled': True, 'path': shared}, 'two': {'enabled': True, 'path': shared}})
+        with self.assertRaises(ValueError):
+            self.run_sync()
+        self.assertFalse(Path(shared).exists())
+        self.config({'extra': {'enabled': True, 'path': str(self.root / 'AGENTS.md')}})
+        with self.assertRaises(ValueError):
+            self.run_sync()
+
+    def test_qoder_and_codex_override(self):
+        """Qoder 仅写全局始终应用规则；Codex 覆盖入口必须明确配置。"""
+        self.run_sync(['--agents', 'qoder'])
+        target = self.home / '.qoder/rules/ai-chinese-comments.md'
+        self.assertIn('trigger: always_on', target.read_text(encoding='utf-8'))
+        codex = self.home / '.codex'
+        codex.mkdir()
+        (codex / 'AGENTS.override.md').write_text('已有覆盖规范', encoding='utf-8')
+        with self.assertRaises(ValueError):
+            self.run_sync(['--agents', 'codex'])
+        self.assertFalse((codex / 'AGENTS.md').exists())
+
+    def test_rollback_on_second_write_failure(self):
+        """第二个写入失败时，第一个文件恢复为原内容。"""
+        first, second = self.home / 'first.md', self.home / 'second.md'
+        first.write_bytes(b'original')
+        real_write = sync.atomic_write
+        def fail_second(path, data, mode):
+            """模拟目标文件被占用或没有写权限。"""
+            if path == second:
+                raise PermissionError('模拟第二个入口写入失败')
+            real_write(path, data, mode)
+        with patch.object(sync, 'atomic_write', side_effect=fail_second), contextlib.redirect_stdout(io.StringIO()), contextlib.redirect_stderr(io.StringIO()):
+            with self.assertRaises(PermissionError):
+                sync.apply_changes([('first', first, b'original', b'new'), ('second', second, None, b'new')], self.root)
+        self.assertEqual(first.read_bytes(), b'original')
+        self.assertFalse(second.exists())
+
+    def test_legacy_and_unknown_agent_rejected(self):
+        """旧机器路径配置和拼错的 Agent 名称不会触发写入。"""
+        with self.assertRaises(ValueError):
+            self.run_sync(['--agents', 'unknown'])
+        (self.root / 'targets.json').write_text('{"codex":"/old/user/AGENTS.md"}', encoding='utf-8')
+        with self.assertRaises(ValueError):
+            self.run_sync()
+
+
+if __name__ == '__main__':
+    unittest.main()